codeman

# 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). Workers in **every other mode** never receive this preamble, but they have the same environment: tell them *"other sessions: `codeman agent --help`"* — the bundled CLI (`ls`, `spawn`, `send`, `wait`, `read`, `interrupt`, `rm`) is the same verbs over the same endpoints, with the guards below (no control bytes, no self-delete, no guessed URL) enforced in code. ## 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.33.4 ] || { 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.33.4$' "$PRE" || (umask 077; cat > "$PRE" <<'PREAMBLE' # ---- Codeman agent preamble 1.33.4 (seeded by Codeman at session spawn; the SKILL.md §0 bootstrap rewrites it when missing or stale) ---- API="${CODEMAN_API_URL:?CODEMAN_API_URL not set; refusing to guess}" SELF="${CODEMAN_SESSION_ID:?CODEMAN_SESSION_ID not set}" # Credentials, cheapest first. Your session has usually INHERITED the server's # CODEMAN_PASSWORD already (§6 explains why, and what to do when it has not); # the data dir's .env is the documented fallback, the same one `codeman attach` # reads. The data dir is wherever the hook-secret file lives. Values may be # quoted or `export`-prefixed. ENV_FILE="${CODEMAN_HOOK_SECRET_FILE:+${CODEMAN_HOOK_SECRET_FILE%hook-secret}.env}" envval() { sed -n "s/^\(export \)\{0,1\}$1=//p" "$ENV_FILE" | tail -1 | sed 's/^"\(.*\)"$/\1/; s/^'\''\(.*\)'\''$/\1/'; } if [ -z "${CODEMAN_PASSWORD:-}" ] && [ -n "$ENV_FILE" ] && [ -f "$ENV_FILE" ]; then CODEMAN_USERNAME=$(envval CODEMAN_USERNAME) CODEMAN_PASSWORD=$(envval CODEMAN_PASSWORD) fi AUTH=(); [ -n "${CODEMAN_PASSWORD:-}" ] && AUTH=(-u "${CODEMAN_USERNAME:-admin}:$CODEMAN_PASSWORD") # -k: harmless on http, required on https (self-signed cert). # X-Codeman-Parent-Session: tags workers YOU spawn as your children, so the web UI can # draw the lineage. Set once here and every present and future create call carries it; # it is ignored on every other endpoint. Purely cosmetic (see §5.1) and it can never # fail a spawn, so there is no case where you would want to leave it off. # X-Codeman-Agent-Origin: marks a case directory a spawn CREATES as agent scratch, so the # user can find and delete it long after your workers are gone (§5.14). Same deal: set # once, cosmetic, never fails a spawn, and it labels only directories Codeman creates. CURL=(curl -sk "${AUTH[@]}" -H "X-Codeman-Parent-Session: $SELF" -H "X-Codeman-Agent-Origin: codeman-skill") CID=codeman-agent-1 # FIXED literal, never "agent-$$": see below # Fail-CLOSED session delete. The DELETE lives INSIDE the guard on purpose: the older # `is_self "$SID" || curl -X DELETE ...` shape failed OPEN, because an undefined # is_self exits 127 and the `||` branch then ran the delete completely unguarded. # Undefined delete_session is "command not found", which deletes nothing. delete_session() { local id="${1:-}" [ -n "$id" ] || { echo "refusing: empty session id"; return 1; } [ "${#SELF}" -ge 8 ] || { echo "refusing: \$SELF unset or too short to prove this is not me"; return 1; } # ids appear in full AND 8-char form (Docker exports a truncated $SELF; mux names and # UI surfaces carry 8-char ids), so compare by prefix in BOTH directions. Equality or # a one-directional check each miss a real combination, and the miss deletes you. case "$id" in "$SELF"*) echo "refusing: $id is me"; return 1 ;; esac case "$SELF" in "$id"*) echo "refusing: $id is me"; return 1 ;; esac "${CURL[@]}" -X DELETE "$API/api/v1/sessions/$id" } # ---- fast path: the four verbs, already written. §1 composes them. ---- _composer_up() { # <sid> <timeoutMs> -> "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() { # <sid> <timeoutMs> -> "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() { # <sid> -> "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/' } # ---- the composer: is the prompt still sitting there, unsent? ---- # ⚠️ Claude Code 2.1.277 (auto-installed 2026-09-18) takes typed text the moment the # composer paints but IGNORES Enter for the first 30-50 seconds after it: the \r that # Codeman sends 50 ms after the text and a lone nudge at 20 s both leave the prompt # stranded, with `0 tokens`, while the wait burns its whole timeout. Measured through # this very route: Enter at 28 s stranded, Enter at 51 s submitted. So sendwait READS # the composer and keeps pressing Enter while the prompt is still there. _composer_text() { # <sid> -> the composer's text with ALL whitespace removed: "" once # the prompt was taken, "?" when the pane shows no composer at all. The composer is # the LAST `❯` line: Claude Code echoes a submitted prompt with the same glyph higher # up in the transcript, so only the last one says whether the text was taken. local t t=$("${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 '\r' | grep -a '^[[:space:]]*❯' | tail -1) [ -n "$t" ] || { printf '?'; return 0; } # Claude Code draws a NO-BREAK SPACE (U+00A0) after the glyph, which [:space:] does # not cover, so it is stripped by its bytes, portably (BSD sed has no \xHH). printf '%s' "$t" | sed 's/^[[:space:]]*❯//' | tr -d '[:space:]' | sed "s/$(printf '\302\240')//g" } _accept_trust() { # <sid> -> 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 <caseName> [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. # CODEMAN_WORKER_ADVISOR=opus (or fable / sonnet) gives every CLAUDE worker spawned while # it is set Claude Code's advisor tool: a stronger model the worker consults before # committing to an approach, on a recurring error and before declaring the task done. # Other modes ignore it. A value the server refuses fails the spawn (INVALID_INPUT); an # advisor that ranks below the worker's model is accepted but never attached by claude. 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' \