mirror of
https://github.com/Ark0N/Codeman.git
synced 2026-11-16 11:19:33 +01:00
The opencode readiness and marker measurements were made on Linux, not on a Mac, and the docs now say so. A worker whose pane ends after it wrote its answer file but before the marker matched answers 3 with no answer: the rc 3 row now says the file may still be in its folder. The example's input folder is named input, so the prompt reads cleanly. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
1122 lines
78 KiB
Markdown
1122 lines
78 KiB
Markdown
---
|
||
name: codeman
|
||
description: >-
|
||
Drive Codeman, the session manager this agent is running inside, over its HTTP API,
|
||
from any agent CLI (Claude Code, Codex, Gemini CLI, OpenCode, Antigravity, Grok
|
||
Build, DeepSeek Harness, OMP): list sessions, start worker sessions in any installed
|
||
CLI, send them prompts, block until they finish (wait / wait-output / send-and-wait),
|
||
read their output, and clean up; where available, message claude workers directly
|
||
(Claude Code cross-session messaging). Use when asked to orchestrate or parallelize
|
||
work across Codeman sessions, get a second opinion from another CLI or model, hand
|
||
work to the local model Codeman installed on this Mac ("use the local model"), watch
|
||
another session, start and manage workers, or retrieve saved local Codex history
|
||
by file/native ID or root and descendants with topic/date filters. Live API
|
||
operations require a Codeman-managed session (CODEMAN_MUX=1). Offline history
|
||
reads do not require a server or managed session.
|
||
---
|
||
|
||
# Driving Codeman from inside a session
|
||
|
||
For **saved Codex conversation history**, use `codeman history read` and
|
||
[reference/history.md](reference/history.md). This is a read-only local command:
|
||
route to it **before §0**, including outside a managed session. It needs no API
|
||
URL, credentials or running server. All live API operations below retain §0.
|
||
|
||
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).
|
||
Experimental bounded inspection and guarded stage/submit load only when needed from
|
||
[reference/inspection-and-staging.md](reference/inspection-and-staging.md).
|
||
|
||
This skill works the same whichever CLI you are: Codeman puts it where each CLI looks
|
||
for skills (`.claude/skills/` for Claude Code, `.agents/skills/` for Codex, Gemini CLI,
|
||
OpenCode, Antigravity, Grok, DeepSeek and OMP). A **pi** or **shell** worker never gets
|
||
it, but has the same environment: tell it *"other sessions: `codeman agent --help`"*.
|
||
That bundled CLI (`ls`, `spawn`, `send`, `wait`, `read`, `inspect`, `stage`, `submit`,
|
||
`interrupt`, `rm`, and the inbox verbs `post`, `inbox`, `ack`) is the same
|
||
verbs over the same endpoints, with the guards below (no control bytes, no self-delete,
|
||
no guessed URL) enforced in code, and it is also your own way through when this
|
||
machine has no `jq` for the preamble below.
|
||
|
||
For an existing project, use one command:
|
||
`codeman agent spawn --working-dir /path/to/project --mode codex`. With no case and
|
||
no `--working-dir`, `spawn` uses cwd. Give editing workers separate worktrees. A
|
||
positional case keeps quick-start behavior and cannot be combined with
|
||
`--working-dir`; an empty `--working-dir` (`"$WT"` unset) refuses with exit 4
|
||
rather than falling back to cwd, and a cwd that is HOME refuses too (hooks would
|
||
land in `~/.claude`; pass `--working-dir ~` to mean it). Directory launches keep parent lineage and never
|
||
mark the project as agent scratch. If startup fails or is ambiguous, the CLI
|
||
reports the exact created ID: inspect it before retrying or cleaning up.
|
||
|
||
**`codeman: command not found` is not a dead end.** Some installs (a server run from a
|
||
source checkout, for one) put no `codeman` on PATH. Do not stop there: §0 and §1 below
|
||
are the same verbs over `curl`, and need nothing but `curl` and `jq`.
|
||
|
||
## 0. Guard and bootstrap
|
||
|
||
For live API operations, 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.
|
||
|
||
Two failures come from your CLI, not from Codeman: name them to the user instead of
|
||
retrying.
|
||
|
||
- **Every call fails at once with "couldn't connect", "connection refused" or `connect
|
||
EPERM`.** Your CLI's sandbox blocks network access, even to this machine. If your CLI
|
||
can ask the user to run a command outside its sandbox (Codex can), re-run **the same
|
||
command** once that way, never a different one; if the user declines, stop. For lasting
|
||
access in Codex, the user turns on **Allow network access** (Codeman App Settings,
|
||
Codex) and starts a new Codex session. Tell them what it costs first: it applies to
|
||
every new local Codex session, and commands in Codex's sandbox can then call Codeman's
|
||
API, which can start a session outside the sandbox with no approval prompt, even when
|
||
a password is set. It opens the network wherever Codex runs the folder workspace-write
|
||
and does not change the sandbox mode: a folder Codex runs read-only keeps the network
|
||
closed, so each call still needs the per-command approval (or `/permissions`).
|
||
**Bypass approvals and sandbox** works everywhere but drops the sandbox and approvals.
|
||
- **`"${CURL[@]}" -o /dev/null -w '%{http_code}' "$API/api/v1/sessions/$SELF"` prints
|
||
`404`.** The commands you run do not carry this session's environment: Codex can run them in a shared background
|
||
process another session started, so `$CODEMAN_SESSION_ID` (and with it `$SELF` and
|
||
the delete guard) is that session's. Delete nothing; tell the user. Codeman starts a
|
||
local Codex 0.162 or later with `--no-daemon` to prevent this, so seeing it means a
|
||
Codex started without that flag: an older Codex, a local session whose version Codeman
|
||
could not read, a remote or Docker session, or a server that predates it.
|
||
|
||
⚠️ **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 your session (claude since
|
||
server 1.18.3, the other CLIs since this skill reached them), 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.50.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.50.0$' "$PRE" || (umask 077; cat > "$PRE" <<'PREAMBLE'
|
||
# ---- Codeman agent preamble 1.50.0 (seeded by Codeman at session spawn; the SKILL.md §0 bootstrap rewrites it when missing or stale) ----
|
||
# Positional parameters are always written with braces, ${1} and never a bare dollar-digit: Claude Code
|
||
# replaces a bare one in a skill body with the matching word of the skill's arguments, and §0 is pasted
|
||
# from that body (test/agent-skill.test.ts pins it).
|
||
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.
|
||
# The agent inbox reads it too, as "who is calling" (§5.15); every other endpoint ignores
|
||
# it. 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'
|
||
}
|
||
_mark_up() { # <sid> <mark> <timeoutMs> -> "true"/"false": a literal, space-free token
|
||
# in the pane's output, read from the buffer so a composer drawn before the wait counts.
|
||
"${CURL[@]}" -G "$API/api/v1/sessions/${1}/wait-output" \
|
||
--data-urlencode "match=${2}" --data-urlencode 'from=buffer' \
|
||
--data-urlencode "timeout=${3}" | 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.
|
||
_mark_up "${1}" "${DSH_READY_MARK:-❯}" "${2}"
|
||
}
|
||
# ---- 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
|
||
}
|
||
# ---- the local model: the model Codeman installed on this Mac, as a worker ----
|
||
# local_model -> ONE compact JSON object on stdout. rc 0 only when a `local` worker can be
|
||
# spawned now (`running:true`) or once spawn_worker has started the runtime (`running:false`):
|
||
# {"spawnable":true,"state":"installed","running":true,"cli":"opencode","cliLabel":"OpenCode",
|
||
# "endpointId":"local-ollama","modelId":"<id>","modelLabel":"<label>"}
|
||
# Otherwise rc 1 and {"spawnable":false,"reason":"<reason>","message":"<why>",...}, the reason
|
||
# one of: not-mac, not-installed, install-unfinished, blocked (installed, but the server
|
||
# refuses a session now: the model changed on disk, another program holds the port, the
|
||
# runtime does not start), admin-only (multi-user mode, 403), unsupported (a Codeman without
|
||
# local models, 404), unauthorized (401, §6), unreachable, error.
|
||
# One GET of an EXPERIMENTAL route. It downloads, installs and starts nothing: installing is
|
||
# a person's decision, made in Codeman's "Run a local model" window.
|
||
local_model() {
|
||
local r code body out
|
||
r=$("${CURL[@]}" -w '\n%{http_code}' "$API/api/v1/local-model")
|
||
code=${r##*$'\n'}; body=${r%$'\n'*}
|
||
case "$code" in
|
||
200) out=$(jq -c '
|
||
def say: (.text // "") as $t
|
||
| reduce ((.vars // {}) | to_entries[]) as $e ($t; gsub("\\{" + $e.key + "\\}"; $e.value));
|
||
.data as $d | ($d.install // {}) as $i | ($i.actions // []) as $a
|
||
| {state:$i.state, running:($i.running == true), cli:$i.cli, cliLabel:$i.cliLabel,
|
||
endpointId:$i.endpointId, modelId:$i.model.id, modelLabel:$i.model.label} as $base
|
||
| if ($d | type) != "object" then {spawnable:false, reason:"error", message:"no data in the answer"}
|
||
elif $i.state == "installed" then
|
||
# `start` alone over-promises: it is offered too while another program holds the
|
||
# port. Only an error-free start is a runtime spawn_worker can bring up.
|
||
if ($i.cli and $i.endpointId and $i.model.id)
|
||
and (($a | index("start-session")) != null or (($a | index("start")) != null and $i.error == null))
|
||
then {spawnable:true} + $base
|
||
else {spawnable:false, reason:"blocked", errorCode:$i.error.code,
|
||
message:(if $i.error then ($i.error.message | say)
|
||
else "The model is installed, but the server offers no session on it right now." end)} + $base
|
||
end
|
||
elif $d.recommendation.reason == "not-macos" then
|
||
{spawnable:false, reason:"not-mac",
|
||
message:("Local models need a Mac with Apple silicon, and this Codeman runs on " + ($d.hardware.platform // "another system") + ".")}
|
||
elif $i.state == "idle" then
|
||
{spawnable:false, reason:"not-installed",
|
||
message:("No local model is installed. " + (if $d.recommendation.verdict == "none" then ($d.recommendation.headline | say)
|
||
else "A person installs one with Run a local model on the Codeman welcome screen." end))}
|
||
else
|
||
{spawnable:false, reason:"install-unfinished", step:$i.step, errorCode:$i.error.code,
|
||
message:("The install is " + ($i.state // "unfinished") + (if $i.step then " at its " + $i.step + " step" else "" end)
|
||
+ (if $i.error then ": " + ($i.error.message | say) else "." end)
|
||
+ " Only the Run a local model window continues it.")} + $base
|
||
end
|
||
| with_entries(select(.value != null))' <<<"$body" 2>/dev/null) ;;
|
||
000) out=$(jq -nc --arg a "$API" '{spawnable:false,reason:"unreachable",message:("No answer from Codeman at " + $a + ".")}') ;;
|
||
401) out='{"spawnable":false,"reason":"unauthorized","message":"Codeman refused the credentials (401): see the codeman skill, section 6."}' ;;
|
||
403) jq -e '.errorCode == "FORBIDDEN"' <<<"$body" >/dev/null 2>&1 &&
|
||
out='{"spawnable":false,"reason":"admin-only","message":"In multi-user mode the local model is for admins only: ask an admin of this Codeman."}' ;;
|
||
404) out='{"spawnable":false,"reason":"unsupported","message":"This Codeman has no local model support: it predates it."}' ;;
|
||
esac
|
||
[ -n "${out:-}" ] || out=$(jq -nc --arg c "$code" --arg t "$body" \
|
||
'{spawnable:false,reason:"error",status:$c,message:((($t | fromjson? | .error?) // $t)[0:300])}')
|
||
printf '%s\n' "$out"
|
||
[ "$(jq -r .spawnable <<<"$out")" = true ]
|
||
}
|
||
# _local_ready_model -> local_model's JSON once a `local` worker can start, rc 1 with the
|
||
# reason on stderr otherwise. An installed model whose runtime is stopped is started first,
|
||
# with exactly what the local model window's Start button sends, and read again until it
|
||
# runs (bounded, about 30 s). ⚠️ That start also undoes a Stop the person made: the runtime
|
||
# starts with Codeman again from then on. Concurrent spawns may both send it; the server
|
||
# runs one runtime verb at a time and a second start keeps the runtime that runs.
|
||
_local_ready_model() {
|
||
local lm r i=0
|
||
lm=$(local_model) || { jq -r '"no local model to spawn on (" + .reason + "): " + .message' <<<"$lm" >&2; return 1; }
|
||
[ "$(jq -r .running <<<"$lm")" = true ] && { printf '%s\n' "$lm"; return 0; }
|
||
r=$("${CURL[@]}" -X POST "$API/api/v1/local-model/runtime" -H 'Content-Type: application/json' -d '{"action":"start"}')
|
||
jq -e '.success == true' <<<"$r" >/dev/null 2>&1 || {
|
||
echo "could not start the local model runtime: $(jq -r '.error // empty' <<<"$r" 2>/dev/null || printf '%s' "$r" | head -c 300)" >&2
|
||
return 1; }
|
||
while :; do
|
||
lm=$(local_model) || { jq -r '"the local model runtime was started, but (" + .reason + "): " + .message' <<<"$lm" >&2; return 1; }
|
||
[ "$(jq -r .running <<<"$lm")" = true ] && { printf '%s\n' "$lm"; return 0; }
|
||
i=$((i+1)); [ "$i" -lt 15 ] || { echo "the local model runtime did not report running within 30 s" >&2; return 1; }
|
||
sleep 2
|
||
done
|
||
}
|
||
# 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 -- or a
|
||
# `local` worker (below) whose composer drew, which takes a prompt but has NO end-of-turn
|
||
# signal unless its harness is claude: drive that one with sendmark.
|
||
# 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.
|
||
# mode `local` is the model Codeman installed on this Mac (local_model), run by the coding
|
||
# agent it was installed with. The worker's mode becomes that agent, and the endpoint and
|
||
# model ride the quick-start as `customModel`: the launch the window's "Start a session"
|
||
# makes. A stopped runtime is started first. Any answer that wants a person to confirm
|
||
# something (a context below the agent's safe floor, a model swap) fails the spawn: this
|
||
# never confirms on anyone's behalf.
|
||
# 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 lm cm='' mark=''
|
||
if [ "$mode" = local ]; then
|
||
lm=$(_local_ready_model) || return 1
|
||
mode=$(jq -r .cli <<<"$lm")
|
||
cm=$(jq -c '{endpointId, modelId}' <<<"$lm")
|
||
# Readiness is a token the agent's composer draws. The registry's composer data never
|
||
# reaches the API, so it is named per agent here. opencode: `┃`, its `workDetect.promptGlyph`.
|
||
# That field is no readiness mark in general (the registry keeps `composerReadyMark` for
|
||
# that, and declares none for opencode), but at boot only the composer draws it: measured
|
||
# on opencode 1.3.0 on Linux, fresh home, custom provider, the first `┃` came with the composer,
|
||
# and a prompt pasted with its Enter at that moment was submitted. claude takes the claude
|
||
# path below. Any other agent needs LOCAL_READY_MARK rather than a worker handed back on a guess.
|
||
[ "$mode" = opencode ] && mark='┃'
|
||
mark=${LOCAL_READY_MARK:-$mark}
|
||
[ "$mode" = claude ] || [ -n "$mark" ] || {
|
||
echo "the local model runs through $mode, and this skill knows no composer mark for it: set LOCAL_READY_MARK to a space-free token its composer draws" >&2
|
||
return 1; }
|
||
fi
|
||
# 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. The advisor is a cloud model,
|
||
# so a claude worker on the local model never gets one.
|
||
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" --arg a "${CODEMAN_WORKER_ADVISOR:-}" --arg cm "$cm" \
|
||
'{caseName:$n,mode:$m,parentSessionId:$p}
|
||
+ (if $m == "deepseek" then {deepSeekConfig:{permissionMode:"danger-full-access"}} else {} end)
|
||
+ (if $m == "claude" and $a != "" and $cm == "" then {advisorModel:$a} else {} end)
|
||
+ (if $cm != "" then {customModel:($cm | fromjson)} else {} end)')")
|
||
# The answers that want a PERSON to decide come back as success with no session id.
|
||
if jq -e '(.data // .) | (.requiresContextWarning or .requiresConfirmation)' <<<"$q" >/dev/null 2>&1; then
|
||
jq -r '"quick-start wants a person to confirm something, so no worker was started: " + ((.data // .) | tojson)' <<<"$q" >&2
|
||
return 1
|
||
fi
|
||
sid=$(jq -r 'if .success then .data.sessionId else empty end' <<<"$q")
|
||
# NOT retryable in a loop: every quick-start failure code is terminal (§5.1).
|
||
[ -n "$sid" ] || { jq -c '{error,errorCode}' <<<"$q" >&2; return 1; }
|
||
# A server without advisor support DROPS the field instead of refusing it, so read it
|
||
# back: a worker silently missing the advisor it was asked for is worth one line.
|
||
if [ "$mode" = claude ] && [ -z "$cm" ] && [ -n "${CODEMAN_WORKER_ADVISOR:-}" ] &&
|
||
[ "$("${CURL[@]}" "$API/api/v1/sessions/$sid" | jq -r '.data.advisorModel // empty')" != "$CODEMAN_WORKER_ADVISOR" ]; then
|
||
echo "worker $sid: this Codeman server ignored CODEMAN_WORKER_ADVISOR (no advisor support); it runs without one" >&2
|
||
fi
|
||
if [ -n "$cm" ] && [ "$mode" != claude ]; then
|
||
# No trust dialog and no hook file to vet: the agent has no hooks, which is exactly
|
||
# why sendwait refuses it (400) and sendmark drives it.
|
||
r=$(_mark_up "$sid" "$mark" 45000)
|
||
[ "$r" = true ] || { echo "local worker $sid ($mode) never drew '$mark' within 45 s; deleted it. Look at GET /api/v1/local-model and the pane of a hand-made session before retrying" >&2
|
||
delete_session "$sid" >/dev/null; return 1; }
|
||
printf '%s\n' "$sid"; return 0
|
||
fi
|
||
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' <<<"$q")
|
||
grep -qs '/api/hook-event' "$cp/.claude/settings.local.json" || {
|
||
echo "case '$name' resolved to '$cp', which has no Codeman hooks (workspaceHooksEnabled off, remote, or an older server?): turn the setting on, or work §5.1+§5.5 by hand with markers" >&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 <caseName[:mode]>... -> one "<caseName> <sessionId>" 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, `summ:local` a worker on the
|
||
# local model, 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 <sid> <prompt> [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: the Enter can be lost (an Ink repaint eats it, and Claude
|
||
# Code 2.1.277+ ignores it outright for the first 30-50 s after the composer paints),
|
||
# leaving the typed prompt stranded on the composer while a long wait runs its whole
|
||
# timeout (observed live, twelve reviews in a row). So the first wait is short; on its
|
||
# timeout the ORIGINAL frame is resent unchanged as a long re-wait (a tagged duplicate:
|
||
# the server re-waits without retyping, §5.3) and kept open in the background, while
|
||
# the composer is READ (_composer_text) and, as long as the prompt is still sitting
|
||
# there, a bare \r goes out about every ten seconds, up to twelve times. An empty
|
||
# composer ends the loop, so a prompt that was taken is never nudged again, and the
|
||
# wait that was open the whole time is what reports the turn's end. 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, sendmark below). ⚠️ 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 c head n=0 tmp bg i
|
||
# One line, like every other waiting sender (`toSingleLine`, `codeman agent send`,
|
||
# the TUI): the server pastes a multi-line prompt as one block, and the loop below,
|
||
# like the server's own submit check, cannot recognise a pasted block that is still
|
||
# on the composer, so a prompt like `Review this:\n- item 1` would sit unsent for
|
||
# the whole re-wait. Each line is trimmed, blank lines are dropped, the rest are
|
||
# joined with a space. For a long multi-line task, write a file and send its path.
|
||
case "$p" in *$'\n'*|*$'\r'*)
|
||
p=$(printf '%s\n' "$p" | tr '\r' '\n' | sed -e 's/^[[:space:]]*//' -e 's/[[:space:]]*$//' -e '/^$/d' | paste -sd ' ' -) ;;
|
||
esac
|
||
[ -n "$p" ] || { echo "sendwait: empty prompt" >&2; return 1; }
|
||
# `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' <<<"$r" >/dev/null 2>&1; then
|
||
# ⚠️ The long re-wait is registered FIRST and stays open for the rest of this call,
|
||
# in the background, while the Enter loop below works the composer. Signals have
|
||
# no history: a `stop` that fires while no wait is open (during a composer read
|
||
# between two short waits, measured) is lost, and the next wait then runs its
|
||
# whole timeout on a turn that already ended. The resend is a tagged DUPLICATE,
|
||
# so the server skips the write and re-waits without retyping (§5.3).
|
||
tmp=$(mktemp "${TMPDIR:-/tmp}/codeman-wait.XXXXXX") || return 1
|
||
"${CURL[@]}" -X POST "$API/api/v1/sessions/$sid/input" \
|
||
-H 'Content-Type: application/json' --data-binary "$(jq -c '.waitTimeout=580000' <<<"$body")" > "$tmp" &
|
||
bg=$!
|
||
# The prompt's head with whitespace removed, matched literally (the "$head"
|
||
# quoting inside ${c#...} keeps a * or ? in the prompt from acting as a glob).
|
||
head=$(printf '%s' "$p" | tr -d '[:space:]' | sed "s/$(printf '\302\240')//g" | head -c 24)
|
||
while [ "$n" -lt 12 ] && [ ! -s "$tmp" ]; do # a non-empty file means the wait ended
|
||
c=$(_composer_text "$sid")
|
||
if [ "$c" = '?' ]; then
|
||
[ "$n" -eq 0 ] || break # unreadable pane: one Enter, then trust it
|
||
elif [ -z "$head" ] || [ "${c#"$head"}" = "$c" ]; then
|
||
break # composer empty (taken) or holding other text
|
||
fi
|
||
n=$((n+1))
|
||
"${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
|
||
i=0; while [ "$i" -lt 10 ] && [ ! -s "$tmp" ]; do sleep 1; i=$((i+1)); done
|
||
done
|
||
wait "$bg"
|
||
# The duplicate reports `delivered:false` -- 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=$(jq -c 'if .success and (.data.wait.ended | not) then .data.delivered = true else . end' < "$tmp")
|
||
rm -f "$tmp"
|
||
fi
|
||
printf '%s\n' "$r"
|
||
}
|
||
# sendmark <sid> <prompt> [timeoutSec] -> one JSON line, for an AGENT worker with no
|
||
# end-of-turn signal: a `local` worker whose agent is not claude, a hook-less claude, and
|
||
# every external agent mode but deepseek (a shell worker takes §5.5's echo form instead):
|
||
# {"token":…,"delivered":true,"matched":true,"answerFile":"<path>","answer":"<text>",…}
|
||
# rc 0: the answer file was read, after the marker or once the file held still (below).
|
||
# 2: neither within the timeout (default 600 s; the worker may still be working, so nothing
|
||
# is deleted). 3: the worker's pane ended. 4: the marker printed, but no answer file turned
|
||
# up within SENDMARK_FILE_WAIT seconds of it (default 120). 1: the send or a wait failed
|
||
# (`detail` says why).
|
||
# It adds ONE sentence to your prompt (joined onto one line, as sendwait does): write the
|
||
# complete answer to codeman-answer-<token>.md in the working directory, and only then end
|
||
# the reply with the word DONE immediately followed by _<token>. The marker is split in what
|
||
# is typed, so the prompt echoing into the pane never matches it, and the token is new for
|
||
# every call (§5.5). The send is sendwait's exactly-once body (per-worker clientId,
|
||
# epoch-second seq) with a one-second `exit` wait, so `delivered` says the pane took it.
|
||
# ⚠️ A marker proves that the model printed the token. Not that it did the work, not that
|
||
# it did it right, not even that the turn is over: a reasoning model can restate the
|
||
# instruction while it plans. That is why the answer FILE is the second gate. ⚠️ And a
|
||
# full-screen agent can print the marker without it ever matching: opencode redraws its
|
||
# spinner between the pieces a model streams, so the stripped stream reads D⬝⬝O⬝⬝N⬝⬝E_⬝⬝m…
|
||
# (measured on opencode 1.3.0 on Linux, a reply streamed a character or two at a time; the screen
|
||
# showed the whole token). So the file is also the way out WITHOUT the marker: present, not
|
||
# empty, and unchanged between two rounds of the marker wait (rounds of at most 10 s), it is
|
||
# read and `matched` says false. It is read from this machine's disk, only when it is a
|
||
# regular file (a symlink is refused), at most 256 KB of it. It stays in the worker's folder
|
||
# (§5.14).
|
||
# SENDMARK_ANSWER_FILE=0 asks for the marker alone, for a worker that cannot write where it
|
||
# runs (codex in a folder it runs read-only, an agent that asks before it writes a file, a
|
||
# worker on another host): rc 0 then means only "the marker printed", and the answer is
|
||
# yours to read (last_text for codex, §5.4). Without the file there is no way out but the
|
||
# marker, so on a full-screen agent that can be rc 2 for a reply that finished.
|
||
sendmark() {
|
||
local sid="${1:?}" p="${2:?}" t="${3:-600}" tok mark file='' wd r w='' rem end start got=0 ended=0 matched=false i=0 rc=2 fp prev=''
|
||
case "$p" in *$'\n'*|*$'\r'*)
|
||
p=$(printf '%s\n' "$p" | tr '\r' '\n' | sed -e 's/^[[:space:]]*//' -e 's/[[:space:]]*$//' -e '/^$/d' | paste -sd ' ' -) ;;
|
||
esac
|
||
[ -n "$p" ] || { echo "sendmark: empty prompt" >&2; return 1; }
|
||
tok=$(printf 'm%x%04x' "$(date +%s)" "$RANDOM"); mark="DONE_$tok"
|
||
if [ "${SENDMARK_ANSWER_FILE:-1}" != 0 ]; then
|
||
wd=$("${CURL[@]}" "$API/api/v1/sessions/$sid" | jq -r '.data.workingDir // empty' 2>/dev/null)
|
||
[ -n "$wd" ] || { echo "sendmark: could not read the working directory of worker $sid" >&2; return 1; }
|
||
file="$wd/codeman-answer-$tok.md"
|
||
p="$p (When you are done: write your complete answer to the file codeman-answer-$tok.md in your current working directory, and only after that file is written, end your reply with the word DONE immediately followed by _$tok with no space in between.)"
|
||
else
|
||
p="$p (When you are done, end your reply with the word DONE immediately followed by _$tok with no space in between.)"
|
||
fi
|
||
r=$("${CURL[@]}" -X POST "$API/api/v1/sessions/$sid/input" -H 'Content-Type: application/json' \
|
||
--data-binary "$(jq -nc --arg p "$p" --arg c "$CID-$sid" --argjson s "$(date +%s)" \
|
||
'{input:($p+"\r"),useMux:true,clientId:$c,seq:$s,wait:"exit",waitTimeout:1000}')")
|
||
if ! jq -e '.success and .data.delivered' <<<"$r" >/dev/null 2>&1; then
|
||
jq -e '.data.wait.ended or .data.wait.signal == "exit"' <<<"$r" >/dev/null 2>&1 && rc=3 || rc=1
|
||
jq -nc --arg t "$tok" --arg r "$r" '{token:$t,delivered:false,matched:false,answerFile:null,answer:null,detail:($r | fromjson? // $r)}'
|
||
return "$rc"
|
||
fi
|
||
start=$(date +%s); end=$((start + t))
|
||
while :; do # bounded waits of at most 10 s each, until the timeout
|
||
rem=$((end - $(date +%s))); [ "$rem" -ge 1 ] || break
|
||
[ "$rem" -le 10 ] || rem=10
|
||
w=$("${CURL[@]}" -G "$API/api/v1/sessions/$sid/wait-output" --data-urlencode "match=$mark" \
|
||
--data-urlencode 'from=buffer' --data-urlencode "timeout=$((rem * 1000))")
|
||
jq -e '.data.wait.matched' <<<"$w" >/dev/null 2>&1 && { matched=true; break; }
|
||
jq -e '.data.wait.ended' <<<"$w" >/dev/null 2>&1 && { ended=1; break; }
|
||
jq -e '.success' <<<"$w" >/dev/null 2>&1 || {
|
||
jq -nc --arg t "$tok" --arg w "$w" '{token:$t,delivered:true,matched:false,answerFile:null,answer:null,detail:($w | fromjson? // $w)}'
|
||
return 1; }
|
||
# No marker this round. The answer file is the other way out (see above): it counts once
|
||
# it is a non-empty regular file whose checksum did not change since the last round.
|
||
if [ -n "$file" ] && [ ! -L "$file" ] && [ -f "$file" ] && [ -s "$file" ]; then
|
||
fp=$(cksum < "$file"); [ "$fp" = "$prev" ] && { got=1; break; }; prev=$fp
|
||
else
|
||
prev=''
|
||
fi
|
||
done
|
||
if [ "$matched" = true ] && [ -n "$file" ]; then
|
||
while :; do
|
||
[ -L "$file" ] && { echo "sendmark: $file is a symlink, not read" >&2; break; }
|
||
[ -f "$file" ] && { got=1; break; }
|
||
[ "$i" -lt "${SENDMARK_FILE_WAIT:-120}" ] || break
|
||
# Two seconds of waiting that also notices a worker that died: an exit wait answers at
|
||
# once then. A wait that did not answer (server gone) still costs its two seconds.
|
||
w=$("${CURL[@]}" -G "$API/api/v1/sessions/$sid/wait" --data-urlencode 'until=exit' --data-urlencode 'timeout=2000')
|
||
jq -e '.data.wait.signal == "exit" or .data.wait.ended' <<<"$w" >/dev/null 2>&1 && { ended=1; break; }
|
||
jq -e '.success' <<<"$w" >/dev/null 2>&1 || sleep 2
|
||
i=$((i + 2))
|
||
done
|
||
fi
|
||
if [ "$got" = 1 ]; then
|
||
head -c 262144 "$file" | jq -Rsc --arg t "$tok" --arg f "$file" --argjson m "$matched" \
|
||
--argjson s "$(($(date +%s) - start))" --argjson c "$(($(wc -c < "$file")))" \
|
||
'{token:$t,delivered:true,matched:$m,answerFile:$f,answer:.,truncated:($c > 262144),waitedSec:$s}'
|
||
return 0
|
||
fi
|
||
jq -nc --arg t "$tok" --arg f "$file" --argjson m "$matched" --argjson e "$ended" --argjson s "$(($(date +%s) - start))" \
|
||
'{token:$t,delivered:true,matched:$m,answerFile:(if $f == "" then null else $f end),answer:null,ended:($e == 1),waitedSec:$s}'
|
||
if [ "$matched" = true ]; then
|
||
[ -z "$file" ] && return 0
|
||
[ "$ended" = 1 ] && return 3
|
||
return 4
|
||
fi
|
||
[ "$ended" = 1 ] && return 3
|
||
return 2
|
||
}
|
||
# last_text <sid> [prev] -> that worker's last assistant message (claude, codex and
|
||
# deepseek write a real transcript; the other modes have none, so read the terminal
|
||
# instead -- §5.4). Polled, because the transcript write LAGS the stop signal, and
|
||
# "some text exists" is not "THIS turn's text exists": right after a SECOND turn on the same worker the endpoint still serves
|
||
# the previous answer for a beat (observed live). When reading consecutive turns, pass
|
||
# the previous answer as [prev]: the poll then holds out for text that differs from it,
|
||
# falling back to whatever it last saw if the budget runs dry, so an honestly repeated
|
||
# answer still comes back. Non-zero exit means the worker really never wrote one.
|
||
last_text() {
|
||
local t="" prev="${2:-}"
|
||
for _ in $(seq 1 15); do
|
||
t=$("${CURL[@]}" "$API/api/v1/sessions/${1}/last-response" | jq -r '.data.text // empty')
|
||
[ -n "$t" ] && [ "$t" != "$prev" ] && { printf '%s\n' "$t"; return 0; }
|
||
sleep 1
|
||
done
|
||
[ -n "$t" ] && { printf '%s\n' "$t"; return 0; }
|
||
return 1
|
||
}
|
||
|
||
# The stamp is the LAST line on purpose (a truncated write leaves it unset) and is kept
|
||
# bare on purpose: the write condition above anchors on it with $, so an inline comment
|
||
# here would fail that match and rewrite this file on every single bootstrap.
|
||
CODEMAN_PREAMBLE=1.50.0
|
||
PREAMBLE
|
||
)
|
||
. "$PRE"; [ "${CODEMAN_PREAMBLE:-}" = 1.50.0 ] || { echo "preamble at $PRE is stale or truncated: rm it and re-run this block"; exit 1; }
|
||
```
|
||
|
||
Every later Bash call that touches the API starts with the same two loader lines from
|
||
the top of this section.
|
||
|
||
Why it is built this way, all of it load-bearing:
|
||
|
||
- **It still fails closed.** A missing or truncated file means `delete_session` is
|
||
undefined, and an undefined function is "command not found", which deletes nothing.
|
||
⚠️ This argument covers accidents, NOT a hostile file: a *complete* attacker-written
|
||
preamble can define `delete_session` and set the stamp, and sourcing executes it. What
|
||
defends against that is the path choice in the next bullet, not this one. Never
|
||
hand-roll a `DELETE` of your own, which is the one thing that would route around this.
|
||
- **The version stamp is the LAST line, and the write condition greps for it.** That one
|
||
choice covers staleness and truncation together: an old skill version's file and a
|
||
half-written one both fail the grep and are rewritten in place, so neither costs you a
|
||
round trip to diagnose and `rm`. The older `[ -s "$PRE" ]` condition could not tell a
|
||
complete file from a half-written one and left both to the post-source guard, which can
|
||
only refuse, not repair. That guard stays as the fail-closed backstop: if the rewrite
|
||
itself is cut short, `CODEMAN_PREAMBLE` is unset and the call stops.
|
||
- **Not `/tmp`.** On a shared machine `/tmp` is world-writable, so another local user
|
||
can pre-create the exact path you are about to `.` and have their code run as you.
|
||
`$HOME`-derived paths are not world-writable, and the file is written 0600 anyway.
|
||
The file holds the credential-*recovery code*, not a recovered password.
|
||
- **Never put `$$` in a `clientId`.** It changes per call, so the "resend the identical
|
||
request" loop in §5.3 would stop being a duplicate and would **retype the prompt**,
|
||
submitting the turn twice. Use the fixed literal `$CID`.
|
||
- Only real environment variables (`CODEMAN_*`, `HOME`) survive, which is why the
|
||
preamble rebuilds `$API` and `$SELF` from them on every source rather than baking
|
||
them in.
|
||
|
||
If a call comes back as unparseable text instead of JSON, that is almost always a
|
||
plain-text 401: see §6 and [the symptom gallery](reference/endpoints.md#symptom-gallery).
|
||
|
||
## 1. The fast path: N workers, one Bash call
|
||
|
||
**If the job is "spawn N claude workers, give them tasks, collect the answers", this
|
||
block is the whole thing. Run it, report, and stop reading. §2 onward is for jobs this
|
||
does not cover; you are not being careless by not reading them.**
|
||
|
||
Fill in the case names and the prompts, then run it as your FIRST Bash call: no
|
||
standalone preamble check before it (line one below IS that check), and no
|
||
reconnaissance. `ls ~/codeman-cases` answers nothing this block needs: invented
|
||
fresh names need no lookup, and `spawn_worker` refuses a name that already exists
|
||
rather than silently reusing it. Everything below is `spawn_workers` / `sendwait` /
|
||
`last_text` / `delete_session` from the §0 preamble, so there is nothing to assemble
|
||
and no per-call body to hand-build.
|
||
|
||
```bash
|
||
. "${XDG_CACHE_HOME:-$HOME/.cache}/codeman-agent-$CODEMAN_SESSION_ID.sh" 2>/dev/null # §0 loader
|
||
[ "${CODEMAN_PREAMBLE:-}" = 1.50.0 ] || { echo "preamble missing or stale; run the full §0 block"; exit 1; }
|
||
N=(alpha beta) # INVENT one fresh case name per worker; never list cases first
|
||
# (a name may carry a mode: `beta:deepseek`, see below)
|
||
T=('reply with one line: the absolute path of your working directory'
|
||
'reply with one line: your model name') # tasks, same order as N
|
||
|
||
S=(); while read -r _ s; do S+=("$s"); done < <(spawn_workers "${N[@]}") # concurrent
|
||
for i in "${!N[@]}"; do [ -n "${S[$i]:-}" ] || FAIL=1; done
|
||
[ -z "${FAIL:-}" ] || { echo "a spawn failed (stderr says why; §5.1): deleting the siblings"
|
||
for s in "${S[@]}"; do [ -n "$s" ] && delete_session "$s" >/dev/null; done; exit 1; }
|
||
|
||
D=$(mktemp -d) || { for s in "${S[@]}"; do delete_session "$s" >/dev/null; done; exit 1; }
|
||
for i in "${!N[@]}"; do sendwait "${S[$i]}" "${T[$i]}" > "$D/$i" & done; wait
|
||
for i in "${!N[@]}"; do
|
||
jq -ce --arg n "${N[$i]}" \
|
||
'{worker:$n,delivered:.data.delivered,timedOut:.data.wait.timedOut,signal:.data.wait.signal}' \
|
||
"$D/$i" || echo "{\"worker\":\"${N[$i]}\",\"error\":\"send produced no result\"}"
|
||
echo "== ${N[$i]}"; last_text "${S[$i]}" || echo "(no response written)"
|
||
done
|
||
for i in "${!N[@]}"; do # delete ONLY what finished; a timeout means STILL WORKING (§3 rule 5)
|
||
if jq -e '.success and .data.delivered and (.data.wait.timedOut|not)' "$D/$i" >/dev/null 2>&1
|
||
then delete_session "${S[$i]}" >/dev/null
|
||
else echo "kept ${N[$i]} (${S[$i]}): its line above says why; re-wait or repair (§5.3), then delete_session it"
|
||
fi
|
||
done; rm -rf "$D"
|
||
```
|
||
|
||
Measured against a live 1.18.0 server: two cold workers spawned and ready in **6.3 s**,
|
||
both turns dispatched and both answers read in **4.0 s** more. If your run takes minutes,
|
||
the time went into deliberation, not the API. The four things that actually cost time:
|
||
|
||
- **Spawning serially.** One worker per Bash call is one model turn per worker. `&` plus
|
||
`wait`, as above, makes N workers cost about what one costs.
|
||
- **Reconnaissance turns before the spawn.** A standalone preamble check, an
|
||
`ls ~/codeman-cases`, a `list_sessions` "to see what is there": each is a whole
|
||
model turn spent learning something this block already handles (line one performs
|
||
the preamble check, invented names need no listing, and `spawn_worker` refuses
|
||
collisions). A live two-worker run spent ~12 s of its 28 s total on exactly two
|
||
such turns; the API work in between was under 10 s.
|
||
- **Re-deriving the happy path** from §5.1 + §5.2 + §5.3 + §5.10. That is what the
|
||
preamble functions exist to end. Compose them; do not rebuild them. The tells that
|
||
you are rebuilding anyway: a `for` loop around `quick-start`, a poll on `.data.pid`,
|
||
a bespoke `ready()` or `spawn()` of your own. Each is a worse copy of a function
|
||
already sitting in your preamble; the live run that wrote them spawned serially,
|
||
polled pid for nothing, and shipped its workers without lineage.
|
||
- **Verifying what is already checked for you.** Two verifications specifically are not
|
||
worth a call here, because `spawn_worker` carries them: the hooks check (it refuses a
|
||
name that resolved to a hook-less directory with one local grep, so a claude worker it
|
||
hands back always has a working `stop` and `sendwait` is trustworthy), and the pid poll,
|
||
which is dead weight because `wait-output` already blocks on the composer.
|
||
|
||
Four things this block leans on, each one link away, no detour needed to run it:
|
||
|
||
- Those case names must be **fresh scratch names**: they create
|
||
`~/codeman-cases/<name>`, not your repo. A name that already means something (a
|
||
linked case, a pre-existing directory) is refused by `spawn_worker` rather than
|
||
silently reused. Spawning where the work actually is (a linked case, a git worktree)
|
||
is a different call, and picking the wrong one is the costliest mistake in this
|
||
skill: §5.1. Those workspaces do get hooks now, unless the operator disabled it.
|
||
- `sendwait` supplies the `\r`, picks a fresh `seq`, and self-heals a stranded Enter.
|
||
A prompt without the `\r` is never submitted (§3), a reused `seq` is silently
|
||
swallowed as an already-applied duplicate, and a lost Enter strands the prompt on the
|
||
composer until a bare `\r` follows: Claude Code 2.1.277 and later ignore Enter for the
|
||
first 30 to 50 seconds after the composer paints while still taking the text, so
|
||
`sendwait` reads the composer and keeps pressing Enter until the prompt has left it.
|
||
All three are reasons to let `sendwait` build the call rather than hand-rolling it.
|
||
- Each `sendwait` costs that worker one billed turn, as does every prompt you send it.
|
||
- For long or high-stakes worker tasks, `CODEMAN_WORKER_ADVISOR=opus spawn_workers "${N[@]}"`
|
||
(`fable`, `opus` or `sonnet`) gives each claude worker Claude Code's advisor tool: a
|
||
stronger model it consults before committing to an approach, on a recurring error and
|
||
before declaring the task done. Advisor calls bill extra tokens, and an advisor ranked
|
||
below the worker's own model is never attached (on an Opus worker only `opus` and
|
||
`fable` do anything).
|
||
- Deleting the sessions does **not** remove the case directories. They are marked as
|
||
agent-created, so `GET /api/v1/cases/agent-created` lists them for cleanup: §5.14.
|
||
|
||
### DeepSeek Harness workers
|
||
|
||
The block above spawns claude workers. Any entry in `N` may instead name a mode
|
||
(`beta:deepseek`), and **a `deepseek` worker is driven by the same four verbs, with no
|
||
change to the rest of the block**: `spawn_workers` waits for its composer, `sendwait`
|
||
blocks on its real end-of-turn signal, `last_text` reads its answer, `delete_session`
|
||
removes it.
|
||
|
||
That is true of no other non-claude mode, and it is worth knowing why: the DeepSeek
|
||
Harness TUI reports `idle`/`working`/`blocked` to Codeman over the supervisor contract it
|
||
implements, so dsh is the one external CLI with definitive `stop`/`blocked` signals
|
||
instead of guessed-from-silence ones — and it writes a structured transcript, which is
|
||
what `last-response` reads for it. `shell`, `opencode`, `gemini`, `antigravity`, `pi`,
|
||
`grok`, `omp` and `copilot` have neither, and `codex` has a transcript and a screen-read `blocked` but
|
||
no `stop`, so all of them still need markers ([§5.5](reference/verbs.md#55-markers-for-hook-less-workers)).
|
||
|
||
Three things to know before you spawn one:
|
||
|
||
- **It needs a pane-capable profile.** `dsh` ships only `web`/`headless`, so the terminal
|
||
agent is always an installed profile. `GET /api/v1/deepseek/status` answers both
|
||
questions separately (`available` = the binary, `runnable` = a profile that can drive a
|
||
pane); a spawn without one fails with `OPERATION_FAILED` rather than falling back.
|
||
- **Do not task it on the strength of a `stop` alone.** The harness reports `idle` at
|
||
boot ~300 ms *before* its composer paints (measured 2.26 s vs 2.56 s), so a `sendwait`
|
||
fired straight after `quick-start` resolves on that boot signal, reports a turn that
|
||
never ran, and leaves the prompt in a pane that was not yet taking input. Letting
|
||
`spawn_worker` gate on readiness is what steps past that edge; it is not optional.
|
||
- **A profile that does not implement the contract looks like a hang.** Codeman cannot
|
||
know at spawn time whether one does. The tell is a `sendwait` that times out on a
|
||
worker whose pane clearly finished: that profile is one of them, so drive it with
|
||
markers instead.
|
||
|
||
### Claude in the cloud, a local model on this Mac
|
||
|
||
When Codeman has installed a model on the Mac it runs on (the **Run a local model** button
|
||
on its welcome screen), you can hand work to that model from here. You stay the planner and
|
||
the reviewer in the cloud; the Mac does the bulk. `spawn_worker <name> local` starts a worker
|
||
on the installed model, run by the coding agent it was installed with (OpenCode on the Mac
|
||
it was tested on), and from then on it is the same verbs. It mixes into one fleet like any
|
||
other mode: `spawn_workers plan review:deepseek summ:local`.
|
||
|
||
Reach for it when:
|
||
|
||
- **The work is bulk, not judgment**: summarizing a folder, classifying, first drafts of
|
||
tests, boilerplate. A local turn has no per-token bill.
|
||
- **The files should stay on this machine**: the worker reads them here, and only what you
|
||
read back from it enters your own context.
|
||
- **You want a second opinion from a different model**, with different blind spots.
|
||
- **The worker should not depend on the network**: the model's runtime listens on this Mac
|
||
only, started with its cloud features off. You, the lead, still need a connection.
|
||
|
||
```bash
|
||
. "${XDG_CACHE_HOME:-$HOME/.cache}/codeman-agent-$CODEMAN_SESSION_ID.sh" 2>/dev/null # §0 loader
|
||
[ "${CODEMAN_PREAMBLE:-}" = 1.50.0 ] || { echo "preamble missing or stale; run the full §0 block"; exit 1; }
|
||
local_model || exit 1 # one JSON line: model, agent, endpoint; or the reason there is none
|
||
SID=$(spawn_worker summ local) || exit 1 # starts a stopped runtime first; empty = failed
|
||
WD=$("${CURL[@]}" "$API/api/v1/sessions/$SID" | jq -r .data.workingDir)
|
||
mkdir -p "$WD/input" && cp ./docs/*.md "$WD/input/" # inside its own folder (§5.9), apart from its CLAUDE.md
|
||
R=$(sendmark "$SID" 'Summarize each .md file in the folder input, two lines each' 900); RC=$?
|
||
jq -r '.answer // "(no answer)"' <<<"$R"
|
||
if [ "$RC" = 0 ]; then delete_session "$SID" >/dev/null
|
||
else echo "kept $SID (sendmark rc $RC: 2 no answer yet, 3 ended, 4 no answer file): $R"; fi
|
||
```
|
||
|
||
`sendmark` is the local worker's `sendwait`: it adds one sentence to your prompt asking for
|
||
the answer in `codeman-answer-<token>.md` in the worker's folder and then a split marker,
|
||
waits for the marker with `wait-output`, and reads the file back. OpenCode can draw the
|
||
marker in pieces that never match, so a file that holds still between two checks ends the
|
||
wait too ([§5.16](reference/verbs.md#516-a-worker-on-the-local-model)). Read its `answer`,
|
||
not the pane: a full-screen agent's pane is a poor transcript. ⚠️ A marker proves that the model
|
||
printed a token, not that the work is done or right. Review what comes back the way you
|
||
would review any first draft.
|
||
|
||
The limits, before you promise the user anything:
|
||
|
||
- **A Mac with Apple silicon, and a model a person installed** in Codeman's local model
|
||
window. This skill never installs one: that is a download of many gigabytes the person
|
||
confirms there. `local_model` says what is missing (`not-mac`, `not-installed`,
|
||
`install-unfinished`, `blocked`, `admin-only`, `unsupported`), so tell the user that
|
||
instead of guessing.
|
||
- **One model, one request at a time.** The runtime loads one model and answers one request
|
||
at a time, so two local workers take turns rather than work side by side. Fan out to the
|
||
cloud; give the Mac a queue.
|
||
- **Slower than a cloud model.** The one measured pair, OpenCode with Qwen3.6 35B-A3B on an
|
||
M5 Pro with 48 GB, ran at about 68 tokens a second, and the first request after a start
|
||
loads the model first. A local worker run by claude spends minutes on its first answer
|
||
(its fixed prompt is about 36,000 tokens).
|
||
- **Markers, not hooks.** OpenCode reports no end of turn, so `sendwait` answers 400 for
|
||
that worker; `sendmark` is the way through. If the installed agent is claude, the worker
|
||
has hooks and `sendwait` works as for any claude worker.
|
||
- **Spawning can change what the person set.** A stopped runtime is started, which also
|
||
undoes the person's Stop: it then starts with Codeman again. And while a local worker is
|
||
open, the window refuses Stop and Remove and names your workers, so delete them as soon
|
||
as they are done.
|
||
- **Admin only in multi-user mode, and experimental.** The local model routes answer 403
|
||
for anyone else (`admin-only`), and they may change in any release.
|
||
|
||
## 2. What do you want to do?
|
||
|
||
One row per job. Acting on this table alone is correct; the §5 links are the detail.
|
||
|
||
| I want to | Call | Detail |
|
||
|-----------|------|--------|
|
||
| start a worker **where the work is** | `POST /api/v1/quick-start {"caseName":…}`, which **creates** `~/codeman-cases/<name>` unless the name is already a case. Any other path (a git worktree): `POST /api/v1/sessions {"workingDir":…}` then `POST /api/v1/sessions/:id/interactive`. Both install hooks by default, so expect full signals in either, and **verify** rather than assume. N workers means N worktrees | [§5.1](reference/verbs.md#51-where-to-spawn) |
|
||
| know a new worker can accept a prompt | `GET .../wait-output?match=shift+tab&from=buffer` (urlencode the `+`); a `deepseek` worker draws `❯` instead, and its boot `stop` fires ~300 ms BEFORE that, so never read the signal as readiness | [§5.2](reference/verbs.md#52-readiness) |
|
||
| deliver a task **and** know when it finished | `POST .../input` with `"input":"…\r"`, `clientId`, `seq`, `"wait":true`. Resolves on `stop`, so it is trustworthy where the signal is real: claude mode with hooks (installed by default, but the operator can disable it and remote sessions never get them) and `deepseek` mode through its status bridge. Costs the worker one billed turn | [§5.3](reference/verbs.md#53-send-a-task-and-wait) |
|
||
| know a hook-less worker finished | it has no `stop`, and `wait:true` there resolves on flapping `idle` **without erroring**: make it print a split, unique marker and `wait-output` on that instead. For an agent worker, `sendmark <sid> "<prompt>"` does all of it and reads the answer back | [§5.5](reference/verbs.md#55-markers-for-hook-less-workers) |
|
||
| hand work to the local model on this Mac (cheap bulk work, files that stay here, a second opinion) | `local_model` says what is installed; `spawn_worker <name> local` (or `name:local` in `spawn_workers`) starts a worker on it; `sendmark` tasks it and returns the answer | [Local model](#claude-in-the-cloud-a-local-model-on-this-mac), [§5.16](reference/verbs.md#516-a-worker-on-the-local-model) |
|
||
| read the answer | `GET .../last-response`, **polled** (claude, codex and deepseek write a transcript; empty for the other modes) | [§5.4](reference/verbs.md#54-read-the-answer) |
|
||
| know if it is alive | `GET .../wait?until=exit&timeout=1000`: an immediate `signal:"exit"` means dead. `status` and `pid` both lie | [§5.6](reference/verbs.md#56-alive-and-stuck) |
|
||
| know if it is stuck | `GET .../active-tools` and `GET .../run-summary` are structured and free; two `terminal?tail=` samples are the crude fallback | [§5.6](reference/verbs.md#56-alive-and-stuck) |
|
||
| make a runaway worker stop | `POST .../input {"input":"\u001b"}` (ESC, **no** `\r`). Deleting the session would destroy the conversation instead | [§5.7](reference/verbs.md#57-interrupt-without-destroying) |
|
||
| resume a worker halted on a usage limit | `POST .../auto-resume {"enabled":true}`. Respawn and Ralph are **not** the remedy: respawn runs `/clear` | [§5.8](reference/verbs.md#58-usage-limits) |
|
||
| give a worker big input | write a file into its workspace with your own tools and send one short line pointing at it. The composer takes 65536 characters, and `send` takes one line | [§5.9](reference/verbs.md#59-big-input-via-the-workspace) |
|
||
| watch N workers at once | one in-flight wait per worker (per-session waiter cap 16); fan-out shapes differ for claude and shell | [§5.10](reference/verbs.md#510-fan-out) |
|
||
| find yourself, list what exists | `GET /api/v1/sessions`, match your `$SELF` by **prefix** | [§5.11](reference/verbs.md#511-list-and-find-yourself) |
|
||
| read or record what the user wants | `GET/PUT .../intent`, and `POST .../readmymind` to predict | [§5.12](reference/verbs.md#512-read-my-mind) |
|
||
| talk to a claude worker directly | `ListAgents` / `SendMessage`, when the feature is on at both ends | [§5.13](reference/verbs.md#513-messaging-claude-workers) |
|
||
| leave a message a session reads when it is ready, any mode, multi-line | `codeman agent post <id> "…"` (`POST .../inbox`). Nothing is typed into its pane and no turn starts; the receiver reads with `codeman agent inbox --wait` and removes with `codeman agent ack <id>`. An idle receiver never looks on its own: `codeman agent ls` shows unread mail, then `send` it one line | [§5.15](reference/verbs.md#515-agent-inbox) |
|
||
| clean up | `delete_session "$SID"` per id you created. Case directories and git worktrees are **not** removed with it; `GET /api/v1/cases/agent-created` lists the scratch case dirs your spawns left behind, for you to report | [§5.14](reference/verbs.md#514-clean-up) |
|
||
|
||
## 3. Rules digest
|
||
|
||
Ten one-liners. Each breaks something concrete; the reason is one link away.
|
||
|
||
1. **End every input with `\r`** or Enter is never sent and the text sits unsubmitted
|
||
([§5.3](reference/verbs.md#53-send-a-task-and-wait)).
|
||
2. **Never branch on `.data.status`.** It reads `idle` mid-turn and `idle` on a dead
|
||
worker ([§5.6](reference/verbs.md#56-alive-and-stuck)).
|
||
3. **Split your markers.** Your typed command echoes into the output stream, so an
|
||
unsplit marker matches before the command runs
|
||
([§5.5](reference/verbs.md#55-markers-for-hook-less-workers)).
|
||
4. **Match single space-free tokens against TUI output.** A TUI positions words with
|
||
cursor moves, so multi-word matches are unreliable there
|
||
([§5.2](reference/verbs.md#52-readiness)).
|
||
5. **A wait timeout is a 200, not an error.** Loop over short waits; the clamp and the
|
||
applied `wait.timeoutMs` are in
|
||
[endpoints.md](reference/endpoints.md#limits-and-caps).
|
||
6. **Signals are edge-triggered with no history.** Register the waiter before the
|
||
event can happen; a `stop` that fires with no waiter is unobservable afterwards
|
||
([§5.10](reference/verbs.md#510-fan-out)).
|
||
7. **Never delete without `delete_session`.** The server lets a session delete itself
|
||
([§4](#4-safety-rules)).
|
||
8. **One in-flight wait per worker.** The per-session waiter cap is 16 and abandoned
|
||
waits count against it ([§5.10](reference/verbs.md#510-fan-out)).
|
||
9. **Every message you send a worker costs it a billed turn**, including a readiness
|
||
ping and an interrupted turn ([§5.7](reference/verbs.md#57-interrupt-without-destroying)).
|
||
10. **Never answer another session's dialog.** Approving a permission prompt you did
|
||
not raise authorizes an action the user never saw ([§4](#4-safety-rules)).
|
||
|
||
## 4. Safety rules
|
||
|
||
You are yourself a session on this server, and the API has **no undo**.
|
||
|
||
- **Never act on your own session, and know that `delete_session` is the ONLY guard.**
|
||
The server has no self-protection: a session that DELETEs its own id succeeds and
|
||
dies silently (verified live). **Always delete through `delete_session "$SID"` from
|
||
§0; never write a bare `curl -X DELETE` and never reintroduce the
|
||
`is_self … || curl -X DELETE …` shape.** That older form failed open: with the
|
||
function undefined (a missing or truncated preamble file, see §0) bash returns 127,
|
||
the `||` branch fires, and the delete runs with no self-check at all. Wrapping the
|
||
request inside the guard is what makes a lost preamble delete nothing instead of
|
||
deleting you. Apply the same prefix-both-directions reasoning before any kill,
|
||
respawn, or input call you write by hand.
|
||
- **Mutating calls you may make unprompted** (this is an allowlist):
|
||
`POST /api/v1/quick-start`; `POST /api/v1/sessions` + `POST /api/v1/sessions/:id/interactive`
|
||
(or `/shell`) for a directory the user's own task named; `POST /api/v1/sessions/:id/input`;
|
||
and `DELETE /api/v1/sessions/:id` **only** for a session you created in this
|
||
conversation, by exact id. Keep a list of the ids you create. Everything else
|
||
mutating needs the user to have asked for it.
|
||
- **Never call these** unless the user explicitly asked, naming the target:
|
||
- `DELETE /api/cases/:name` recursively **deletes a real directory of the user's
|
||
code** from disk. One wrong case name destroys work that was never yours.
|
||
- `DELETE /api/sessions` (no id) is a **bulk kill of every session**, the user's
|
||
real work included. `DELETE /api/subagents/:agentId` kills one background agent;
|
||
`DELETE /api/subagents` (no id) does *not* kill anything, it clears the watcher's
|
||
map and timers, which blinds every subagent surface in the UI until they are
|
||
rediscovered. Neither is yours to call.
|
||
- respawn / ralph / orchestrator / cron mutations: respawn runs `/clear` (wipes a
|
||
conversation), orchestrator state is a single global slot, cron jobs outlive you.
|
||
- `PUT /api/settings`, `POST /api/system/update`: global UI settings; server restart.
|
||
- `POST /api/approvals/:id/answer`. It types a digit, an Esc or free text into
|
||
whichever session raised the prompt. Approving another session's permission
|
||
dialog authorizes a tool call the user never saw, from a session that is not
|
||
yours. Answer only a prompt raised by a worker you created, and only when the
|
||
user asked you to.
|
||
- **Never spawn a worker into the directory you are editing**, and give N workers N
|
||
git worktrees rather than one shared checkout. Two agents in one working tree
|
||
interleave writes and each reads the other's half-finished files; a `git checkout`
|
||
in one yanks the tree out from under the other. Creating worktrees changes the
|
||
user's repository state, so say that you did; **removing** one discards any
|
||
uncommitted work inside it, so ask first ([§5.1](reference/verbs.md#51-where-to-spawn)).
|
||
- Never `tmux kill-session`, `pkill tmux`, `pkill claude`. The API is the only interface.
|
||
- Sessions count against a **global cap, 50 by default** (`CODEMAN_MAX_SESSIONS`), and,
|
||
in multi-user mode, a per-user cap (half the global cap, 25 by default) that fires
|
||
the same 409. Case creation is uncapped and writes real
|
||
directories. Clean up every session you start, and never retry `quick-start` in a
|
||
loop.
|
||
|
||
## 5. Recipes → [reference/verbs.md](reference/verbs.md)
|
||
|
||
The per-verb detail lives in [reference/verbs.md](reference/verbs.md), loaded on demand
|
||
so it is not paid for on every skill load. Section numbers and anchors are unchanged, so
|
||
a `§5.4` reference still resolves. **§1 already covers the common job without any of
|
||
these**; open the one row you actually hit.
|
||
|
||
| Open | When |
|
||
|------|------|
|
||
| [5.1 Where to spawn](reference/verbs.md#51-where-to-spawn) | the work is **not** a fresh scratch case: a linked case, a git worktree, any path that already existed. Hooks are absent there, which silently breaks send-and-wait. The costliest mistake in this skill |
|
||
| [5.2 Readiness](reference/verbs.md#52-readiness) | a worker never drew its composer, or you need the trust-dialog ladder by hand |
|
||
| [5.3 Send a task and wait](reference/verbs.md#53-send-a-task-and-wait) | the `sendwait` body, its signals, and the duplicate-resend loop |
|
||
| [5.4 Read the answer](reference/verbs.md#54-read-the-answer) | `last_text` came back empty, or the mode is not claude/codex/deepseek |
|
||
| [5.5 Markers for hook-less workers](reference/verbs.md#55-markers-for-hook-less-workers) | the worker has no `stop` hook: synchronize on a split, unique printed marker |
|
||
| [5.6 Alive and stuck](reference/verbs.md#56-alive-and-stuck) | is it dead or just slow? `status` and `pid` both lie |
|
||
| [5.7 Interrupt without destroying](reference/verbs.md#57-interrupt-without-destroying) | a runaway worker you want to stop but keep |
|
||
| [5.8 Usage limits](reference/verbs.md#58-usage-limits) | a worker halted on a subscription limit |
|
||
| [5.9 Big input via the workspace](reference/verbs.md#59-big-input-via-the-workspace) | the prompt is larger than one composer line |
|
||
| [5.10 Fan out](reference/verbs.md#510-fan-out) | many workers at once: waiter caps, and why signals are edge-triggered |
|
||
| [5.11 List and find yourself](reference/verbs.md#511-list-and-find-yourself) | enumerate sessions, or match `$SELF` by prefix |
|
||
| [5.12 Read My Mind](reference/verbs.md#512-read-my-mind) | read or record what the user wants for a case |
|
||
| [5.13 Messaging claude workers](reference/verbs.md#513-messaging-claude-workers) | `ListAgents` / `SendMessage` instead of the HTTP path |
|
||
| [5.14 Clean up](reference/verbs.md#514-clean-up) | what deleting a session does **not** remove, and how to list the case dirs you left |
|
||
| [5.15 Agent inbox](reference/verbs.md#515-agent-inbox) | messages that wait for the receiver instead of being typed: post, read until ack, who counts as the receiver |
|
||
| [5.16 A worker on the local model](reference/verbs.md#516-a-worker-on-the-local-model) | what `local_model` answers, what `spawn_worker <name> local` does step by step, and every `sendmark` outcome |
|
||
|
||
## 6. Setup and auth
|
||
|
||
You need this section only when the API answers something `jq` cannot parse, or when
|
||
you are on a server old enough to lack the wait endpoints. Endpoint-level detail lives
|
||
in [endpoints.md](reference/endpoints.md#auth-and-credentials).
|
||
|
||
### Credentials
|
||
|
||
Auth is active only when the server has `CODEMAN_PASSWORD` (or is in multi-user mode).
|
||
**Your session has usually inherited that password already**, which is why the §0
|
||
preamble tries `$CODEMAN_PASSWORD` first: Codeman does not strip it. `buildClaudeEnv()`
|
||
(`src/session-cli-builder.ts`) spreads the server's entire `process.env` into the
|
||
session and deletes only `COLORTERM` and `CLAUDECODE`, and the tmux spawn path applies
|
||
no denylist either. On a stock password-protected install (`install.sh` writes the
|
||
password into the systemd unit or launchd plist, so the server process carries it) the
|
||
value is simply in your environment.
|
||
|
||
It is not guaranteed, though, which is what the fallbacks are for. A tmux pane
|
||
inherits the **tmux server's** environment, and that server can predate the password;
|
||
and the data dir's `.env` is only ever read by the `codeman` CLI itself, never loaded
|
||
into the web server's environment.
|
||
|
||
Fallback 1, in the §0 preamble already: the data dir's `.env`, the same file
|
||
`codeman attach` reads. It is hand-authored; nothing ever writes it.
|
||
|
||
Fallback 2, for a stock install where the supervisor definition is the only copy on
|
||
disk. Append this to the preamble file (before its version-stamp line) and re-source:
|
||
|
||
```bash
|
||
if [ -z "${CODEMAN_PASSWORD:-}" ]; then # install.sh puts it in the service definition
|
||
UNIT="$HOME/.config/systemd/user/codeman-web.service"
|
||
PLIST="$HOME/Library/LaunchAgents/com.codeman.web.plist"
|
||
if [ -f "$UNIT" ]; then
|
||
# install.sh backslash-escapes " and \ in the unit value; undo it or a password
|
||
# containing either recovers wrong and auth fails.
|
||
CODEMAN_PASSWORD=$(sed -n 's/^Environment="CODEMAN_PASSWORD=\(.*\)"$/\1/p' "$UNIT" | head -1 | sed 's/\\\(["\\]\)/\1/g')
|
||
elif [ -f "$PLIST" ]; then
|
||
# install.sh XML-escapes the plist value; undo it (& LAST, mirroring escape order).
|
||
CODEMAN_PASSWORD=$(awk '/<key>CODEMAN_PASSWORD<\/key>/{getline; print}' "$PLIST" | sed -n 's/.*<string>\(.*\)<\/string>.*/\1/p' \
|
||
| sed -e 's/</</g' -e 's/>/>/g' -e 's/&/\&/g')
|
||
fi
|
||
fi
|
||
```
|
||
|
||
⚠️ **A 401 is plain text, not the JSON envelope**, so on a password-protected server
|
||
every `jq` in these recipes dies with `jq: parse error` instead of showing
|
||
`UNAUTHORIZED`. If that happens, check the status with `-w '%{http_code}'`; if it is
|
||
401 and no fallback found a credential, **stop and tell the user you need
|
||
credentials**. The same is true of the guards that run before any handler: the Host
|
||
allowlist (`403 Forbidden: host not allowed`), the Origin/CSRF guard, and the auth
|
||
rate limiter's 429 all answer in plain text. The hook-secret bypass covers only
|
||
`/api/hook-event` and `/api/status-telemetry`, never session control.
|
||
|
||
In multi-user mode accounts live in `users.json` and the credential is a real user's
|
||
name and password. A recovered `CODEMAN_PASSWORD` still often works: `bootstrapInitialAdmin()`
|
||
(`user-store.ts:417-427`) creates the FIRST admin from `CODEMAN_USERNAME`/`CODEMAN_PASSWORD`
|
||
on first boot when no users exist, so on a stock multi-user install that pair usually IS
|
||
a valid admin login until someone changes it. Try it once; if it fails, ask the user
|
||
rather than retrying (ten failures rate-limit the address).
|
||
|
||
### Server version
|
||
|
||
The wait endpoints first ship in Codeman **1.13.0**, but do not gate on the version
|
||
number: a dev build can serve them while reporting an older version. Probe instead.
|
||
`GET .../wait` on a real session id answering 404 with an `.error` starting `Route `
|
||
means the server predates them (fall back to polling `GET .../terminal?tail=` and say
|
||
so). `Session ... not found` means your session id is wrong, not the server.
|
||
|
||
### Where the API is unreachable
|
||
|
||
- **Remote-SSH cases** do not export `CODEMAN_MUX`/`CODEMAN_API_URL` into the session,
|
||
so the §0 guard fails closed and you refuse to act. That is correct behavior, not a
|
||
bug to work around.
|
||
- **Inside a Docker case**, a loopback-bound server is unreachable from the container,
|
||
and `CODEMAN_DOCKER_BRIDGE_HOOKS=1` does not fix it: that opens a hooks-only
|
||
listener, so hook events flow but `/api/v1/*` stays refused. Report it rather than
|
||
retrying; making it reachable is an operator decision.
|
||
|
||
Everything else (endpoint tables, per-mode signal table, error codes, capacity limits,
|
||
Docker/remote caveats): [reference/endpoints.md](reference/endpoints.md). Fan-out
|
||
orchestration and blocked-worker handling: [reference/recipes.md](reference/recipes.md).
|