Agent Runner

Project-centered multi-agent orchestration for VS Code and code-server.

Agent Runner turns VS Code into a local project center for coordinating a Manager and specialized agents. Select a project, open its persistent Chatroom, route work, follow each agent's activity, inspect shared project state, and schedule follow-up work without mixing one repository's context with another.

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

Project Center UI

The AGENT RUNNER PROJECTS Activity Bar view is the entry point for the whole workspace:

• TOWNHALL opens the default coordination project for conversation and work that does not belong to a repository.
• PROJECTS discovers git WorkDirs under a user-selected root. Clicking a project opens or reveals its persistent Chatroom editor tab.
• AGENTS shows Manager first and then configured mailbox agents. Expand an agent to open its first-level Markdown identity, role, soul, and memory files.
• ISSUES shows the selected project's deterministic handoff and audit state.
• AGENDA shows upcoming one-time and repeated work plus recent dispatches.

Each project gets one isolated workspace in the editor. The left side is the human-agent conversation; the right Team side shows one live activity card per agent with thinking and tool progress. Team cards also own terminal, model, and restart controls. Hide Team when the conversation needs the full editor width, or open several project Chatrooms without crossing histories or live events.

Project state survives browser and workbench reloads. The extension restores each open panel's workdir, project_key, JSONL history, and latest Team activity while keeping delivery deterministic.

Core Design

Chatroom is the deterministic, project-bound message room shared by the user, Manager, and configured mailbox agents. Each open Chatroom belongs to exactly one workdir and project_key. The extension, not an agent, owns recipient resolution, one-time user-message persistence, JSONL history, live-event project filtering, and reply correlation. Manager executes through the embedded Pi AgentSession; workers receive per-agent mailbox files. Agent intelligence produces plans and answers, while extension code controls delivery and state.

Messages and Team activity from one project must never appear in another project's Chatroom. Agent-to-agent coordination uses mailbox, project knowledge uses the project module, and system diagnostics use daily logs rather than human chat history.

How To Use

1. Open AGENT RUNNER PROJECTS. Choose TOWNHALL for general coordination or click a repository under PROJECTS. Agent Runner opens that project's Chatroom as an editor tab and keeps it bound to that WorkDir.
2. Click the login button in Chatroom. It opens the packaged Manager Pi terminal. Log in with Codex, then click Chatroom refresh. The login circle is gray when logged out and green when authenticated. Chatroom will show: Now you are ready to use Agent Runner. Use /bootstrap to initialize your workspace.
3. 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.
4. Start working in that project Chatroom. Send an unaddressed message to Manager, select an agent from the composer, mention a specific agent with @agent, or use @channel for all configured mailbox agents.

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.110.0
• An extension host with Node.js >=22.19.0 for the packaged Manager Pi AgentSession runtime. VS Code/code-server ^1.110.0 satisfies this contract.

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 PROJECTS contains TOWNHALL, PROJECTS, AGENTS, ISSUES, and AGENDA. TOWNHALL is first and opens the general coordination Chatroom. PROJECTS lists discovered git WorkDirs; clicking one opens that project's Chatroom in the middle editor panel. Use the PROJECTS + action to choose the folder under which git projects are discovered, and use refresh to rescan it.

Chatroom

Use CHATROOM as the main user-agent message center.

Use TOWNHALL for general coordination that is not tied to a git WorkDir. Use PROJECTS for project-specific threads and shared project knowledge.

• 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.
• Use the model action on the Manager card in Team to choose an openai-codex model registered by packaged Pi. The selection is saved in ~/.agent-runner/agents/manager/model.json and applies to the next Manager request. Model changes are rejected while Manager is working.
• The AGENTS row follows the selected Manager model immediately. Mailbox agent rows use their fresh launcher-reported runtime and explicit --model; they do not guess a model when the CLI leaves model selection to Codex.
• The editor tab is bound to one WorkDir. Open another project row for a separate project Chatroom tab; reopening a project reveals its existing tab.
• Open project Chatroom tabs survive a browser or workbench reload. The extension restores each panel's project binding, subscriptions, JSONL history, and retained Team state.
• The project-bound panel shell opens immediately, then hydrates its Chatroom history, agent labels, connection state, and Team activity in the background. Restoring multiple panels shares runtime/WebSocket initialization and the retained activity-log read instead of repeating that work per tab.
• The bound project name appears at the left of the header; hover it to see the full WorkDir. Team and action controls stay aligned to the right. On a narrow editor, secondary login/export actions move into the … menu.
• 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 mailbox agents. It intentionally excludes Manager; add @manager explicitly when Manager should receive the same message.
• 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 channel-wide 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.
• Upload one or more browser-local files with #. Uploaded files appear as removable #filename chips above the auto-growing input before sending.
• Press Enter to insert a line break and Shift+Enter to send. Use Tab to accept the highlighted @mention or slash-command suggestion.
• Sending, Queued, upload, and failure states are transient composer status; they are not written into Chatroom history.
• Agent names in Chatroom use stable agent-specific text colors on a transparent background so replies remain easy to scan without filled badges.
• On wide editors, Chatroom uses a 60/40 split: conversation stays on the left and the project-scoped Team panel stays on the right. Each agent has one reusable card; new work replaces that card's prior trace, active cards expand, and completed cards collapse.
• The header belongs to the conversation pane. Use its panel toggle to hide Team and give Chatroom the full editor width, or restore the 60/40 split.
• Use the colored dot beside a final reply to focus and expand its matching Team card. On narrow editors, Team is a separate header mode instead of a compressed side panel. Thinking traces are restored from the latest three daily logs and are never copied into permanent Chatroom message text.
• New replies auto-scroll only while the view is already near the bottom. When reading older messages, use the sticky new-message button to return to the latest reply. Loading older history preserves the current reading position.
• Use Chatroom reload to refresh that project's history and Team activity. Use the PROJECTS view refresh action to rescan git projects.

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 all configured mailbox agents to review the WorkDir from their own roles.
• /check-in: ask all configured mailbox agents 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 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.
• Open the config button to edit ~/.agent-runner/agents/config.

Use each agent's card header in the Chatroom Team panel for runtime controls. Worker cards provide terminal attach, model selection, and restart. Manager provides model selection and restart because it is an embedded Pi AgentSession rather than a tmux/screen worker. Mailbox-agent model changes update the agent's CLI= model argument and restart that agent.

Use the Team header + action to add an agent. Enter a creation request with the agent's name, role, focus, purpose, and domain knowledge. The extension sends the request to Manager in the current project Chatroom.

The built-in Manager appears first in AGENTS, followed by configured mailbox agents. Manager shows its Pi AgentSession state, but it is not stored as an agent section in ~/.agent-runner/agents/config. Expanding the Manager row shows its first-level Markdown identity and memory files.

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.

Configured Codex mailbox agents are launched with JSONL streaming enabled. scripts/codex-json-progress.js converts Codex stream events into the same project-scoped per-agent Team cards used by Manager replies. 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.

Issues

Use ISSUES as a compact audit index for the selected project.

• It shows planning, open, working, in review, in test, and done snapshots with the current responsible agent.
• It does not schedule work, manage dependencies, retry tasks, or advance an issue automatically.
• issue_report records state-only intake or corrections.
• An explicit issue_handoff routes the next mailbox task and records the matching audit transition. Failed mailbox delivery rolls that transition back rather than leaving a false handoff state.
• Cleanup handoffs return blocked or stale work to Architect.

Diagnostics

Use the worker's Team-card terminal action for live output. Daily Manager events are stored in logs/YYYY-MM-DD/pi-manager.log; configured mailbox-agent sessions are stored in logs/YYYY-MM-DD/<agent-name>.screen.log. Worker log routing rolls over at local midnight without restarting the tmux/screen session.

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
• logs/YYYY-MM-DD/: consolidated system and agent session logs; normalized thinking.jsonl traces are retained for three days
• agenda/: scheduled work state
• issues/: deterministic audit and handoff skill docs
• projects/: WorkDir-specific shared project knowledge
  • projects/config.json: extension-owned project discovery root
  • projects/<project_key>/chatbox/log/YYYY-MM-DD.jsonl: project-scoped Chatroom history
  • projects/<project_key>/status/index.html: standalone project report artifact
  • projects/<project_key>/issues.jsonl: active project issues
  • projects/<project_key>/issues_done.jsonl: completed project issues

Changelog

5.3.0

• Reframed Agent Runner as a project-centered workspace: one Activity Bar Project Center opens persistent, isolated editor Chatrooms with conversation, Team activity, project issues, scheduling, and agent controls organized around the selected WorkDir.
• Consolidated TOWNHALL, PROJECTS, AGENTS, ISSUES, and AGENDA under one AGENT RUNNER PROJECTS Activity Bar container, with TOWNHALL as the first subview.
• Moved Chatroom out of the sidebar. Selecting a project now opens or reveals one project-bound Chatroom editor tab, and live replies/progress are isolated by project_key across concurrently open tabs.
• Kept Manager as the embedded, resumable Pi AgentSession while configured Codex workers remain one-batch-per-run mailbox agents with JSON progress and final-reply bridging.
• Added Manager model selection, synchronized runtime/model labels, and refined Chatroom header, composer, history loading, scrollbar, and progress UI.
• Split project Chatroom into a responsive 60/40 conversation and Team workspace. Agent thinking now lives in reusable per-agent Team cards, restores from the retained project trace, and can be focused from a final reply's colored dot.
• Added persistent project Chatroom editor panels that restore after a browser or workbench reload.
• Reduced Chatroom startup work: render the editor shell before backend hydration, coalesce runtime/WebSocket initialization, avoid loading the full Pi model registry for display-only labels, load independent panel state in parallel, and share retained thinking-log reads across restored tabs.
• Changed @channel to target configured mailbox agents only. Manager is included only through an explicit @manager, Manager selection, or normal fallback for unaddressed messages.
• Formalized Chatroom as the deterministic one-project message room and made live reply, Team activity, and Manager-working events reject mismatched or unscoped project data.
• Restored the classic Agent Runner cube/chat marketplace logo with its three colored agent dots.
• Added a native PROJECTS + action that selects and persists the git project discovery root, followed by an immediate bounded rescan.
• Added per-agent model Quick Picks with synchronized Manager selection and persistent worker CLI= updates.
• Raised the minimum VS Code/code-server compatibility to ^1.110.0, matching the Node.js runtime required by packaged Pi, and upgraded audited runtime dependencies.
• Serialized Agenda scheduling and dispatch, made active-task writes atomic, and made scheduled inbox delivery atomic.
• Made Chatroom delivery durable: history is persisted before staged mailbox files become visible, replies are persisted before live broadcast, partial deliveries are explicitly audited, and stale adopted endpoints recover.
• Batched contiguous Manager messages for the same project while isolating projects in FIFO order, and made unrecoverable failed batches settle instead of blocking the queue.
• Added local-midnight rollover for worker session logs and retained Manager diagnostics in pi-manager.log.
• Removed the polling OUTPUT subview. Live worker output remains available from the Team-card terminal action, while retained diagnostics stay in daily logs.
• Moved terminal, model, and restart controls from AGENTS rows into each Chatroom Team-card header.
• Changed composer keys to Enter for a line break and Shift+Enter to send.

5.2.6

• Replaced the embedded Chatroom sidebar with an AGENT RUNNER PROJECTS TreeView. Each project opens or reveals a project-bound Chatroom editor tab.
• Merged AGENTS, OUTPUT, ISSUES, and AGENDA into the Projects Activity Bar container and removed the separate legacy Activity Bar icons.
• Isolated live replies and thinking updates by project_key across multiple open project tabs and removed the visible WorkDir dropdown.
• Added Manager model selection and synchronized AGENTS runtime/model labels.

5.2.3

• Made project discovery cache-first and moved bounded Git scanning to the background, with explicit rescanning from the Chatroom reload control.
• Bounded Chatroom rendering to 500 DOM messages and 2,000 in-memory messages while preserving incremental history loading.
• Reduced VSIX size by excluding bundled Pi TypeScript sources/declarations, source maps, documentation, examples, and test files that are not used at runtime.
• Added automatic retention: 30 days for system/session logs, 180 days for project Chatroom JSONL history, and the latest 1,000 Agenda dispatch records.
• Kept bundled Pi at patched version 0.80.6 and added release checks for required runtime files and excluded development files.
• Unified Manager and worker progress as agentThinking, with three-day daily JSONL traces and lazy > disclosure from final Chatroom replies.
• Added deterministic issue_handoff gates that update ISSUES and route the next mailbox task together; blocked cleanup always returns to Architect.
• Kept Kanban as an audit-only project index, with rollback on failed mailbox delivery, serialized issue writes, Relay isolation, and focused regression coverage.

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 operational and audit views into separate Activity Bar containers.
• Added deterministic ISSUES/Kanban workflow states for planning, in test, and done-at-Test-Prod release gates.
• 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 Chatroom messages organized by day 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 state-only corrections use issue_report; normal gate transitions use issue_handoff so Kanban status and the next mailbox route stay correlated.

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.
• Updated bootstrap model intent guidance: Manager Pi should prefer supported quick candidates in order: gpt-5.6-luna, gpt-5.6-terra, then gpt-5.6-sol, while Architect and Review should prefer flagship gpt-5.6-sol.
• Updated Chatroom and AGENTS runtime labels to include concrete model names for all agents, such as Manager (pi-codex/gpt-5.6-luna), Architect (codex/gpt-5.6-sol), and Backend (codex/gpt-5.6-luna).
• Updated Manager Pi startup to prefer supported quick model candidates in order: gpt-5.6-luna, gpt-5.6-terra, then gpt-5.6-sol.

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.
• 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 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.