Driving CLIque

CLIque runs coding-agent sessions (Claude, Codex, Grok, a shell, …) in tmux and exposes every action as an HTTP call. That is the point: anything the panel can do, a script or an agent can do. This skill is the orchestration surface.

Connect

Base URL is the panel's own — http://127.0.0.1:3200 on the same box, or the tailscale URL from off it. Authenticate with a bearer token, not a cookie:

CLIQUE_TOKEN=$(python3 -m clique token create my-agent | grep -oE 'mxp_[A-Za-z0-9_-]+')   # shown once
curl -H "Authorization: Bearer $CLIQUE_TOKEN" http://127.0.0.1:3200/api/state

Use --read-only for a token that may observe but not start or stop anything.

The one word that matters: state

Every session in GET /api/state carries a state:

Orchestration is: start work, then wait for idle (done) or waiting (it needs you) — never a tight poll of the whole panel.

Endpoints

• GET /api/state — every session, each with id, name, cli, cwd, state, rss.
• POST /api/sessions — start one. Body: {cli, cwd, name?, folder?, mode?}. Add {worktree: true, branch: "<name>"} to run it in an isolated git worktree of the repo at cwd — the way to put several agents on one repo without them clobbering each other. Returns {id, worktree}.
• POST /api/sessions/<id>/send — {text, enter: true} submits a prompt.
• GET /api/sessions/<id>/peek?lines=N — the last N lines of the pane.
• GET /api/sessions/<id>/transcript — the full conversation as turns (Claude).
• GET /api/sessions/<id>/wait?for=idle,waiting&timeout=60 — blocks until the session reaches one of the for states or the timeout (max 300s). Returns {state, matched, waited}. This is the primitive to build on.
• POST /api/sessions/<id>/kill — stop it (keeps the record, resumable).
• DELETE /api/sessions/<id> — remove it. A worktree CLIque made is removed too, but only when it has no uncommitted changes.

Recipe: one task across many repos

auth=(-H "Authorization: Bearer $CLIQUE_TOKEN"); base=http://127.0.0.1:3200
for repo in /root/platform/relay /root/platform/sentinel /root/platform/clique; do
  id=$(curl -s "${auth[@]}" $base/api/sessions -d \
    "{\"cli\":\"claude\",\"cwd\":\"$repo\",\"worktree\":true,\"branch\":\"audit\",\"name\":\"audit $(basename $repo)\"}" \
    | python3 -c 'import sys,json;print(json.load(sys.stdin)["id"])')
  curl -s "${auth[@]}" $base/api/sessions/$id/send -d \
    '{"text":"Audit this repo for security issues and write findings to AUDIT.md.","enter":true}' >/dev/null
  echo "$id"                                   # collect the ids
done
# then, for each id: wait for it to finish or come back asking
curl -s "${auth[@]}" "$base/api/sessions/$id/wait?for=idle,waiting,error&timeout=300"
# idle -> done; waiting -> it needs an answer; peek to see what it said:
curl -s "${auth[@]}" "$base/api/sessions/$id/peek?lines=40"

Rules

• Wait, don't spin. Use /wait, not a loop over /api/state. It holds the connection until the state changes, capped at 300s — call again for longer.
• Reads are bounded. peek and transcript return a tail, never a whole 30 MB transcript. Ask for the lines you need.
• Worktrees for parallel same-repo work. Two agents in one working tree fight over files; one worktree each and they do not. Delete the session to clean up.
• A shell is not resumable. Killing a shell session loses its state; killing a Claude/Codex one does not — it starts again where it was.