# Codeman > >- - **Type:** Skill - **Install:** `agentstack add skill-ark0n-codeman-codeman` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [Ark0N](https://agentstack.voostack.com/s/ark0n) - **Installs:** 0 - **Category:** [Cloud & Infrastructure](https://agentstack.voostack.com/c/cloud-infrastructure) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [Ark0N](https://github.com/Ark0N) - **Source:** https://github.com/Ark0N/Codeman/tree/master/skills/codeman - **Website:** https://getcodeman.com ## Install ```sh agentstack add skill-ark0n-codeman-codeman ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # Driving Codeman from inside a session You are an agent running inside a Codeman-managed terminal session. Codeman is the server that spawned you; its HTTP API can start, prompt, watch, and delete other sessions. **Read as far as your job needs and no further.** §0 is the bootstrap, run once. §1 is the whole fast path: spawn N workers, task them, collect answers. **If §1 covers your job, run it and stop there.** The sections after it are for jobs it does not cover, and reading them to be thorough is the main reason a ten-second run takes minutes. §2 is the verb table when your job is a different one. §3 and §4 are the rules; §6 is setup and credentials, which you only need when something 401s. Everything else loads on demand, and is meant to be opened at one section, not read through: the verbs in detail (the old §5) in [reference/verbs.md](reference/verbs.md), worked multi-worker flows in [reference/recipes.md](reference/recipes.md), endpoint tables and a symptom gallery in [reference/endpoints.md](reference/endpoints.md), and direct messaging to claude workers in [reference/messaging.md](reference/messaging.md). ## 0. Guard and bootstrap If `CODEMAN_MUX` is not `1`, **stop and say so**. Do not guess an API URL; a server you are not part of is not yours to drive. ⚠️ **Your shell state does not survive between tool calls.** Each Bash call starts a fresh shell, so `$API`, `$SELF`, the `CURL` array and `delete_session` are all gone by the next call, and `$$` is a different pid. **The filesystem does survive**, so write the preamble to a file once and source it afterwards, rather than re-pasting a hundred-odd lines at the top of every call (a half-re-pasted preamble used to be the single most likely way to break a run). **Codeman seeds the preamble file for you** when it spawns a claude session (server 1.18.3+), so the bootstrap is usually nothing at all: these are the two lines every later call opens with, and your first REAL call performs them anyway: ```bash . "${XDG_CACHE_HOME:-$HOME/.cache}/codeman-agent-$CODEMAN_SESSION_ID.sh" 2>/dev/null [ "${CODEMAN_PREAMBLE:-}" = 1.22.0 ] || { echo "preamble missing or stale; run the full §0 block"; exit 1; } ``` ⚠️ **Never spend a Bash call on this check alone.** §1's block opens with this same loader, so when §1 is the job, start there: the check rides the spawn call for free, and a standalone "preamble OK" call buys nothing while costing a full model turn (measured live: a lone check plus the deliberation around it added ~6 s to a 28 s two-worker run). §0 is done the moment any job call passes its opening check. Only when a call reports missing or stale, run the full block below once — and run it **verbatim**: paste it as-is, never re-type it, trim it, or "extract the parts you need". A hand-assembled preamble is the documented failure mode of this skill: one live run rebuilt it "minimally" and lost the `X-Codeman-Parent-Session` header (every worker spawned with no lineage arc in the web UI) and the fast-path functions (the spawn fell back to a serial quick-start loop plus pid polls), turning a ten-second job into a fifty-second one. If your harness directs temporary files into a scratchpad directory, that directive covers task scratch, not this file: it is a per-session cache that every later call re-sources by this exact path, so keep the path below. If you must relocate it anyway, copy the block's content byte-for-byte unchanged and source your path in every later call instead. ```bash test "${CODEMAN_MUX:-}" = 1 || { echo "Not inside a Codeman-managed session; refusing to act."; exit 1; } : "${CODEMAN_SESSION_ID:?CODEMAN_SESSION_ID not set}" "${HOME:?HOME not set}" PRE="${XDG_CACHE_HOME:-$HOME/.cache}/codeman-agent-$CODEMAN_SESSION_ID.sh" mkdir -p "$(dirname "$PRE")" # Rewrite unless the file already ends with THIS version's stamp, so a stale or a # half-written file self-heals here instead of costing you a round trip to rm it. grep -qs '^CODEMAN_PREAMBLE=1.22.0$' "$PRE" || (umask 077; cat > "$PRE" -> "true"/"false". `shift+tab` is the one token "${CURL[@]}" -G "$API/api/v1/sessions/$1/wait-output" \ --data-urlencode 'match=shift+tab' --data-urlencode 'from=buffer' \ --data-urlencode "timeout=$2" | jq -r '.data.wait.matched // false' } _dsh_up() { # -> "true"/"false". The DeepSeek Harness TUI's # composer glyph. Override with DSH_READY_MARK for a profile that draws another one. "${CURL[@]}" -G "$API/api/v1/sessions/$1/wait-output" \ --data-urlencode "match=${DSH_READY_MARK:-❯}" --data-urlencode 'from=buffer' \ --data-urlencode "timeout=$2" | jq -r '.data.wait.matched // false' } # ---- the workspace-trust dialog: READ the screen, never press Enter blind ---- # Claude Code 2.1.252 dropped the option numbers, REVERSED them, and highlights # "No, exit" by default: # Security guide # ❯ No, exit # Yes, I trust this folder # Enter to confirm . Esc to cancel # so the bare \r that answered the old layout now answers *exit* and the pane is # dead (`status 1`) seconds after the spawn -- measured on a live 2.1.252 case. # These two read the rendered pane and steer onto the trust option instead. _trust_key() { # -> "confirm" | "move" | "" (nothing safe to press) # full=1 returns the RENDERED pane; a claude pane keeps no tmux history, so that # is the current frame rather than every repaint since launch. tail -1 anyway, # because the freshest marked row is the only one still true. "${CURL[@]}" -G "$API/api/v1/sessions/$1/terminal" --data-urlencode 'full=1' \ | jq -r '.data.terminalBuffer // empty' \ | sed -e "s/$(printf '\033')\[[0-9;?]*[a-zA-Z]//g" -e "s/$(printf '\033')[()][AB0]//g" \ | tr -d ' \t' | grep -i '❯[0-9.]*\(yes,itrustthisfolder\|no,exit\)' | tail -1 \ | sed -e 's/.*[Yy]es,.*/confirm/' -e 's/.*[Nn]o,.*/move/' } _accept_trust() { # -> 0 once it has answered the dialog, 1 if it could not local sid="$1" k i=1 while [ "$i" -le 6 ]; do k=$(_trust_key "$sid") [ -n "$k" ] || return 1 # no dialog on screen, or a layout this cannot read # A SEPARATE clientId for these keys. seq is monotonic per clientId, so # spending prompt numbers here would make the next sendwait -- whose default # seq is the epoch second -- look like a stale duplicate and vanish silently. "${CURL[@]}" -X POST "$API/api/v1/sessions/$sid/input" -H 'Content-Type: application/json' \ -d "$(jq -nc --arg k "$([ "$k" = confirm ] && printf '\r' || printf '\033[B')" \ --arg c "$CID-trust-$sid" --argjson s "$i" \ '{input:$k,useMux:true,clientId:$c,seq:$s}')" >/dev/null [ "$k" = confirm ] && return 0 sleep 1; i=$((i+1)) # re-read: the arrow is CONFIRMED before Enter goes out done return 1 } # spawn_worker [mode] -> session id on stdout, diagnostics on stderr. # quick-start AND readiness in one call, with a strict contract: NON-EMPTY stdout means # a READY worker whose end-of-turn signal can be trusted -- a claude worker in a # hook-carrying case, or a `deepseek` worker whose harness TUI drew its composer. # Anything less is rc 1 with EMPTY stdout, and the half-spawned session is deleted here # rather than handed back, because a worker that never drew its composer would eat the # task prompt with its trust dialog. There is deliberately no pid poll: wait-output # already blocks until the composer draws, and pid!=null proved startup, never readiness. spawn_worker() { local name="${1:?spawn_worker needs a case name}" mode="${2:-claude}" q sid cp r # parentSessionId doubles the CURL header, so a spawn_worker copied off the shared # curl (or a body someone rebuilt from this recipe) still carries its lineage. # deepseek: ask for the same permission posture the Run button sends, because the # harness's own default (`workspace-write`) still ASKS, and a worker that stops on # an approval row is a worker no fan-out can finish. It is not an escalation -- # claude workers already spawn with permissions skipped, and in multi-user mode the # server clamps this back to `workspace-write` for an owner without the grant. # Spawn by hand (§5.1) when you want a worker that asks. q=$("${CURL[@]}" -X POST "$API/api/v1/quick-start" -H 'Content-Type: application/json' \ -d "$(jq -nc --arg n "$name" --arg m "$mode" --arg p "$SELF" \ '{caseName:$n,mode:$m,parentSessionId:$p} + (if $m == "deepseek" then {deepSeekConfig:{permissionMode:"danger-full-access"}} else {} end)')") sid=$(jq -r 'if .success then .data.sessionId else empty end' &2; return 1; } if [ "$mode" = deepseek ]; then # The one non-claude mode with REAL end-of-turn signals: its TUI reports # idle/working/blocked to Codeman, so sendwait, until=stop and the Approvals # Inbox all work here exactly as they do for claude. No hook file to vet # (the bridge is env-injected, not a workspace file) and no trust dialog. # ⚠️ Readiness is still not optional, and NOT interchangeable with the stop # signal: the harness's boot report lands ~300ms BEFORE the composer paints # (measured 2.26s vs 2.56s after spawn), so a sendwait fired straight after # quick-start returns on that BOOT signal, reports a turn that never ran, and # strands the prompt in a pane that was not yet taking input. r=$(_dsh_up "$sid" 45000) [ "$r" = true ] || { echo "dsh worker $sid never drew a composer: no pane-capable profile, a profile whose composer is not '${DSH_READY_MARK:-❯}' (set DSH_READY_MARK), or a harness that failed to boot -- check GET /api/v1/deepseek/status. Deleted it" >&2 delete_session "$sid" >/dev/null; return 1; } printf '%s\n' "$sid"; return 0 fi [ "$mode" = claude ] || { printf '%s\n' "$sid"; return 0; } # no other mode draws a composer to wait on # The server installs hooks into every claude workspace now, so this grep normally # passes; it stays because the install is gated on a setting the operator can turn # off, remote sessions never get hooks, and a session created by an older server # still has none. No marker means sendwait would false-resolve on flapping idle, # possibly inside the user's REAL repo: refuse rather than run the job there. cp=$(jq -r '.data.casePath // empty' &2 delete_session "$sid" >/dev/null; return 1; } # Short composer wait FIRST, then the trust dialog: a case still showing the # dialog can never pass the composer wait, so acting early keeps a cold case from # paying the whole long wait before the fallback even runs (§5.2). A warm case # matches in under a second and never reaches it, and _accept_trust returns in a # blink when there is no dialog, so this costs nothing in the ordinary slow case. r=$(_composer_up "$sid" 5000) if [ "$r" != true ]; then # Codeman answers this dialog itself and normally wins the race; this is the # bounded fallback for when its 90 s window / 6-keystroke cap has run out. _accept_trust "$sid" r=$(_composer_up "$sid" 45000) fi [ "$r" = true ] || { echo "worker $sid never drew a composer; deleted it. Retry by hand via the §5.2 ladder (its billed stage-4 probe included)" >&2 delete_session "$sid" >/dev/null; return 1; } printf '%s\n' "$sid" } # spawn_workers ... -> one " " line per worker, in # order; the sessionId column is EMPTY for a spawn that failed (stderr has why). # CONCURRENT: N workers cost about what one costs. Spawning them one Bash call at a time # is the single biggest avoidable delay in this skill. A bare name is a claude worker; # `beta:deepseek` makes that one a DeepSeek Harness worker, and a mixed fleet is one # call. Case names must be UNIQUE: two workers in one case directory co-edit the same # tree (§4), so a repeat is an error here, not a race (the mode never disambiguates two # workers, since they would still share the directory). spawn_workers() { local d spec n m i=0 [ "$#" -gt 0 ] || { echo "spawn_workers: no case names given" >&2; return 1; } [ -z "$(printf '%s\n' "$@" | sed 's/:.*//' | sort | uniq -d)" ] || { echo "spawn_workers: duplicate case names" >&2; return 1; } d=$(mktemp -d "${TMPDIR:-/tmp}/codeman-spawn.XXXXXX") || return 1 for spec in "$@"; do n=${spec%%:*}; m=${spec#*:}; [ "$m" = "$spec" ] && m=claude ( spawn_worker "$n" "$m" > "$d/$i" ) & i=$((i+1)) done wait i=0; for spec in "$@"; do printf '%s %s\n' "${spec%%:*}" "$(cat "$d/$i" 2>/dev/null)"; i=$((i+1)); done rm -rf "$d" } # sendwait [seq] -> blocks until that worker's turn ENDS (~10 min ceiling # across its two waits). One billed turn. The \r and the per-worker clientId are applied # here, which is why you never hand-build this body. seq defaults to the CURRENT EPOCH # SECOND so that every new prompt is a new frame: the server drops any (clientId,seq) # pair it has already applied, so a fixed default would make every later prompt to that # worker a silent no-op that still "succeeds" and reports the previous turn's state. # Pass seq explicitly for exactly one reason: resending a possibly-delivered frame as a # deliberate duplicate, at the SAME number (§5.3). # Delivery is SELF-HEALING: an Ink repaint occasionally eats the Enter, leaving the # typed prompt stranded on the composer while a long wait runs its whole timeout # (observed live). So the first wait is short; on its timeout a bare \r goes out (the # missing Enter when the prompt is stranded, a no-op when the turn is genuinely # running), then the ORIGINAL frame is resent unchanged, which the server takes as a # tagged duplicate: it re-waits without retyping (§5.3). Trustworthy for a worker # spawn_worker handed back -- claude (hooks vetted) or deepseek (status bridge) -- # and for those only. Hook-less workspaces and the other modes resolve on flapping # idle: markers instead (§5.5). ⚠️ A dsh worker running a profile that does not # implement the status contract is the one case that LOOKS like claude but is not: # it accepts the send and then burns both waits. One timeout on a dsh worker whose # pane clearly finished means that profile, so switch that worker to markers. sendwait() { local sid="${1:?}" p="${2:?}" seq="${3:-$(date +%s)}" body r # `wait:"stop,exit"`, never the `wait:true` default set: that set also carries # `idle`, which is INFERRED from output stabilization and flaps mid-turn. On a # dsh worker whose TUI repaints rarely the session reads `idle` while the model # is still answering, and the re-wait below then resolved in 0 ms with # `signal:"idle"` on a turn that had another three minutes to run (measured). # A wait named after the end of a turn should only end with the turn, or with # the worker. ⚠️ This is also what makes a wrong mode LOUD: the modes that # cannot deliver `stop` answer 400 (before writing anything) instead of # resolving on a flap, which is the answer that sends you to markers (§5.5). body=$(jq -nc --arg p "$p" --arg c "$CID-$sid" --argjson s "$seq" \ '{input:($p+"\r"),useMux:true,clientId:$c,seq:$s,wait:"stop,exit",waitTimeout:20000}') r=$("${CURL[@]}" -X POST "$API/api/v1/sessions/$sid/input" \ -H 'Content-Type: application/json' --data-binary "$body") if jq -e '.data.delivered and .data.wait.timedOut' /dev/null 2>&1; then "${CURL[@]}" -X POST "$API/api/v1/sessions/$sid/input" -H 'Content-Type: application/json' \ -d "$(jq -nc --arg c "$CID-$sid" --argjson s "$(date +%s)" \ '{input:"\r",useMux:true,clientId:$c,seq:$s}')" >/dev/null # The resend is a tagged DUPLICATE, so the server skips the write and reports # `delivered:false` for it -- truthfully, but about the wrong send. The first # one delivered, so carry that forward, or §1's cleanup reads a completed turn # as an undelivered one and keeps a finished worker forever. r=$("${CURL[@]}" -X POST "$API/api/v1/sessions/$sid/input" \ -H 'Content-Type: application/json' --data-binary "$(jq -c '.waitTimeout=580000' [prev] -> that worker's last assistant message … ## Source & license This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [Ark0N](https://github.com/Ark0N) - **Source:** [Ark0N/Codeman](https://github.com/Ark0N/Codeman) - **License:** MIT - **Homepage:** https://getcodeman.com Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** yes - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** yes - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/skill-ark0n-codeman-codeman - Seller: https://agentstack.voostack.com/s/ark0n - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.