Agents

Agents (Claude Code, Codex, ...) running in T3 can queue and manage stage tasks. Three front ends share one set of operations, all over the REST API. No gating: agents get the same access as the web UI.

Front ends

• CLI: stage task add|ls|show|edit|rm|start|stop|followup|dup|link|order|unlink|wait, schedule ..., sessions ls|search|show|questions (questions is read-only), projects ls, models ls, context. Human output by default, --json for agents and scripts. stage help lists everything.
• stdio MCP: stage mcp.
• HTTP MCP: http://<host>:7380/mcp (streamable HTTP, stateless, served by the running app; no install). It calls the app's own /api on loopback. Cannot read local files, so no imagePaths.

Install and register

Install the binary on the T3 host and register it. The compose image does not install it; rerun after updates.

mise run install-cli         # ~/.local/bin/stage (no args = server; subcommands = CLI)
stage setup mcp              # claude mcp add --scope user + codex mcp add (stdio); --http registers /mcp instead
stage setup instructions     # idempotent usage block in ~/.claude/CLAUDE.md and ~/.codex/AGENTS.md

STAGE_URL (or --url) points the CLI and stdio MCP at the app. Default http://127.0.0.1:7380.

Caller context

T3 sets T3CODE_THREAD_ID in every provider process. The CLI and stdio MCP read it and the cwd; HTTP MCP tools take callerThreadId / cwd arguments instead (override; required for context over HTTP).

• Project: explicit --project (id or exact title) > the calling session's project > the project whose root is the longest prefix of cwd.
• Model: explicit (provider inferred from the model via the catalog) > pinned default > last used > T3 default, like the New task form.
• Provenance: tasks and schedules record the creating session (originThreadId; spawned schedule tasks inherit it), shown as "Created by" on task detail and "by agent" on task rows.

Run after me

--after-me / afterMe starts the task when the calling session is settled in T3 (error without a calling session).

• A session owned by a task becomes a normal task link (afterTaskId).
• Any other session is a session link (afterThreadId). Many tasks may wait on one session.

Rules: link rules.

Handoff

A linked task's launch prompt gets its predecessor's final reply, PRs, branch/worktree and thread id. Default on.

• Turn off with --handoff=false / handoff: false on create_task, update_task or link_task (CLI task add|link --handoff=false, task edit --handoff=true|false). Omitted keeps the task's value.
• get_task returns handoff and currentHandoff. stage task show prints handoff on|off for linked tasks and the current attempt's record.

Block format: Handoff.

Predecessor base

--base predecessor --base-ref origin/main / base: "predecessor" starts a linked task's worktree from its predecessor's branch. --base-ref is the fallback.

• create_task, create_schedule, update_task, update_schedule and link_task take optional base (ref|predecessor; CLI task add|edit --base).
• On create it needs baseRef (the fallback). On update_task / link_task without baseRef it keeps the task's current worktree (error for a root task).
• get_task returns currentLaunchBase. stage task show prints worktree from #12's branch (fallback origin/main, branch -) and, once launched, base feat/api (from #12) or base origin/main (fallback: <reason>).

Rules: Predecessor base.

Session batch

The tasks a session created, grouped into run-order chains (head first) and independent tasks.

• get_session / stage sessions show return it (createdTasks) so a planning agent can check what it queued. get_task returns batch.
• order_tasks / stage task order ID ID... links several backlog tasks in order in one step. order_tasks takes taskIds and returns { "tasks": Task[] }.
• In the web UI, session detail lists the batch ("Created tasks") and task detail shows it as a compact Batch panel.

Rules: Session batch.

MCP tools

• Results are the REST shapes; lists are compact rows. Errors are tool errors carrying the API error.
• list_tasks and list_sessions rows carry lastWordPreview. get_task and get_session carry the reply excerpt in thread.lastWord (the CLI prints it as "last word"), plus pullRequests and thread.recentRuns (the CLI prints a prs block and a runs block: newest 10, (10 of N runs); --json has every stored run).
• get_session_questions / stage sessions questions ID read pending questions. Agents cannot answer them.
• search_sessions (stage sessions search QUERY [--project P] [--limit N]) wraps GET /api/threads/search and returns { results: [{ t3ThreadId, title, match, snippet?, project?, state?, taskId?, lastWordPreview?, t3WebUrl? }], t3 }.
• imagePaths reads local files and uploads them (POST /api/uploads). CLI and stdio only; HTTP MCP rejects them.
• wait_task polls GET /api/tasks/:id every 3s until the state is in until (default needs_input done settled failed interrupted cancelled) or timeoutSeconds (default 600, max 3600). CLI task wait exits 3 on timeout.

Examples

stage task add --title "Fix flaky test" --prompt "..." --effort high          # backlog
stage task add --title "Deploy" --prompt-file deploy.md --after-me             # runs when this session settles
echo "..." | stage task add --title "Refactor" --prompt - --base-ref origin/main --start
stage task ls --state backlog --json
stage task wait 42 --until done,settled --timeout 30m                          # exit 3 on timeout
stage task order 41 43 42                                                      # 43 runs after 41, 42 after 43
stage sessions show "$T3CODE_THREAD_ID"                                        # this session's batch
stage schedule add --title "Nightly deps" --prompt "..." --cron "0 2 * * *" --tz Asia/Kolkata
stage sessions search "token refresh" --project stage                          # titles, then message text via T3