Codeman

Name: Codeman
Author: Ark0N

Start, prompt and read coding agent sessions running in a self-hosted Codeman dashboard

By Ark0N (individual) TypeScript Local · stdio AI and ML Developer tools

GitHub npm Website

64 popularity score ★ 832 ↓ 4.3k/wk

Connect your client

Local (npm)

Add in one click

Add to Cursor Add to VS Code Add to LM Studio Add to Goose

Opens the app, which asks before it adds the server. Then replace each <NAME> in its settings with your value.

Or add it by command or config

It needs CODEMAN_API_URL. Replace each <NAME> with your value.

Claude CodeTerminal

claude mcp add codeman -e CODEMAN_API_URL=<CODEMAN_API_URL> -- npx -y aicodeman mcp

Claude Desktopclaude_desktop_config.json

{
  "mcpServers": {
    "codeman": {
      "command": "npx",
      "args": [
        "-y",
        "aicodeman",
        "mcp"
      ],
      "env": {
        "CODEMAN_API_URL": "<CODEMAN_API_URL>"
      }
    }
  }
}

Cursor~/.cursor/mcp.json

{
  "mcpServers": {
    "codeman": {
      "command": "npx",
      "args": [
        "-y",
        "aicodeman",
        "mcp"
      ],
      "env": {
        "CODEMAN_API_URL": "<CODEMAN_API_URL>"
      }
    }
  }
}

VS Code.vscode/mcp.json

{
  "servers": {
    "codeman": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "aicodeman",
        "mcp"
      ],
      "env": {
        "CODEMAN_API_URL": "<CODEMAN_API_URL>"
      }
    }
  }
}

Codex~/.codex/config.toml

[mcp_servers.codeman]
command = "npx"
args = ["-y", "aicodeman", "mcp"]

[mcp_servers.codeman.env]
CODEMAN_API_URL = "<CODEMAN_API_URL>"

Gemini CLITerminal

gemini mcp add --scope user -e CODEMAN_API_URL=<CODEMAN_API_URL> codeman npx -- -y aicodeman mcp

Local (from source)

Add in one click

Add to Cursor Add to VS Code Add to LM Studio

Opens the app, which asks before it adds the server. Then replace each <NAME> in its settings with your value.

Or add it by command or config

It needs CODEMAN_API_URL. Replace each <NAME> with your value.

FirstTerminal

git clone https://github.com/Ark0N/Codeman.git
cd Codeman
npm install
npm run build

Claude CodeTerminal

claude mcp add codeman -e CODEMAN_API_URL=<CODEMAN_API_URL> -- node '<ABSOLUTE_PATH_TO_CLONE>/dist/index.js' mcp

Claude Desktopclaude_desktop_config.json

{
  "mcpServers": {
    "codeman": {
      "command": "node",
      "args": [
        "<ABSOLUTE_PATH_TO_CLONE>/dist/index.js",
        "mcp"
      ],
      "env": {
        "CODEMAN_API_URL": "<CODEMAN_API_URL>"
      }
    }
  }
}

Cursor~/.cursor/mcp.json

{
  "mcpServers": {
    "codeman": {
      "command": "node",
      "args": [
        "<ABSOLUTE_PATH_TO_CLONE>/dist/index.js",
        "mcp"
      ],
      "env": {
        "CODEMAN_API_URL": "<CODEMAN_API_URL>"
      }
    }
  }
}

VS Code.vscode/mcp.json

{
  "servers": {
    "codeman": {
      "type": "stdio",
      "command": "node",
      "args": [
        "<ABSOLUTE_PATH_TO_CLONE>/dist/index.js",
        "mcp"
      ],
      "env": {
        "CODEMAN_API_URL": "<CODEMAN_API_URL>"
      }
    }
  }
}

Codex~/.codex/config.toml

[mcp_servers.codeman]
command = "node"
args = ["<ABSOLUTE_PATH_TO_CLONE>/dist/index.js", "mcp"]

[mcp_servers.codeman.env]
CODEMAN_API_URL = "<CODEMAN_API_URL>"

Gemini CLITerminal

gemini mcp add --scope user -e CODEMAN_API_URL=<CODEMAN_API_URL> codeman node -- '<ABSOLUTE_PATH_TO_CLONE>/dist/index.js' mcp

Settings 5

Set together: host session
`CODEMAN_API_URL`	Required: Address of the running Codeman server, e.g. http://127.0.0.1:3000 (https only when started with --https). Can also be passed as --url.
`CODEMAN_PASSWORD` secret	Optional: Codeman's HTTP Basic password, needed when the server has one set. Read from Codeman's data folder .env when unset.
`CODEMAN_USERNAME`	Optional: HTTP Basic user name sent with CODEMAN_PASSWORD. Default `admin`.
`CODEMAN_MUX`	Optional: Set to 1 inside a Codeman pane so the server knows the session it runs in (pass it through in Codex).
`CODEMAN_SESSION_ID`	Optional: Id of the Codeman session the MCP client runs in, read only when CODEMAN_MUX is 1.

What it does

Codeman is a self-hosted web dashboard that runs AI coding CLIs such as Claude Code, Codex, OpenCode, Gemini CLI, Grok and DeepSeek inside persistent tmux sessions. Its `codeman mcp` subcommand is a stdio MCP server that talks to a running Codeman instance over its HTTP API, so one assistant can hand work to other agents: open a new worker in any installed CLI, type a prompt into it, wait for the turn to finish and read back the reply, then close it.

The server adds no routes of its own. It uses the same API and password as the web dashboard, and workers show up there as tabs, so a person can watch or take over. A worker is started in a Codeman "case" (a folder). A new case name creates a fresh scratch folder, while an existing one runs the worker in that project. The run mode defaults to claude, and a plain shell is offered too.

A few things the README leaves out, read in src/mcp-server.ts and src/codeman-credentials.ts: read_output trims what it returns to 40,000 characters, and in terminal mode it reads the last 4000 bytes unless tail_bytes asks for anywhere from 100 to 200000. The Basic auth user is CODEMAN_USERNAME, which falls back to admin, and both it and CODEMAN_PASSWORD are looked up in Codeman's data folder .env when the environment lacks them. The README's client examples point CODEMAN_API_URL at https://127.0.0.1:3000, but a plain `codeman web` serves http on port 3000 unless started with --https, so use the address you open the dashboard at.

What it needs

Runtime	Node.js 22+
Runs on	macOS, Linux
Codeman	Your own instanceA running Codeman server (codeman web) the MCP server can reach at CODEMAN_API_URL
Also	tmux on the Codeman host At least one AI coding CLI installed and signed in (Claude Code, Codex, Gemini CLI and others)

Start Codeman with `codeman web` (localhost:3000 by default) before the MCP server is used. Windows works only through WSL. Building node-pty on Linux needs a compiler toolchain, which the getcodeman.com installer adds when missing.

Limits

Not covered Prompting, interrupting and deleting work only on sessions this server started (and its host session's own workers) unless launched with --allow-any-session
Not covered It never acts on the Codeman session it runs in. Listing, reading and waiting cover every session
Size cap A wait returns after 45 s by default and at most 600 s with timeout_ms. Codex cuts tools off at 60 s unless tool_timeout_sec is raised
Size cap send_prompt takes one line of printable text. Newlines and control characters are refused
Size cap read_output returns at most 40,000 characters
Limit Only claude and deepseek sessions report a definite end of turn. For other CLIs "finished" is guessed from a quiet screen
Limit Without CODEMAN_API_URL or --url it starts, but every call only explains how to configure it

Prompting, interrupting and deleting work only on sessions this server started (plus, inside a Codeman session, that session's own workers) unless it is launched with --allow-any-session; it never acts on the session it runs in. Listing, reading and waiting cover every session. A wait returns after 45 s by default and at most 600 s. send_prompt types a single line. read_output's last_answer and conversation come from transcripts only for claude, codex and deepseek sessions; other modes are read from the terminal. Without CODEMAN_API_URL or --url the server starts but every call only explains how to configure it.

Who it suits

Suits someone already running Codeman who wants an assistant in Claude Code, Codex, Cursor or Claude Desktop to farm out tasks to other agent CLIs on the same host and collect the answers, with every worker visible as a dashboard tab. It is a client of Codeman, not a standalone agent runner: without a Codeman server it does nothing. Because workers run with the CLIs' own logins and Codeman starts Claude sessions with --dangerously-skip-permissions by default, it suits a trusted single-user machine better than a shared one. Pick something else if you only need to call one model or do not want tmux-based sessions.

Tools 7

3 only read, 3 change things, 1 can delete or overwrite. A ? marks an optional parameter.

list_sessions: Lists visible Codeman sessions with mode, status, folder and whether this server may prompt them
start_session changes: Opens a new worker in an installed agent CLI or shell inside a new or existing case foldercase: stringmode?: enumname?: stringwait_ready?: boolean
send_prompt changes: Types a one-line prompt into a worker and presses Enter, by default waiting for the turn to endsession_id: stringtext: stringwait?: booleantimeout_ms?: integer
wait_for_session: Blocks until a session signals stop, blocked, idle, working or exit, or prints a given markersession_id: stringuntil?: arraymatch?: stringfrom?: enumtimeout_ms?: integer
read_output: Returns a worker's last reply, the whole conversation, or the tail of its terminalsession_id: stringsource?: enumtail_bytes?: integer
interrupt_session changes: Sends one Escape to stop the current turn while keeping the conversationsession_id: string
delete_session deletes: Closes a worker session and leaves its case folder in placesession_id: string

Popularity

64 popularity score, on our list (the bar is 36)

★ 832 ↓ 4.3k/wk

GitHub stars	832	35 points
npm downloads, last week	4,292	29.1 points

Measured 2026-11-07. How the score works.

Where it is published

Code	ark0n/codeman ★ 832
npm	aicodeman 1.49.0, 2026-11-06

What it can reach

Runs	On your machine
Reaches	Runs shell commands, Your code, Files on your machine, The internet
Changes things	Yes: it can write, send, create or delete
Sign-in	None
Licence	MIT (npm)
Last code change	2026-11-06

Runs on your machine as a stdio process and sends HTTP requests to the Codeman server named in CODEMAN_API_URL, using HTTP Basic auth when CODEMAN_PASSWORD is set. Its tools start and delete tmux sessions on the Codeman host, including plain shells, and type prompts into them, so an assistant using it can have agent CLIs edit files and run commands under the user's own CLI logins. Codeman launches Claude sessions with --dangerously-skip-permissions by default (configurable in its settings), and its README calls the web UI a remote-code-execution surface for whoever can reach it. The MCP server limits prompting, interrupting and deleting to its own workers unless --allow-any-session is given; reading output is open for every session.

Over time

GitHub stars 832 +38 (+5 %)

832794

14 Oct 20267 Nov 2026

npm downloads a week 4.3k +3.5k (+429 %)

6.6k226

9 Mar 20267 Nov 2026

Before the site measured it, read from npm's daily download counts.

Popularity score 64 −1 (−2 %)

6558

14 Oct 20267 Nov 2026

What is rising across the directory

Sources

Page checked 2026-11-02.

Badge for your README

Shows this server's rank in its category, and stars for a server that runs on your machine. It updates every hour.

MarkdownREADME.md

[![Codeman on EveryMCPServer](https://everymcpserver.com/badge/codeman.svg)](https://everymcpserver.com/servers/codeman)

Connect your client

Add in one click

Or add it by command or config

Add in one click

Or add it by command or config

Settings 5

What it does

What it needs

Limits

Who it suits

Tools 7

Similar servers

Claudish

ReevesAgents

AgentRQ

opencode-mcp

Crewly

Prism Coder