Agent Runner

Multiple Agents Orchestration for VS Code

Agent Runner adds a local multi-agent workspace to VS Code and code-server. Use it to chat with a manager agent, route messages to specific agents, inspect agent state, and schedule follow-up work.

"If you are not sure how to use Agent Runner, ask the Manager agent inside Chatroom."

How To Use

1. Open AGENT RUNNER CHAT and click the login button in CHATROOM. It opens the packaged Manager Pi terminal. Log in with Codex. After login completes, click the Chatroom refresh button. The login circle is gray when not logged in and green when logged in. Chatroom will show: Now you are ready to use Agent Runner. Use /bootstrap to initialize your workspace.
2. Type /bootstrap to initialize the workspace. This asks Manager to create or refresh the first architect agent, ask it to check in, and record the Chatroom reply contract for future work. It also saves the default project workflow for the selected WorkDir, including Architect-first routing and Review handoff rules when a review agent exists.
3. You can also send a setup command to Manager. For the built-in architect, ask Manager to refine or initialize its role, focus, purpose, and domain knowledge:

Initialize the architect agent with its role, focus, purpose, and domain knowledge.

You can also type /initagent as the first input token. Chatroom replaces it with an editable prompt for creating a new agent and ignores anything typed after the slash command.

To add more agents later, ask Manager:

Add more agent with <name, role, focus, purpose, and domain knowledge>.

Requirements

• VS Code or code-server compatible with VS Code ^1.90.0
• Node.js >=22.19.0 for the packaged manager Pi AgentSession runtime

The VSIX includes the Pi CLI runtime under vendor/pi, so the manager AgentSession path does not require a global pi install. The extension uses VS Code/code-server's built-in terminal surface for terminal views; xterm.js is not vendored.

Usage

Open the Activity Bar:

• AGENT RUNNER CHAT opens CHATROOM.
• AGENT RUNNER TEAM opens AGENTS, GROUPS, and OUTPUT.
• AGENT RUNNER KANBAN opens ISSUES and AGENDA.

Chatroom

Use CHATROOM as the main user-agent message center.

• Type a normal message to send it to manager.
• Use the header login button to open the packaged Manager Pi login terminal when first setting up Pi auth. The circle is gray when not logged in and green when logged in.
• Pick a WorkDir from the project dropdown in the header before sending a project-specific message. The dropdown stays compact in the header and shows full paths when opened.
• Use the robot icon in the input bar to filter the chat history to one agent. When an agent is selected there, new messages are routed to that agent.
• Use @agent mentions to route directly to specific agents, for example @architect review this design.
• A selected agent and @mentions are additive. For example, if architect is selected and the message contains @backend, both agents receive the message.
• Use @channel to send to all configured agents. Use @group_<name> to send to every agent in a configured group. @group_all is intentionally omitted; use @channel for all agents.
• Type / as the first input character to show built-in prompt helpers: /initagent, /bootstrap, /review, /check-in, /system-reload-agents, /update-skill, /setmorningcall, /report, and /workflow.
• Submitting a slash helper first writes the generated message into Chatroom, then executes it. /review and /check-in are group helpers and include @channel; /initagent, /bootstrap, /setmorningcall, /report, and /workflow are Manager helpers. /system-reload-agents and /update-skill are deterministic system helpers.
• Mention multiple agents to send one copy to each target, for example @architect @backend compare the implementation options.
• Agent names in Chatroom have stable colored badges so replies are easier to scan. The badge color is tied to the canonical agent name.
• Use the chat bubble / web icon switch before the WorkDir dropdown to switch between Chatroom and the selected project's status/index.html page. The page is loaded directly into the webview, so code-server does not need a remote vscode-resource host for this view.
• Use reload to refresh chat history and rebuild the project list. In web mode, reload also rereads the selected project's status/index.html.

Slash Helpers

Slash helpers write their generated message into Chatroom first, then run.

• /initagent: ask Manager to create a new agent and initialize its files.
• /bootstrap: ask Manager to initialize the first architect agent, ask it to check in, record the Chatroom reply contract for future work, and save the selected WorkDir's default project workflow with Architect-first routing and Review handoff rules.
• /review: ask the current group to review the WorkDir from each agent's own role.
• /check-in: ask the current group for concise human check-ins.
• /setmorningcall: ask Manager to schedule a daily 8:00 AM SGT check-in.
• /report: ask Manager for a concise project report and update the selected project's white-theme status/index.html page after the requested agent reports finish.
• /workflow: ask Manager to show or generate the project workflow.
• /system-reload-agents: reload agents and groups from config.
• /update-skill: clone or pull Agent Runner skills into ~/.agent-runner/skills.

Agents

Use AGENTS to inspect and control local agents.

• Expand an agent to see its first-level Markdown files.
• Click an agent to switch OUTPUT to that agent.
• Use the inline terminal button to attach to the agent tmux/screen session.
• Use the inline restart button to restart one agent.
• Open the config button to edit ~/.agent-runner/agents/config.

The manager is the Chatroom Pi AgentSession runtime, so AGENTS lists only configured mailbox agents.

Manager Chatroom replies use a long-lived packaged Pi AgentSession. When the extension restarts, the next manager AgentSession continues the most recent manager session from ~/.agent-runner/agents/manager/.pi-sessions. The embedded Pi AgentSession lifecycle is managed by src/agents.ts; Chatroom owns routing, history, and UI.

Groups

Use GROUPS to see which configured agents belong to each group. Group membership comes from each agent's GROUPS= setting in ~/.agent-runner/agents/config. Every configured agent is always shown under all; agents can also belong to any number of additional groups. In Chatroom, mention a group with @group_<name> to route the message to that group.

Configured Codex mailbox agents are launched with JSONL streaming enabled. scripts/codex-json-progress.js converts Codex stream events into the same collapsible thinking panel used by Manager replies, labeled with the agent name. The bridge summarizes useful stream details such as shell commands, file reads, searches, compile runs, failures, and concise agent progress messages.

Agenda

Use AGENDA to inspect scheduled work.

• ONE-TIME shows pending delayed tasks.
• REPEATED shows repeating tasks.
• DISPATCHED shows the latest dispatched tasks.
• Use Process Due Agenda Now to process due work immediately.

Agents schedule delayed or repeated work through Agent Runner; scheduled tasks are delivered back into the target agent inbox when due.

Output

Use OUTPUT to read the selected agent session log. The default output is the manager log.

Runtime Files

Agent Runner stores runtime state under:

~/.agent-runner

Important folders:

• agents/: agent config and per-agent working folders
• mailbox/: per-agent inbox and processed messages
• chatbox/: Chatroom endpoint state and UI-owned chatbox module files
• agenda/: scheduled work state
• issues/: deterministic issue-reporting skill docs
• projects/: WorkDir-specific shared project knowledge
  • projects/<project_key>/chatbox/log/YYYY-MM-DD.jsonl: project-scoped Chatroom history
  • projects/<project_key>/status/index.html: page shown by Chatroom web mode
  • projects/<project_key>/issues.jsonl: active project issues
  • projects/<project_key>/issues_done.jsonl: completed project issues

Changelog

5.2.0

• Improved Manager Pi robustness with stronger request correlation, safer retry and restart handling, visible Manager status, and an inline restart control in AGENTS.
• Split the Activity Bar into AGENT RUNNER TEAM for AGENTS/GROUPS/OUTPUT and AGENT RUNNER KANBAN for ISSUES/AGENDA.
• Added deterministic ISSUES/Kanban workflow states for planning, in test, and done-at-Test-Prod release gates, with status-only issue updates kept separate from mailbox routing.
• Added the root KANBAN.md skill and runtime install path so agents share the same tracked-issue handoff contract after extension activation.
• Added human-readable JSON/JSONL rendering for AGENTS OUTPUT while preserving useful command/tool/function payload details.
• Included Relay runtime and documentation hardening, including stale websocket reconnect handling and rejection of inbound deterministic control actions.
• Refreshed Agent Runner skills/docs for Manager -> Architect -> Review -> Test-Prod handoffs, package/runtime skill installation, and 5.2.0 release gating.

5.1.0

• Added Chatroom transcript export/download for the selected project as a standalone HTML file.
• Exported transcripts include project metadata, generated timestamp, message count, and day-grouped Chatroom messages from project-scoped history.
• Kept transcript generation deterministic and offline-friendly with escaped message content and a restrictive exported HTML content security policy.
• Moved the project Chatroom log path helper into the projects module for reuse by export and Chatroom code.
• Includes the recent 5.0.2 label/workflow updates: concrete runtime/model labels, Manager quick-model preference, default Manager -> Architect -> Review workflow, and clean Review -> Test-Prod make reinstall release gate.
• ISSUES status updates remain deterministic and status-only: agents update in review, in test, and done through control events at Review/Test-Prod handoff boundaries while mailbox/project workflow still owns routing.

5.0.2

• Added Chatroom history loading across the latest two non-empty project days.
• Added a compact -- load more -- history separator to load older days one at a time.
• Improved the project dropdown so compact labels show more of the project name while still exposing full paths when opened.
• Updated /bootstrap to install the default Manager → Architect → Review workflow:
  • Manager rewrites user input into clear tasks and routes to Architect when present.
  • Architect decides whether to handle work or assign it to another agent.
  • Review is code-review-only by default and reviews code/config/doc/workflow changes when available.
  • Clean Review results route directly to Test-Prod for make reinstall; Review findings or Test-Prod failures route back to Architect for fix ownership.
• Added bootstrap model intent guidance: Manager Pi should prefer quick models such as gpt-5.5-nano or gpt-5.5-mini, while Architect should prefer a flagship model such as gpt-5.5 or the closest supported equivalent.
• Updated Chatroom and AGENTS runtime labels to include concrete model names for all agents, such as Manager (pi-codex/gpt-5.5-mini), Architect (codex/gpt-5.5), and Backend (codex/gpt-5.5-mini).
• Updated Manager Pi startup to prefer supported quick model candidates in order: gpt-5.5-mini, gpt-5.5-nano, then gpt-5.5.

4.1.0

• Added the compact Chatroom project dropdown in the header with full path labels when opened.
• Moved agent filtering into the input bar as a robot icon selector.
• Removed the group selector from the input bar; Chatroom group routing now uses @group_<name> mentions and @channel for all agents.
• Made selected-agent routing additive with @mentions.
• Improved agent-filtered history so it shows the selected agent replies with the relevant user prompts.
• Added stable colored agent-name badges in Chatroom.
• Added built-in project web report/status support for each selected WorkDir.
• Added the web introduction page and screenshots under web/agent-runner/.

0.4.0

• Added GROUPS subview for config-driven agent group membership.
• Normalized agent groups around GROUPS= and built-in all.
• Added Chatroom slash helpers for agent creation, review, check-ins, workflow, reports, morning calls, agent reload, and skill updates.
• Added project workflow contract with role/task ownership, handoff rules, Manager check loops, and success/failure criteria.
• Added per-message runtime labels such as Manager (pi-codex) and Architect (codex).
• Added packaged Manager Pi Codex runtime flow and login button.
• Added ~/.agent-runner/skills/SKILL.md reference for downloaded skills.