Show HN: Agent Office (Slack for AI Agents) – Similar to Grok Bot but older

Agent Office, a multi-agent workspace manager built on Pi, orchestrates AI coding agents with tick-based scheduling, priority queues, inbox IPC, cross-agent file access, watchdog monitoring, cron jobs, optional Docker sandbox isolation, and declarative YAML configuration. The tool, similar to Claude Code or OpenClaw, supports teams like basic-team, OpenServ team, and feature team, and requires pnpm install and environment setup. It offers in-process or Docker sandbox modes and includes a Web UI.

Multi-agent workspace manager built on Pi https://github.com/badlogic/pi-mono . Orchestrates AI coding agents — similar to Claude Code or OpenClaw — with tick-based scheduling, priority queues, inbox IPC, cross-agent file access, watchdog monitoring, proactive cron jobs, optional Docker sandbox isolation, and declarative YAML configuration. agent-office.mp4 Try one of these examples to get up and running quickly. Set env vars in the project root .env not inside Docker — the host forwards them to containers . Basic team — PM, coder, and reviewer uses GitHub Copilot OAuth, no API keys : pnpm install cp -r examples/basic-team/ ~/.agent-office/offices/basic-team/ pnpm dev oauth login github-copilot --office basic-team pnpm dev start --office basic-team --sandbox docker OpenServ team — idea scout, team lead, agent dev, and token launcher: pnpm install cp .env.example .env mkdir -p ~/.agent-office/offices/openserv-team cp examples/openserv-team/office.yaml ~/.agent-office/offices/openserv-team/office.yaml pnpm dev start --office openserv-team --sandbox docker OPENAI API KEY= WALLET PRIVATE KEY= EVM wallet key for openserv-labs/skills agents Feature team — task-driven development with Kanban board: cp -r examples/feature-team/ ~/.agent-office/offices/feature-team/ pnpm dev start --office feature-team See examples/ /baturyilmaz/agent-office/blob/main/examples for more details — each has a README describing the setup. Architecture architecture Quick Start quick-start OAuth Authentication oauth-authentication Multi-Office Architecture multi-office-architecture Sandbox Modes sandbox-modes Commands commands Agent Tools agent-tools Concepts concepts Prompt Inspection prompt-inspection Cost Tracking cost-tracking Web UI web-ui End-to-End Examples end-to-end-examples Project Structure project-structure Dependencies dependencies Development development php graph TD YAML office.yaml -- WS CLI CLI + Web UI -- WS Workspace WS -- SCH Scheduler\ntick loop WS -- BUS MessageBus\ninboxes WS -- WD Watchdog\nheartbeat WS -- CRON CronService\nscheduled jobs WS -- TS TaskService\nKanban board WS -- |in-process| A Agent A\nPi · tools · skills WS -- |in-process| B Agent B\nPi · tools · skills WS -- |Docker sandbox| HA Host API\nHTTP :13000 HA <-- |HTTP| SA Sandbox A\nDocker · Pi · proxy tools HA <-- |HTTP| SB Sandbox B\nDocker · Pi · proxy tools BUS -- A BUS -- B BUS -- HA Core flow: office.yaml auto-spawn / CLI / Web UI / Cron / Agent cron tools / Task notifications - Workspace - Scheduler tick - drain inbox - dispatch to Pi Agent - agent runs tools - response streamed to UI. Each agent is a full Pi coding agent with its own filesystem workspace, skills, and injected tools message user , post channel , message agent , list agents , read agent file , authenticated fetch , cron add , cron remove , cron list , task create , task update , task list , task get , task delete , read skill , skill search , skill install , skill remove , skill create . The scheduler runs a tick loop that serves agents by priority, one message per tick per agent, non-blocking. Agents can run in-process default or inside Docker containers for full process-level isolation. pnpm install Configure .env cp .env.example .env then fill in your keys Create an office pnpm dev office create my-team Start Web UI auto-starts pnpm dev start --office my-team Start with Docker sandbox isolation pnpm dev start --office my-team --sandbox docker Create a .env file with your provider API keys. Each model requires its corresponding provider key: Model API Keys required for agents using these models OPENAI API KEY=sk-... For OpenAI models gpt-4o, etc. ANTHROPIC API KEY=sk-... For Anthropic models Claude, etc. GEMINI API KEY=... For Google Gemini models XAI API KEY=... For xAI Grok models Optional: Custom secret refs for office.yaml agents MY GH TOKEN=ghp ... Host env vars for authenticated fetch secrets Authentication: Each model needs credentials. You can use either API keys .env or OAuth: API keys — set in .env e.g. OPENAI API KEY=sk-... . Required when the model's provider has no OAuth credentials. OAuth — authenticate via provider CLIs before starting. OAuth tokens auto-refresh and don't require .env keys. Option A: API keys in .env echo "ANTHROPIC API KEY=sk-..." .env Option B: OAuth login requires provider CLI installed pnpm dev oauth login anthropic --office my-team pnpm dev oauth list --office my-team When both OAuth credentials and an API key exist for a provider, you can switch between them per-agent in the Web UI. See OAuth Authentication oauth-authentication for details. See the Dynamic Model Discovery section below for how to browse available models and their requirements in the Web UI. As an alternative to API keys in .env , agents can authenticate with model providers via OAuth. This uses the provider's own CLI login flow — the agent-office CLI orchestrates the browser-based OAuth handshake and stores credentials per office. | Provider ID | Name | Flow Type | Requires | |---|---|---|---| anthropic | Anthropic | Code paste | Anthropic CLI | openai-codex | OpenAI | Callback server | OpenAI Codex CLI | github-copilot | GitHub Copilot | Code paste | GitHub Copilot CLI | google-gemini-cli | Google Gemini CLI | Callback server | Gemini CLI | google-antigravity | Antigravity | Callback server | Antigravity CLI | Code paste providers open a browser URL and prompt you to paste back an auth code. Callback server providers start a local HTTP server and complete the flow automatically. Login — interactive OAuth flow opens browser pnpm dev oauth login <provider --office <id List — show all providers and credential status pnpm dev oauth list --office <id Logout — remove stored credentials pnpm dev oauth logout <provider --office <id Example session: bash $ pnpm dev oauth login anthropic --office my-team oauth Logging in to Anthropic... oauth Open this URL to authenticate: https://console.anthropic.com/oauth/... Paste the authorization code: oauth Credentials saved for Anthropic. $ pnpm dev oauth list --office my-team ✓ anthropic Anthropic ✗ openai-codex OpenAI ✗ github-copilot GitHub Copilot ✗ google-gemini-cli Google Gemini CLI ✗ google-antigravity Antigravity Login: pnpm dev oauth login <provider --office my-team Logout: pnpm dev oauth logout <provider --office my-team Credentials are stored at ~/.agent-office/offices/<id /oauth/<provider .json and auto-refresh when tokens expire. Set the auth field on an agent to use OAuth instead of an API key: agents: designer: model: anthropic:claude-sonnet-4-20250514 auth: "oauth:anthropic" use OAuth credentials reviewer: model: openai:gpt-4o auth: "oauth:openai-codex" use OAuth credentials analyst: model: google:gemini-2.0-flash no auth field — falls back to GEMINI API KEY from .env The auth field format is oauth:<provider-id . When set, the agent uses stored OAuth credentials with automatic token refresh instead of a static API key. When OAuth credentials exist for an agent's model provider, the Web UI Config tab shows an Auth selector to switch between "API Key" and "OAuth" modes. The UI also displays all authenticated providers as green badges with one-click removal. The auth selector only appears when credentials are available — if no OAuth login has been done for a provider, agents use API keys by default. | Method | Path | Description | |---|---|---| GET | /api/oauth/providers | List all providers with authentication status | GET | /api/oauth/status/:id | Check if credentials exist for a provider | DELETE | /api/oauth/:id | Remove stored credentials for a provider | Each office represents a company or team with shared identity, env vars, and secrets. Offices live under ~/.agent-office/offices/<id / . Create with default display name same as id pnpm dev office create acme Create with a custom display name pnpm dev office create acme --name "Acme Corp" Office IDs must be path-safe: lowercase letters, digits, hyphens, underscores matching a-z0-9 a-z0-9 - . The display name office.name in YAML is free-form. Define your office once in ~/.agent-office/offices/<id /office.yaml and agents auto-spawn on startup. ~/.agent-office/offices/acme/office.yaml office: name: Acme Corp description: "We build AI-powered widgets" env: SHARED API URL: https://api.acme.com secrets: SHARED TOKEN: ${ACME TOKEN} cron: standup: schedule: "0 9 1-5" report channel: general tasks: - title: "Daily standup" assignee: pm agents: designer: model: anthropic:claude-sonnet-4-20250514 priority: normal idle | low | normal | high | critical or 0-4 thinking: low off | minimal | low | medium | high | xhigh description: "Frontend designer — builds HTML/CSS" prompt inline: | You are a frontend designer specializing in responsive layouts. Focus on clean, semantic HTML and modern CSS. skills: - nichochar/web-skills auth: "oauth:anthropic" optional — use OAuth instead of API key api key ref: MY CUSTOM KEY optional — host env var name for model key override env: non-sensitive, passed as Docker --env agent overrides office LOG LEVEL: debug WORKSPACE NAME: designer secrets: sensitive, ${VAR} refs only — delivered via authenticated fetch GITHUB TOKEN: ${MY GH TOKEN} disclose secrets: true show secret names in system prompt default: false permissions: office cron: true allow managing office-level cron jobs reviewer: model: openai:gpt-4.1 priority: high thinking: medium description: "Code reviewer" Office-level env and secrets are inherited by all agents. Agent-level values override office-level. All agent fields are optional. Agents are spawned sequentially in declaration order; if one fails, the rest still start. Model availability depends on your provider account — replace the model value with your preferred provider:model-id if the default is unavailable. | Field | Type | Default | Description | |---|---|---|---| model | string | anthropic:claude-sonnet-4-20250514 | provider:model-id | priority | string | number | normal | Priority name or 0-4 | thinking | string | low | off / minimal / low / medium / high / xhigh | description | string | "" | Visible to other agents | prompt inline | string | none | Custom instructions inline text, appended to base prompt | cwd | string | ~/.agent-office/offices/<id /agents/<name /workspace | Working directory | skills | string | | GitHub sources to auto-install owner/repo | auth | string | none — uses API key | Auth mode: oauth:<provider-id for OAuth see | api key ref | string | auto from provider | Host env var name for model API key | env | map | {} | Non-sensitive env vars Docker --env , supports ${VAR} refs | secrets | map | {} | Secret refs in ${VAR} format delivered via authenticated fetch | disclose secrets | boolean | false | Show secret names in system prompt | cron | map | {} | Named cron jobs see | reports to none — reports to user Hierarchy hierarchy permissions {} Permissions permissions , Tool Policy tool-policy prompt mode "full" full all blocks or minimal base + identity + custom only on demand skills true read skill heartbeat none Heartbeat heartbeat Task tools task create , task update , task list , task get , task delete are available to all in-process agents by default. Restrict access via permissions.tools.deny . See Task Management task-management . Agents can run proactively via heartbeats — periodic messages that prompt agents to check for work or run maintenance without external triggers. agents: monitor: heartbeat: interval ms: 60000 prompt: "Check for pending work and report status" active hours: start: "09:00" end: "17:00" | Field | Required | Default | Description | |---|---|---|---| interval ms | yes | — | Interval in milliseconds between heartbeats | prompt | no | default | Custom prompt text for heartbeat messages | active hours | no | none | Restrict heartbeats to a time window | Heartbeat messages are injected with from: " heartbeat " and formatted as Heartbeat \n<prompt . Busy agents status running are skipped. The permissions field controls which privileged operations an agent may perform: | Permission | Type | Default | Description | |---|---|---|---| office cron | boolean | false | Allow managing office-level cron jobs via cron add / cron remove | Permissions are validated at config parse time. Unknown keys or non-boolean values are rejected. The permissions.tools field restricts which tools an agent may use: agents: restricted-bot: permissions: tools: deny: cron add, cron remove blacklist — all except these OR allow: message agent, list agents whitelist — only these — blacklist: agent has all tools except the listed ones. deny — whitelist: agent has only the listed tools. allow - Cannot specify both allow and deny — validation error at parse time. - Default no tools field : all tools available. Server-side enforcement: in Docker sandbox mode, denied tools also return HTTP 403 on the corresponding Host API endpoint e.g. /api/cron-add returns 403 Tool denied by policy . Defaults: office cron is false ; tools are all allowed unless allow or deny is set. Setting both allow and deny is a validation error. View permissions in the Web UI or edit via the API without editing YAML manually: agent permission show bot agent permission set bot office cron true agent permission set bot tools deny cron add,cron remove agent permission clear bot office cron agent permission clear bot tools Changes are saved to office.yaml . Run office reload --force to apply. The reports to field defines a manager for each agent, creating an org tree. Agents without reports to report directly to the user. The hierarchy is injected into the system prompt so each agent knows its manager, peers, and direct reports. agents: lead: description: "Team lead" coder: reports to: lead reviewer: reports to: lead Validation rules: - Must reference a valid agent name same a-zA-Z0-9 - + format - Self-reference is rejected - Cycles are detected and rejected e.g. A reports to B, B reports to A - Unknown agent references are rejected Hierarchy changes trigger agent restarts prompts are recomposed with updated context . Commands automatically keep office.yaml in sync: persists the agent to YAML use hire --ephemeral to skip removes the agent from YAML fire updates the agent's skill add/remove skills array in YAML GitHub source model skills.sh package installs skill search / skill install tools or UI install write files under agents/<agent /skills but do not auto-edit office.yaml . All writes are atomic temp file + rename and serialized through a two-layer lock in-process queue + cross-process file lock per office. API command strings UI has equivalent controls : office reload Spawn new agents from YAML, skip already-running office reload --force Kill and re-spawn agents with changed config office validate Dry-run: parse + validate without spawning office path Print path to office.yaml Agents can run proactively on schedules via per-agent cron jobs. The host-side CronService manages timers and creates structured tasks via TaskService — giving cron-triggered work full Kanban visibility, dependency chaining, and completion reporting. Breaking change: message and targets fields have been replaced by a tasks array. Each task requires title and assignee . In office.yaml under the agents section: agents: standup-bot: model: anthropic:claude-sonnet-4-20250514 cron: daily-standup: schedule: "0 9 1-5" 5-field only min hour dom month dow timezone: "America/New York" optional, default UTC catch up: once optional: "skip" default | "once" enabled: true optional, default true report channel: general optional, post completion summary to this channel tasks: - title: "Daily standup report" description: "Report your status for today's standup" assignee: standup-bot | Field | Required | Default | Description | |---|---|---|---| schedule | yes | — | 5-field cron expression @daily / @hourly rejected | tasks | yes | — | Array of task templates; each requires title and assignee | timezone | no | UTC | IANA timezone for schedule evaluation | catch up | no | skip | skip = ignore missed fires on restart; once = fire one catch-up task | enabled | no | true | Set false to pause without removing | report channel | no | none | Channel name to post task completion summaries to | Each task in the tasks array supports: | Field | Required | Description | |---|---|---| title | yes | Task title shown in Kanban board | assignee | yes | Agent name to assign the task to | description | no | Detailed instructions for the assignee | parent id | no | Parent task ID T-prefixed to nest under | report channel | no | Per-task channel override for completion notification | Job names must match a-zA-Z0-9 - + . Each agent can have 0-N named jobs max 10 per agent via tools . Task chaining: Multiple tasks in a single cron job are automatically chained — each task depends on the previous one completing. The chain fires with CRITICAL priority. Catch-up behavior: On restart, if catch up: once and a fire was missed since the last run, one immediate task chain is created. First-ever run no prior state never catches up. State persists to ~/.agent-office/offices/<id /cron/state.json . Safety guards: Tasks are always created regardless of agent status — they queue in the agent's inbox. A global dispatch cap of 60 cron jobs per minute prevents misconfigured schedules from flooding the task queue. API command strings UI has equivalent controls : cron list List all cron jobs cron status agent Detailed job status cron add <agent <job "<schedule " --apply Add a job prompts for task title/assignee cron remove <agent <job --apply Remove a job cron trigger <agent <job Fire immediately cron enable <agent <job --apply Re-enable a paused job cron disable <agent <job --apply Pause a job Without --apply , commands write to office.yaml only — run office reload to activate. With --apply , changes take effect immediately if the agent is running. Change detection uses normalized config comparison resolved model, numeric priority, sorted skills, trimmed prompt so cosmetic YAML differences like normal vs 2 or reordered skills don't trigger false warnings. In addition to per-agent cron, you can define office-level cron jobs that create task chains across multiple agents: In office.yaml under the office section: office: cron: standup: schedule: "0 9 1-5" timezone: "America/New York" report channel: general tasks: - title: "Daily standup report" description: "Report your status for today's standup" assignee: pm - title: "Standup review" description: "Review and summarize the standup reports" assignee: lead weekly-review: schedule: "0 17 5" tasks: - title: "Weekly progress summary" description: "Summarize this week's progress" assignee: pm | Field | Required | Default | Description | |---|---|---|---| schedule | yes | — | 5-field cron expression | tasks | yes | — | Array of task templates; each requires title and assignee | timezone | no | UTC | IANA timezone for schedule evaluation | catch up | no | skip | skip = ignore missed fires on restart; once = fire one catch-up task | enabled | no | true | Set false to pause without removing | report channel | no | none | Channel name to post task completion summaries to | Assignee names are validated at parse time. Typos fail fast: office office.cron.standup: unknown assignee agent "codre" Activation: YAML edits require office reload to take effect. Commands with --apply take effect immediately. Office cron commands: cron add office <job "<schedule " prompts for task title/assignee cron remove office <job cron trigger office <job fire immediately Office jobs appear in cron list with an office scope tag. The global 60/minute dispatch cap applies. In addition to operator-managed cron Web UI/API , agents can self-manage cron jobs via three built-in tools: cron add , cron remove , and cron list . cron trigger remains operator-only. Agent scope default — agents manage their own jobs with no special permission. Max 10 jobs per agent. agent calls cron add: name: "nightly-report" schedule: "0 22 " tasks: - title: "Generate nightly summary report" assignee: "self" - Cron job "nightly-report" saved and activated At 10:00 PM . Office scope — requires permissions: { office cron: true } in office.yaml. Tasks can be assigned to any agent. agent calls cron add: name: "standup" schedule: "0 9 1-5" scope: "office" tasks: - title: "PM standup report" description: "Report your status" assignee: "pm" - title: "Coder standup report" description: "Report your status" assignee: "coder" - Cron job "standup" saved and activated At 09:00 AM, Monday through Friday . Visibility: cron list shows all office-level jobs plus only the calling agent's own agent-scope jobs. No cross-agent visibility. Error handling: Malformed or invalid office.yaml returns a tool error — no silent success. Validation errors bad schedule, unknown assignees , parse failures, and permission denials all produce explicit error messages. Audit trail: Every action success, denial, or error is logged to <officeDir /logs/cron-audit.jsonl and printed to stdout with cron-audit prefix. Security: Agent-scope writes are isolated to the calling agent's YAML section identity derived from auth token . All mutations run under withOfficeLock with race-free activation from the same parsed document. Agents can create, assign, and track tasks through a shared Kanban-style task system. The TaskService manages task state, enforces status transitions, resolves dependency chains, and dispatches notifications via the message bus. Task tools task create , task update , task list , task get , task delete are registered as default tools for all agents. Restrict access per agent via permissions.tools.deny . Task proxy endpoints are available via Host API. Cron integration: Cron jobs now create tasks instead of sending messages. Tasks fired by cron are tagged with createdBy: " cron " and appear in the Kanban board with CRITICAL priority. Use task list with createdBy: " cron " to query them. Task completion can trigger a channel notification via the report channel field on the task or on the parent cron job definition. Tasks follow a Kanban status flow with enforced transitions: waiting → todo → in progress → done → failed | Status | Allowed transitions | |---|---| waiting | todo | todo | in progress | in progress | done , failed | done | terminal | failed | terminal | Tasks can be deleted from any state. Deleting a task cleans up dependency references and auto-unblocks dependent tasks. Dependency behavior: Tasks created with dependsOn start in waiting regardless of the requested status. When all dependencies reach done , the TaskService auto-transitions the blocked task to todo and sends a Task Ready notification to the assignee. Notifications: New task assignments dispatch New Task messages. Dependency resolution dispatches Task Ready messages. Both are sent from task via the message bus. The message bus applies a dedicated higher limit for task notifications 40 messages / 30s so task events are less likely to be dropped under bursty updates. Audit trail: All task mutations are logged to <officeDir /logs/task-audit.jsonl . Persistence: Task state is stored at <officeDir /tasks/tasks.json . Agents interact with tasks via four built-in tools: agent calls task create: title: "Implement login page" description: "Build login form with email/password fields and validation" assignee: "coder" dependsOn: - Created task T-a1b2c3 status: todo - New Task notification sent to coder agent calls task update: id: "T-a1b2c3" status: "done" result: "Implemented login with email/password auth" - Task T-a1b2c3 updated to done - Dependent tasks auto-transition to todo php agent calls task list: assignee: "coder" status: "in progress" - Returns filtered list of tasks php agent calls task get: id: "T-a1b2c3" - Returns full task details title, description, status, assignee, dependencies, timestamps task list --assignee <agent --status <status List/filter tasks task board Kanban board view task get <id Show task details The Web UI includes a Kanban board accessible from the sidebar "Tasks" item. Columns: waiting, todo, in progress, done. Filter by agent using the segmented control. Click a task card to view full details or delete it. If you have a legacy ~/.agent-office/agents.yaml , migrate to the multi-office format: Preview what will happen pnpm dev office migrate --name my-team --dry-run Run the migration copies data, renames agents.yaml → agents.yaml.bak pnpm dev office migrate --name my-team Verify everything works pnpm dev start --office my-team Clean up old files prompts for confirmation pnpm dev office migrate --name my-team --finalize Starting with a legacy agents.yaml present will fail with a migration prompt. agent-office supports two execution modes for agents: pnpm dev start --office my-team or explicitly: pnpm dev start --office my-team --sandbox none Agents run in the same Node.js process as the scheduler. Simple, fast, zero setup. Tools call directly into the message bus and filesystem. Best for: development, single-user setups, trusted agent code. pnpm dev start --office my-team --sandbox docker Each agent runs inside an isolated Docker container with hardened security. Agents communicate with the host via HTTP through the Host API. Best for: untrusted agent code, multi-tenant environments, production deployments. Requirements: Docker must be installed and running. Build tooling: The sandbox image includes python3 , make , and g++ so agents can npm install packages with native addons node-gyp . Host Process Docker Container per agent +---------------------------+ +-----------------------------+ | Workspace | | sandbox-entry.ts | | Scheduler + MessageBus | | Pi Agent + coding tools | | Host API server :13000 |<-HTTP | Proxy tools HTTP- Host | | DockerProvider | | HTTP server :3100 | | Watchdog | | Heartbeat loop 5s | +---------------------------+ +-----------------------------+ Workspace generates a unique auth token per agent and registers it with the Host API. DockerProvider builds the pi-sandbox Docker image once , then runs a container per agent with: --cap-drop=ALL — no Linux capabilities --security-opt no-new-privileges — no privilege escalation --user 1000:1000 — non-root user- Volume mount: host workspace directory - /workspace in container sandbox-entry.ts inside container creates a Pi Agent with:- Local coding tools read, write, edit, bash, grep, find, ls scoped to /workspace - Proxy tools that forward message user , post channel , message agent , list agents , read agent file , authenticated fetch , task create , task update , task list , task get , task delete , read skill , skill search , skill install , skill remove , skill create to the Host API over HTTP - Local coding tools read, write, edit, bash, grep, find, ls scoped to Host API authenticates requests via Bearer token, executes them against the message bus / filesystem, and returns results. Prompt flow: Host sends POST /prompt to container - agent processes - container sends POST /api/prompt-done back to host. Heartbeat: Container sends POST /api/heartbeat every 5 seconds. Watchdog monitors these for stuck detection. | Protection | Mechanism | |---|---| | Process isolation | Separate Docker container per agent | | No root access | --user 1000:1000 , --cap-drop=ALL , no-new-privileges | | Filesystem isolation | Only the agent's own workspace is mounted | | Secret isolation | Model API key via GET /api/secrets memory-only, never in Docker env | | Tool secret isolation | Per-agent secrets resolved host-side via authenticated fetch — never enter container | | Output redaction | Two-layer: sandbox-side + host-side redaction of secrets in events and fetch responses | | SSRF protection | Two-layer: literal IP check + DNS resolution blocks private, loopback, link-local, IPv4-mapped IPv6 | | Cross-agent file access | Proxied through Host API with path traversal guards | | Authentication | Unique per-agent Bearer token on all endpoints except /health | | Message integrity | Server derives sender identity from token, never trusts body | | Idempotency | messageId -based deduplication with 5-minute TTL | | Request limits | 64 KB message-agent body, 1 MB general body, 1 MB file response | | Prompt timeout | 5-minute timeout on prompt completion | Terminal 1: Start with Docker sandbox pnpm dev start --office acme --sandbox docker API command strings UI has equivalent controls : hire designer --model anthropic:claude-sonnet-4-20250514 --desc "Frontend designer" → agent:designer Started in sandbox http://localhost:13100 hire reviewer --model openai:gpt-4.1 --desc "Code reviewer" → agent:reviewer Started in sandbox http://localhost:13101 send designer "Create a responsive landing page with hero section" → designer works inside its Docker container, edits files in /workspace → Files persist at ~/.agent-office/offices/acme/agents/designer/workspace/ on the host send reviewer "Review designer's index.html and send feedback" → reviewer uses read agent file proxied via Host API to read designer's files → reviewer uses message agent proxied via Host API to send feedback to designer Verify files created by sandboxed agents persist on the host: ls ~/.agent-office/offices/acme/agents/designer/workspace/ index.html styles.css ... The Host API runs on port 13000 configurable and provides the bridge between sandboxed agents and the host system. | Method | Path | Purpose | |---|---|---| GET | /api/secrets | Fetch secrets model API key + tool secrets at container boot | POST | /api/message-user | Send a DM to the human user egress, idempotent | POST | /api/post-channel | Post a message to a channel egress, rate-limited | POST | /api/message-agent | Forward message to another agent's inbox | GET | /api/agents | List all agents name, status, description | GET | /api/agent-file?agent=X&path=Y | Read file from another agent's workspace | POST | /api/authenticated-fetch | Host-proxied HTTP request with secret injection | POST | /api/cron-add | Add or update a cron job auth required, identity from token | POST | /api/cron-remove | Remove a cron job auth required, identity from token | POST | /api/cron-list | List cron jobs visible to the calling agent auth required | POST | /api/prompt-done | Notify host that a prompt completed | POST | /api/agent-event | Forward agent events to host redacted | POST | /api/heartbeat | Update agent heartbeat timestamp | POST | /api/task-create | Create a task auth required | POST | /api/task-update | Update a task auth required | POST | /api/task-list | List tasks auth required | POST | /api/task-get | Get task details auth required | POST | /api/task-delete | Delete a task auth required | POST | /api/read-skill | Read full skill content auth required | POST | /api/skill-search | Search skills registry auth required | POST | /api/skill-install | Install a skill from registry auth required | POST | /api/skill-remove | Remove an installed skill auth required | POST | /api/skill-create | Create a custom skill auth required | POST | /api/tool-count | Report agent tool count auth required | All endpoints require Authorization: Bearer <token header. The token is generated per agent by the host and injected into the container as an environment variable. Model API keys are never passed as Docker env vars — they are fetched via GET /api/secrets at boot and stored in memory only. Runtime operations are available through two surfaces: Typed REST API — dedicated endpoints for each operation e.g. POST /api/agents to hire, DELETE /api/agents/:name to fire, PATCH /api/agents/:name/prompt to update prompt . See REST API Endpoints rest-api-endpoints for the full list.— structured endpoint for sending messages to agents POST /api/send { "agent": "<name ", "message": "<text " } . The Web UI has dedicated controls buttons, forms, modals for common operations — hire, fire, send, cron, reload — that call these typed endpoints internally. The table below lists all available operations and their descriptions: | Command | Description | |---|---| hire <name options | Create a new agent persists to YAML unless --ephemeral | roster | Show all agents with status table | send <agent <message | Queue a message for an agent | fire <agent | Stop and remove an agent removes from YAML | status | Show scheduler, watchdog, and resource state | skill add <agent <source | Install skills from GitHub source owner/repo , legacy flow | skill list <agent | List installed skills | skill remove <agent <name | Remove a legacy GitHub-source skill | agent env set <agent <KEY <VALUE | Set env var in office.yaml | agent env unset <agent <KEY | Remove env var from office.yaml | agent secret-ref set <agent <KEY <ENV | Set secret ref in office.yaml | agent secret-ref unset <agent <KEY | Remove secret ref from office.yaml | agent config show <agent | Show agent config secrets redacted | agent prompt show <agent | Show effective prompt version/hash | agent prompt set <agent <text | Set custom prompt prompt inline only | agent prompt append <agent <text | Append to custom prompt prompt inline only | agent prompt clear <agent | Remove prompt config both inline and file ref | agent permission show <agent | Show agent permissions office cron, tools | agent permission set <agent office cron <bool | Set office cron permission true/false | agent permission set <agent tools allow|deny <t | Set tools allow/deny list comma-separated | agent permission clear <agent office cron | Clear office cron permission | agent permission clear <agent tools | Clear tools permissions | agent hierarchy show <agent | Show agent's manager, peers, and direct reports | org chart | Display full org tree user at root | office reload --force | Re-apply office.yaml force kills changed agents | office validate | Dry-run: parse + validate YAML without spawning | office path | Print path to office.yaml | cron list | List all cron jobs | cron status agent | Detailed cron job status | cron add <agent <job "<sched " <msg --apply | Add a cron job | cron remove <agent <job --apply | Remove a cron job | cron trigger <agent <job | Fire a cron job immediately | cron enable <agent <job --apply | Re-enable a paused job | cron disable <agent <job --apply | Pause a cron job | cron add office <job "<sched " <msg --targets a,b | Add an office-level cron job applies immediately | cron remove office <job | Remove an office-level cron job applies immediately | cron trigger office <job | Fire an office cron job immediately | task list --assignee X --status S | List tasks with optional filters | task board | Show Kanban board view | task get <id | Show task details | prompt report <agent | Show prompt composition block sizes, tool count, mode | cost status | Session token and cost totals resets on restart | cost today --agent <name | Persistent token and cost totals for today | cost report --days <n --agent <name | Historical usage over last N days | oauth login <provider --office <id | Interactive OAuth login for a provider | oauth logout <provider --office <id | Remove OAuth credentials for a provider | oauth list --office <id | List all providers and credential status | hire <name --model <provider:id Model default: anthropic:claude-sonnet-4-20250514 --priority <0-4 0=IDLE, 1=LOW, 2=NORMAL, 3=HIGH, 4=CRITICAL --thinking <level off, minimal, low, medium, high, xhigh --cwd <path Custom workspace dir --desc <text Agent description visible to other agents --prompt <text Custom system prompt --api-key-ref <ENV NAME Host env var for model API key override --env <KEY=VALUE Non-sensitive env var repeatable --secret-ref <KEY=ENV Secret ref mapping repeatable --ephemeral Don't persist to office.yaml The hire modal in the Web UI displays all available models dynamically, grouped by provider. Instead of a hardcoded list, you can browse: 700+ available models from 10+ providers Anthropic, OpenAI, Google, xAI, Mistral, etc. Model metadata : reasoning capability, context window, input/output costs Provider grouping : Easy navigation by provider anthropic, openai, google, etc. How it works: - Web UI calls GET /api/models endpoint - Backend fetches available models and groups them by provider - Models are displayed with metadata for easy selection - Fallback to default model if fetch fails API Endpoint: GET /api/models Auth: Session cookie required Response: { "providers": "anthropic", "openai", "google", ... , "models": { "anthropic": { "id": "claude-opus-4-6", "name": "Claude Opus 4.6", "provider": "anthropic", "reasoning": true, "contextWindow": 200000, "maxTokens": 4096, "cost": { "input": 3, "output": 15 } }, ... , "openai": ... , ... } } Example: When you click "Hire" in the UI, you'll see all models grouped like: Anthropic └─ Claude Opus 4.6 reasoning: ✓, context: 200k, cost: $3-15/MTok └─ Claude Sonnet 4 reasoning: ✗, context: 200k, cost: $3-15/MTok └─ Claude Haiku 3.5 reasoning: ✗, context: 200k, cost: $0.8-4/MTok OpenAI └─ GPT-4o reasoning: ✓, context: 128k, cost: $5-15/MTok └─ GPT-4o mini reasoning: ✗, context: 128k, cost: $0.15-0.6/MTok └─ ... pnpm dev start --office <name Office to load required --tick-interval <ms Scheduler tick interval default: 2000 --sandbox <mode Sandbox mode: none | docker default: none --no-ui Run headless without the web UI Migration note:The interactive ao REPL has been removed. All runtime commands are now available through the Web UI controls and typed REST API endpoints. Use --no-ui for headless operation; send SIGINT / SIGTERM to shut down. Runtime commands everything in the table above can be executed through two surfaces: Web UI — dedicated controls buttons, forms, modals for common operations: hire, fire, send messages, cron management, office reload, org chart. Some data tasks, cost, permissions, skills is displayed read-only. There is no free-text command prompt in the UI. REST API — typed endpoints per resource e.g. POST /api/agents , DELETE /api/agents/:name , PATCH /api/agents/:name/prompt , plus POST /api/send for agent messages. Callable via curl , scripts, or browser DevTools. See REST API Endpoints rest-api-endpoints . One-shot CLI commands office create , office validate , office migrate , oauth login/logout/list , start are run in the terminal and are not part of the runtime API. With --no-ui , the dashboard and API server are not started — runtime commands are unavailable for that process. The Web UI server exposes typed REST endpoints for all operations. All mutating endpoints require session cookie + CSRF headers Origin + X-Requested-With: XMLHttpRequest . Auth & SSE: | Method | Path | Description | |---|---|---| POST | /api/auth | Authenticate with bootstrap token, set session | GET | /api/events | SSE event stream real-time updates | GET | /api/state | Full workspace state snapshot | GET | /api/status | Scheduler and agent status overview | GET | /api/hierarchy | Org chart hierarchy data | GET | /api/manifest | UI build manifest | Agents: | Method | Path | Description | |---|---|---| POST | /api/agents | Hire a new agent | GET | /api/agents/:name | Get agent details | DELETE | /api/agents/:name | Fire an agent | POST | /api/send | Send a message to an agent | GET | /api/agents/:name/inbox | Get agent inbox queue | GET | /api/agents/:name/messages | Get agent DM history | DELETE | /api/agents/:name/messages | Clear agent DM history | GET | /api/agents/:name/files | List agent workspace files | GET | /api/agents/:name/files/content | Read a file from agent workspace | PATCH | /api/agents/:name/prompt | Set, append, or clear agent prompt | PATCH | /api/agents/:name/permissions | Update agent permissions | PATCH | /api/agents/:name/env | Set or unset agent env var | PATCH | /api/agents/:name/secret-refs | Set or unset agent secret ref | PATCH | /api/agents/:name/auth | Set or clear agent auth mode | PATCH | /api/agents/:name/manager | Set or clear agent manager | PATCH | /api/agents/:name/heartbeat | Set agent heartbeat config | DELETE | /api/agents/:name/heartbeat | Clear agent heartbeat config | GET | /api/agents/:name/peers | List peer agents with conversations | GET | /api/agents/:name/peers/:peer/messages | Read inter-agent conversation | GET | /api/agents/:name/skills | List agent installed skills | GET | /api/agents/:name/skills/search | Search skills registry | POST | /api/agents/:name/skills/install | Install a skill for an agent | DELETE | /api/agents/:name/skills/:skill | Remove an installed skill | Cron: | Method | Path | Description | |---|---|---| GET | /api/cron | List all cron jobs | POST | /api/agents/:name/cron | Add a cron job for an agent | DELETE | /api/agents/:name/cron/:job | Remove an agent cron job | PATCH | /api/agents/:name/cron/:job | Enable or disable an agent cron job | POST | /api/agents/:name/cron/:job/trigger | Trigger an agent cron job | POST | /api/cron/office | Add an office-level cron job | DELETE | /api/cron/office/:job | Remove an office-level cron job | POST | /api/cron/office/:job/trigger | Trigger an office-level cron job | Tasks: | Method | Path | Description | |---|---|---| GET | /api/tasks | List tasks with filters | POST | /api/tasks | Create a task | GET | /api/tasks/board | Get Kanban board data | GET | /api/tasks/:id | Get task details | PATCH | /api/tasks/:id | Update task status/data | DELETE | /api/tasks/:id | Delete a task | Channels: | Method | Path | Description | |---|---|---| POST | /api/channels | Create a channel | PATCH | /api/channels/:name | Update channel members/desc | DELETE | /api/channels/:name | Delete a channel | POST | /api/channels/:name/send | Send a message to a channel | GET | /api/channels/:name/messages | Get channel message history | DELETE | /api/channels/:name/messages | Clear channel history | Office & Scheduler: | Method | Path | Description | |---|---|---| POST | /api/office/apply | Apply office.yaml changes | GET | /api/office/validate | Validate office.yaml | GET | /api/office/path | Get office.yaml file path | POST | /api/scheduler/start | Start the scheduler | POST | /api/scheduler/stop | Stop the scheduler | Metrics: | Method | Path | Description | |---|---|---| GET | /api/cost | Cost and token usage data | OAuth: | Method | Path | Description | |---|---|---| GET | /api/oauth/providers | List all providers with authentication status | GET | /api/oauth/status/:id | Check credential status for a provider | DELETE | /api/oauth/:id | Remove stored credentials for a provider | Agents communicate through explicit tool calls. Agent text output is internal thinking — not visible to the user. All outward communication uses egress tools message user , post channel , messaging tools message agent , list agents , read agent file , authenticated fetch , cron tools cron add , cron remove , cron list , task tools task create , task update , task list , task get , task delete , and skill tools read skill , skill search , skill install , skill remove , skill create . Tool schemas are defined once in src/agent/tools/contracts.ts . Both in-process and sandboxed agents expose the full tool set. The task system automatically notifies the task creator when a task's status changes. When an agent calls task update to transition a task, TaskService sends a system message from task to the creator with the new status, result summary, and task reference. This eliminates "silent completion" without relying on agents to remember to send message agent manually. Automatic notifications are sent for these transitions: | Status | Notification | |---|---| in progress | Task Started — creator knows work has begun | review | Task In Review — creator knows review is pending | done | Task Completed — creator receives result summary | Notifications are skipped when the creator is a system address user , cron , etc. or when the creator and assignee are the same agent. Agent-to-agent requests without the task system still require the agent to message agent the requester with results. The base prompt base-v1.md instructs agents accordingly. Discover all agents in the workspace with their name, status, and description. Agents are instructed to call this first when given a task to find collaborators. Send a direct message to another agent's inbox. Messages are delivered on the next scheduler tick as a new prompt prefixed with Message from sender and a footer To reply, call message agent with to="sender" . Channel context: Messages delivered through public channels include channel context: Posted in channel. Other members: agent1, agent2 . This lets agents know they're in a shared conversation and who else can see the message. Channel replies use To reply in channel, post in the channel instead of the direct message agent footer. Optional parameters: | Parameter | Type | Default | Description | |---|---|---|---| originTaskId | string | — | Related task ID for correlation tracking | Returns delivery confirmation: { queued: true } on success, or { queued: false, reason: "..." } on failure e.g. rate limited . copywriter calls message agent: to: "designer" message: "Here's the landing page copy: ..." - Message lands in designer's inbox - Next tick delivers it as: Message from copywriter \nHere's the landing page copy: ...\n\n To reply, call message agent with to="copywriter" - Designer starts working Send a message to the human user. This is the only way an agent communicates with the user — agent text output is internal thinking and not visible. DMs are persisted via the egress service to both SQLite dm messages table and JSONL user-dm.jsonl , with idempotency via deterministic egressId SHA-256 from idempotencyKey . php agent calls message user: message: "The login page is ready for review." - DM persisted to SQLite + JSONL - state changed SSE broadcast triggers UI refresh - Real-time: tool execution end SSE event invalidates React Query cache for immediate display Idempotency: When called with the same idempotencyKey derived from the tool call's internal request ID , duplicate writes are prevented. SQLite INSERT OR IGNORE gates the JSONL write, ensuring exactly-once persistence even under retries. Validation: Empty messages and messages exceeding 64 KB are rejected. Post a message to a named channel. All channel members see the message in their channel-<name .jsonl session files. Bus notifications are sent to other members not self . Optional mentions array targets bus delivery to specific members only. agent calls post channel: channel: "general" message: "The API endpoint is deployed." mentions: "reviewer" - JSONL written to all members' sessions/channel-general.jsonl - Bus notification sent to reviewer only not self Rate limiting: 5 messages per 30-second window per agent per channel. user posts bypass the rate limit. Hop count: Messages carry a hopCount field incremented on each delivery. Posts are rejected when hopCount = 5 to prevent infinite loops. Role assignment: Posts from user get role: "user" , all others get role: "assistant" . Read files directly from another agent's workspace without needing to ask them. Path traversal is blocked for security. php reviewer calls read agent file: agent: "designer" path: "index.html" - Returns contents of ~/.agent-office/offices/<id /agents/designer/workspace/index.html In Docker sandbox mode, this tool is proxied through the Host API. The agent sends an HTTP request to the host, which reads the file on disk and returns the content. The sandboxed agent never has direct filesystem access to other agents' workspaces. Make HTTP requests to external APIs using pre-configured secrets. The secret is injected server-side and never exposed to the agent process — the agent only knows the secret name , not its value. agent calls authenticated fetch: url: "https://api.github.com/user/repos" secretName: "GITHUB TOKEN" method: "GET" - Host resolves GITHUB TOKEN to the actual value from process.env - Host injects Authorization: Bearer ghp ... header - Host makes the outbound HTTPS request - Host redacts secret value from response body - Agent receives: HTTP 200 OK\n\n {"id":1,"name":"my-repo",...} - Configuration — secrets are declared in office.yaml using ${VAR} refs: agents: my-agent: model: anthropic:claude-sonnet-4-20250514 secrets: GITHUB TOKEN: ${MY GH TOKEN} SLACK TOKEN: ${MY SLACK TOKEN} disclose secrets: true agent sees names, never values - Resolution — at spawn time, ${MY GH TOKEN} is resolved from process.env . Missing refs fail fast with a clear error. The resolved values are stored in memory on the host, never written to disk or Docker env vars. - Tool injection — the authenticated fetch tool is automatically added to agents that have at least one secret configured. No secrets = no tool. - Execution — when the agent calls the tool: In-process: the host tool resolves the secret, validates the request SSRF, HTTPS, headers , makes the fetch, and redacts the secret from the response. Docker sandbox: the proxy tool forwards the request to POST /api/authenticated-fetch on the Host API. The host resolves the secret, makes the outbound request, redacts the response, and returns it. The secret never enters the container. - Response redaction — before the response reaches the agent, the secret value is scrubbed from both the response body and headers. This prevents reflection attacks where an upstream endpoint echoes back the Authorization header. | Protection | Detail | |---|---| | HTTPS required | Only https:// URLs allowed localhost exempt in dev | | SSRF literal | Blocks private IPs: 10.x , 172.16-31.x , 192.168.x , 127.x , 169.254.x , 0.0.0.0 | | SSRF DNS | Resolves hostnames via dns.resolve4 / resolve6 , checks all IPs — catches evil.com → 127.0.0.1 | | SSRF IPv6 | Blocks ::1 , fc00::/7 , fe80::/10 , IPv4-mapped forms ::ffff:7f00:1 , ::ffff:127.0.0.1 | | Auth header injection | Auth header set after user headers — cannot be overridden by the agent | | Blocked headers | Host , Content-Length , Transfer-Encoding , Connection , Cookie are silently stripped | | Header name allowlist | Only Authorization , X-API-Key , Api-Key allowed as auth header names | | Reserved secrets | MODEL API KEY cannot be used with authenticated fetch prevents exfiltration | | Size limits | Request body: 1 MB, Response body: 5 MB | | Timeout | 30-second timeout on outbound requests | | Response redaction | Secret value scrubbed from response body and headers before agent sees it | | Agent isolation | Each agent can only access its own secrets — agent A cannot use agent B's tokens | Secrets are only usable through two host-side paths: Model auth — MODEL API KEY is consumed by the agent runtime's getApiKey callback to authenticate with model providers Anthropic, OpenAI, etc. HTTP calls — tool secrets GITHUB TOKEN , etc. are consumed via authenticated fetch , where the host injects the secret into outbound requests In both cases, the raw secret value is never exposed to agent code — it's not in process.env , not on disk, and not in Docker env vars. The agent only knows the secret name . This means if a project inside the agent workspace needs a raw key e.g. an SDK that reads process.env.X API KEY , secrets won't work for that. Use env instead: secrets | env | | |---|---|---| | Agent can read value | No | Yes visible in process.env / bash | | Usable by SDKs/CLIs | No — only via authenticated fetch | Yes — available as env var | | Appears in Docker env | No | Yes --env | | Redacted from logs | Yes response + event redaction | No | Requires ${VAR} format | Yes | Yes supports ${VAR} and literals | Rule of thumb: use secrets when the agent only needs to make authenticated HTTP calls API tokens, webhooks . Use env when workspace code needs the raw value SDK clients, CLI tools, build scripts — but accept that the agent can read it. The auth parameter controls how the secret is injected into the request: | Mode | Header value | Example | |---|---|---| bearer default | Bearer <secret | Authorization: Bearer ghp abc123 | token | token <secret | Authorization: token ghp abc123 | raw | <secret | X-API-Key: ghp abc123 | Custom auth mode example: agent calls authenticated fetch: url: "https://api.service.com/data" secretName: "SERVICE KEY" auth: { mode: "raw", headerName: "X-API-Key" } - Header injected: X-API-Key: <resolved secret value Add or update a cron job. Agent scope default manages the calling agent's own jobs. Office scope requires office cron permission. agent calls cron add: name: "daily-check" schedule: "0 9 " tasks: - title: "Run daily health check" assignee: "self" - Cron job "daily-check" saved and activated At 09:00 AM . Remove a cron job by name. Scope defaults to agent. php agent calls cron remove: name: "daily-check" - Cron job "daily-check" removed. List active cron jobs. Shows all office-level jobs plus only the calling agent's own agent-scope jobs. php agent calls cron list: scope: "all" - agent daily-check 0 9 At 09:00 AM next: 2025-01-15T09:00:00.000Z tasks: 1 office standup 0 9 1-5 ... next: 2025-01-13T09:00:00.000Z tasks: 2 Load full skill content on demand enabled by default; set on demand skills: false for eager mode . When on-demand mode is active, the agent's system prompt contains only skill summaries name + description . The agent calls read skill to fetch the full markdown content when needed. php agent calls read skill: name: "web-skills" - Returns full SKILL.md content for the skill - Errors with list of available skill names if not found Search the skills.sh registry for installable packages. php agent calls skill search: query: "web scraping" limit: 5 - Returns matching packages in owner/repo@skill-name format Install a skills.sh package into the agent's skills directory. php agent calls skill install: package: "owner/repo@skill-name" - Skill installed to agents/<agent /skills/<skill-name Remove a project-installed skill by name. Legacy GitHub-sourced skills must be removed via the CLI skill remove command. php agent calls skill remove: name: "skill-name" - Skill removed from agents/<agent /skills/ Create a new custom skill scaffold in the agent's skills directory. agent calls skill create: name: "my-skill" description: "Short trigger description" instructions: "Step-by-step workflow" when to use: "When the user asks for X" - Skill scaffold created at agents/<agent /skills/my-skill/ Create a task with title, description, and assignee. Optional dependsOn array specifies task IDs that must complete first. agent calls task create: title: "Implement login page" description: "Build login form with email/password and validation" assignee: "coder" dependsOn: "T-abc123" - Created T-def456 status: waiting — waiting on T-abc123 Tasks with unmet dependencies start as waiting . Tasks with no dependencies start as todo . Update task status, reassign, or record a result. Status transitions are validated see Task Lifecycle task-lifecycle . agent calls task update: id: "T-def456" status: "done" result: "Implemented login with validation" - Task updated. Dependent tasks auto-transition to todo. List tasks with optional filters by assignee, status, priority, or creator. php agent calls task list: assignee: "coder" status: "in progress" - Returns in progress tasks assigned to coder php agent calls task list: createdBy: " cron " - Returns all tasks created by cron jobs Get full task details by ID. php agent calls task get: id: "T-def456" - Returns: title, description, status, assignee, dependsOn, timestamps, result Delete a task permanently by ID. Cleans up dependency references — any task that depended on the deleted task has that dependency removed and may auto-unblock. php agent calls task delete: id: "T-def456" - Task T-def456 deleted. Dependent tasks auto-unblocked. src/agent/tools/ contracts.ts Single source of truth name, label, description, parameters fetch-helpers.ts Shared SSRF protection, URL validation, auth header builder message-user.ts message user — host implementation egress-impl.messageUser post-channel.ts post channel — host implementation egress-impl.postChannel message-agent.ts Host implementation bus.send list-agents.ts Host implementation direct listFn call read-agent-file.ts Host implementation direct fs access authenticated-fetch.ts Host implementation outbound fetch with secret injection task-create.ts task create — host implementation task-update.ts task update — host implementation task-list.ts task list — host implementation task-get.ts task get — host implementation task-delete.ts task delete — host implementation task-impl.ts Shared task tool logic read-skill.ts read skill — host implementation skill-search.ts skill search — host implementation skill-install.ts skill install — host implementation skill-remove.ts skill remove — host implementation skill-create.ts skill create — host implementation skill-impl.ts Shared skill tool logic cron-add.ts cron add — host implementation cron-remove.ts cron remove — host implementation cron-list.ts cron list — host implementation cron-impl.ts Shared cron tool logic policy.ts Tool policy allow/deny filtering proxy/ message-user.ts message user — proxy implementation HTTP POST /api/message-user post-channel.ts post channel — proxy implementation HTTP POST /api/post-channel message-agent.ts Sandbox implementation HTTP POST /api/message-agent list-agents.ts Sandbox implementation HTTP GET /api/agents read-agent-file.ts Sandbox implementation HTTP GET /api/agent-file authenticated-fetch.ts Sandbox implementation HTTP POST /api/authenticated-fetch task-create.ts task create — proxy implementation HTTP task-update.ts task update — proxy implementation HTTP task-list.ts task list — proxy implementation HTTP task-get.ts task get — proxy implementation HTTP task-delete.ts task delete — proxy implementation HTTP read-skill.ts read skill — proxy implementation HTTP skill-search.ts skill search — proxy implementation HTTP skill-install.ts skill install — proxy implementation HTTP skill-remove.ts skill remove — proxy implementation HTTP skill-create.ts skill create — proxy implementation HTTP cron-add.ts cron add — proxy implementation HTTP cron-remove.ts cron remove — proxy implementation HTTP cron-list.ts cron list — proxy implementation HTTP index.ts Barrel export + HostFetch type In-process agents use the host implementations directly. Sandboxed agents use the proxy implementations, which forward requests to the Host API over HTTP. Both share the same tool contracts and validation helpers to prevent drift. Every agent receives a layered system prompt composed from nine ordered layers: Base prompt src/agent/prompts/base-v1.md — always included, never overridden. Covers:- Communication model: agent text = internal thinking not visible to user ; message user = agent→user; post channel = agent→channel; message agent = agent→agent - Agent-to-agent messaging tools, messaging protocol, reply-loop avoidance, workflow rules, reporting - Execution protocol Plan → Act → Verify → Report - Workspace discipline and persistence discipline - No invented details — do not fabricate external systems, links, IDs, or integrations; ask or state unknown - Operating context awareness — treat the office as your environment; do not assume facts not in prompt context or tool output - Quality bar verify before claiming done, report assumptions - Safety constitution no independent goals, no self-modification, no replication, no exfiltration, safety over completion, human oversight first - Instruction precedence system rules office config custom instructions file injections - Communication model: agent text = internal thinking not visible to user ; Office context — office name and description e.g. "You work at Acme Corp. We build AI-powered widgets" . Only present when an office has a display name. Hierarchy — manager, peers, and direct reports derived from reports to fields. Only present when hierarchy data exists. See Hierarchy hierarchy . Runtime context — available env var names, secret names when disclose secrets: true , active cron job summaries. Lists are sorted for deterministic hashing. Identity — agent name, description, workspace path. Custom instructions — the prompt inline content from office.yaml , appended under a Custom Instructions header. Skills — summaries only by default on-demand via read skill , or full content when on demand skills: false . See Skills skills . Prompt source: use prompt inline to provide custom instructions as inline text. The legacy prompt field is no longer supported — use prompt inline instead. With prompt mode: minimal , only base, identity, and custom layers are included office, hierarchy, runtime, and skills are skipped . Each prompt is versioned v1 and hashed SHA-256, first 12 hex chars for traceability. The hash is logged on agent spawn. An .effective-prompt.md snapshot is written to the agent directory on every spawn/reload for debugging. Custom instructions are append-only — they add your content after the base prompt. All agents always receive messaging rules, tool guidance, and safety instructions regardless of custom prompt content. Note: agent prompt show <agent displays the prompt text but excludes runtime-loaded skills. Use prompt report <agent for the authoritative composed-block view with accurate character counts. The scheduler runs a setInterval tick loop default 2s . Each tick: - Sorts agents by priority CRITICAL=4 first, IDLE=0 last - Skips agents currently running status === "running" - Drains each agent's inbox, delivers the highest-priority message - Dispatches non-blocking — all agents run concurrently via async I/O - Re-queues remaining messages for the next tick --tick-interval <ms Configure via CLI flag default: 2000 | Level | Value | Use case | |---|---|---| IDLE | 0 | Background tasks, monitoring | LOW | 1 | Review, optimization | NORMAL | 2 | Standard work default | HIGH | 3 | Primary agents, user-facing | CRITICAL | 4 | Urgent, time-sensitive | Higher-priority agents are always served first. One message per tick per agent prevents starvation. Each office gets an isolated directory, and each agent within it gets its own workspace: ~/.agent-office/ offices/ acme/ office.yaml office + agent definitions .lock per-office config lock cron/ state.json cron job state tasks/ tasks.json task store logs/ cron-audit.jsonl agent cron tool audit trail task-audit.jsonl task mutation audit trail usage-cost.jsonl per-agent token usage + cost records agents/ designer/ workspace/ agent's cwd — all file tools scoped here memory/ MEMORY.md agent memory private, writable logs/ daily activity logs YYYY-MM-DD.md instructions/ user instruction files SOUL.md, CONTEXT.md, IDENTITY.md sessions/ JSONL session history system-managed user-dm.jsonl user↔agent DMs agent-reviewer.jsonl inter-agent conversations channel-general.jsonl channel conversations skills/ installed skill directories .sources.json skill folder → GitHub source mapping .effective-prompt.md generated snapshot do not edit reviewer/ workspace/ sessions/ skills/ defi-lab/ office.yaml agents/ ... All file tools read, write, edit, bash are scoped to the agent's workspace directory. Agents can read each other's files via read agent file but cannot write to them. In Docker sandbox mode, the workspace directory is volume-mounted into the container at /workspace . File changes made inside the container persist on the host. Markdown files loaded from each agent's skills/ directory and injected into the system prompt. Skills work in both in-process and Docker sandbox modes. There are two skill models: - GitHub source legacy + office.yaml sync : skill add <agent <owner/repo skill remove <agent <name - skills.sh package project-local install : skill search / skill install tools- Web UI Skills Manager install field owner/repo@skill-name GitHub source model can be declared in office.yaml : office.yaml — skills auto-install on startup agents: designer: skills: - nichochar/web-skills API command strings — GitHub source model updates office.yaml skill add designer nichochar/web-skills skill list designer skill remove designer web-tools A .sources.json file in each agent's skills directory maps installed skill folders back to their GitHub source, so skill remove can clean up office.yaml entries when the last skill from a source is removed. Registry installs track package mapping in .registry-map.json . skill remove tool is project-skill only. If a skill is legacy GitHub-sourced, remove it through CLI skill remove <agent <name . On-demand loading default : Skill summaries name + description are included in the prompt and agents call read skill read skill to fetch full content when needed. This reduces prompt size for agents with many or large skills. Set on demand skills: false to inject full skill content into the system prompt eager mode .Periodic heartbeat checks default: every 10s . If an agent's last heartbeat exceeds the stuck threshold default: 120s , it aborts and re-initializes with a fresh Pi instance. Every agent event resets the heartbeat timer. For Docker-sandboxed agents, heartbeats are received via POST /api/heartbeat from the container every 5s and fed into the watchdog through the same monitoring path. Watchdog behavior is configurable via WorkspaceConfig.watchdog all fields optional : | Parameter | Default | Description | |---|---|---| checkIntervalMs | 10000 | How often the watchdog checks heartbeats | stuckThresholdMs | 120000 | Time without heartbeat before declaring agent stuck | maxRestarts | 5 | Max restarts before marking agent as dead | healthyResetMs | 600000 | Time healthy before resetting restart counter | Inbox queues and DM records are persisted to SQLite so they survive process restarts. Requires Node.js 22+ node:sqlite . DM conversations are dual-written to both SQLite dm messages table and JSONL session files — SQLite is the primary source for UI DM display, while JSONL enables agent self-service lookup via read file / grep . Inter-agent and channel messages are JSONL-only see Session History session-history . | What | DB location | Behavior | |---|---|---| | Inbox queue | <officeDir /messages/messages.sqlite | Pending messages restored on agent register; popped messages deleted; fire <agent purges all. | | DM records | Same DB file | Written by egress service with deterministic egress id for idempotency. SQLite INSERT OR IGNORE gates JSONL writes. | The database is created automatically on first start . WAL mode, busy timeout=5000 , and synchronous=NORMAL are set for safe concurrent reads and crash resilience. If node:sqlite is unavailable, startup fails with a clear error message. The MessageBus supports sendWithOutcome which returns { queued: boolean; reason?: string } instead of void. Messages carry envelope fields correlationId , originTaskId for tracking. Conversation history is stored as JSONL files in each agent's sessions/ directory system-managed, agents must not write to it . Three session types are supported: | File name | Scope | |---|---| user-dm.jsonl | User-to-agent DMs | agent-<peer .jsonl | Inter-agent conversations | channel-<name .jsonl | Channel conversations | Each line is a JSON object: {"ts":"ISO8601","role":"user|assistant","from":"sender","text":"content","egressId":"..."} . The egressId field present on egress-written records enables idempotent deduplication. Dual write inter-agent : Inter-agent messages are written to both the sender's and receiver's session directories, so each agent has a complete local copy of the conversation. Dual write DMs : User-agent DM conversations are written to both SQLite dm messages table and JSONL user-dm.jsonl by the egress service message user tool . Each record carries a deterministic egress id SHA-256 from idempotencyKey for deduplication — SQLite INSERT OR IGNORE prevents duplicates and gates the JSONL write. SQLite serves as the primary source for UI DM display GET /api/agents/:name/messages . JSONL enables agents to search and read their DM history via read file / grep . Rotation: Session files are rotated at 500 lines, keeping the last 400 lines to prevent unbounded growth. Agent access: Agents use their native read file , grep , and ls tools to search and read session history from their sessions/ directory. There are no dedicated session tools — the base prompt instructs agents about the directory layout. Write guard: The sessions/ directory is system-managed. Agents are instructed not to write to it. Channels are defined in office.yaml under office.channels : office: name: my-team channels: general: members: pm, coder, reviewer description: Main discussion channel design: members: pm, designer If no general channel is defined, a fallback is created with all agents as members. Channel membership is refreshed on office reload . POST /api/channels/:name/send — broadcast or mention-targeted channel send. Channel management API all require session cookie + CSRF headers : POST /api/channels — create a new channel. Body: { name, members: string , description?: string } . Returns 201 on success. Validates name not reserved, matches a-zA-Z0-9 - + , members must be known agents, non-empty, no duplicates . PATCH /api/channels/:name — update an existing channel. Body: { members?: string , description?: string } . Merges with existing config. Returns 200 . DELETE /api/channels/:name — delete a channel. Returns 200 . Deleting general is rejected with 400 { error: "cannot delete default channel" } . If the deleted channel is currently selected in the UI, the client falls back to the default conversation channel or the Tasks system view. All channel mutations persist to office.yaml atomically lock + temp file + rename and immediately refresh the in-memory channel map with a state changed SSE broadcast. No office restart is required. Channel ID vs label: The API uses raw channel names e.g., general . The UI displays general as a label but sends the raw name in API calls. The server normalizes -prefixed names for backward compatibility e.g., %23general → general . Inspect the composed system prompt for any running agent: prompt report bot === Prompt Report: bot === Mode: full Version: v1 Base prompt 2,847 chars Office block 156 chars Runtime block 312 chars Identity block 89 chars Custom prompt 1,204 chars Skills 3,421 chars ────────────────────────────────── Total 8,029 chars Tools: 15 registered Skills: 2 loaded web-skills, code-review Use this to check prompt size after truncation and confirm tool/skill counts. A full .effective-prompt.md snapshot is also generated per agent on every spawn/reload at <officeDir /agents/<name /.effective-prompt.md . Add .effective-prompt.md to .gitignore — it is generated, not source. Agent-office tracks per-agent token usage and cost from model responses. cost status === Cost Status session === Total tokens: 12,450 Cost: $0.0832 bot: 8,200 tokens $0.0614 helper: 4,250 tokens $0.0218 cost today cost today --agent bot cost report --days 7 cost report --days 30 --agent bot — in-memory session totals. Resets on gateway restart. cost status — persistent totals for the current day. cost today — historical totals over the last N calendar days. cost report --days <n - All commands accept --agent <name to filter to a single agent. - Usage records are stored at ~/.agent-office/offices/<id /logs/usage-cost.jsonl append-only JSONL . The start command starts a web UI dashboard automatically disable with --no-ui : ui Dashboard: http://127.0.0.1:3847/ token=<bootstrap Open the printed URL to authenticate with the one-time bootstrap token. The dashboard API uses a session-cookie flow with CSRF protection: - Open the token=<bootstrap URL — the UI extracts the token from the URL fragment. POST /api/auth with { "token": "<bootstrap " } plus Origin and X-Requested-With: XMLHttpRequest headers.- Server validates the one-time token, invalidates it, and returns a Set-Cookie: ao session=<id ; HttpOnly; SameSite=Strict header. - All subsequent API calls use the session cookie. Mutating endpoints require Origin must match http://127.0.0.1:<port and X-Requested-With: XMLHttpRequest headers for CSRF protection. This is separate from the sandbox Host API auth bearer token per agent, described in Host API Endpoints host-api-endpoints . Slack-style layout — sidebar with channels general , direct messages per agent, Cron management, Heartbeat management, Files browser, and a Tasks Kanban view Kanban board — task board with columns waiting → todo → in progress → done , per-agent filter, and task deletion from detail view Agent DMs — conversation threads per agent with message input, tabbed view Messages, Internal, Files, Prompt, Skills, Configure , and clear history via three-dot menu Internal conversations — read-only viewer for agent-to-agent messages with peer selector dropdown and disabled message input Agent detail — skills tab for viewing installed skills per agent Agent fire — comprehensive cleanup with impact modal showing affected tasks, cron jobs, and channel memberships before confirmation Dynamic model selection — Hire modal displays all 700+ available models from pi-ai, grouped by provider with metadata reasoning capability, context window, costs . Auto-updates when pi-ai upgrades. OAuth auth selector — per-agent Config tab shows auth mode toggle API Key / OAuth when OAuth credentials exist for the agent's model provider, plus authenticated provider badges with one-click credential removal Heartbeat management — top-level page /heartbeat with card-based dashboard showing configured heartbeats, next run times, active hours, and add/edit/remove via modal Cron management — top-level sidebar item with dedicated cron view, human-friendly schedule builder hourly/daily/weekly/custom , report channel selector, loading states, and delete confirmation Files browser — centralized page /files to browse all agents' workspace files Debug logs — live event capture panel with source/kind/agent filters, preset views All, Errors, Tools, Messages, Task/Cron , group-by-agent mode, and JSONL export Org chart — dedicated page /org-chart with interactive hierarchy visualization and agent profile drawer Cost dashboard — dedicated page /cost with per-agent token usage and cost breakdown Office settings — dedicated page /settings with channel management create, edit members/description, delete , read-only scheduler status, config reload/validate URL-based navigation — React Router v7 with bookmarkable URLs, browser back/forward, and deep linking to any view Real-time updates — SSE event stream with unread badges and queue depth indicators | Env var | Default | Description | |---|---|---| UI PORT | 3847 | Dashboard HTTP port | The server binds to 127.0.0.1 only never exposed to the network . Auth uses HttpOnly session cookies with CSRF protection. pnpm ui:build Type-check + Vite production build pnpm ui:lint ESLint + single-component-per-file check pnpm ui:check TypeScript type check only The frontend lives in ui/ Vite + React 19 + Mantine 7 + React Router v7 . During dev, pnpm -C ui dev starts the Vite dev server with API proxy to the backend. Three agents collaborate on a landing page, all running in-process: hire designer --model openai:gpt-5.2-codex --desc "Frontend designer — builds HTML/CSS" hire copywriter --model openai:gpt-5.2-codex --desc "Copywriter — writes marketing copy" hire reviewer --model openai:gpt-5.2-codex --desc "Code reviewer — reviews quality" What happens: copywriter writes copy, uses list agents to discover designer, sends via message agent designer receives the message, builds index.html with the copy- You send: @reviewer Review designer's work and send feedback reviewer calls list agents , uses read agent file to read designer's HTML, sends feedback via message agent designer applies fixes, copywriter reports completion to the user All coordination is autonomous after the initial prompt. Isolated agents working on a Node.js API project: Start with Docker isolation pnpm dev start --office my-team --sandbox docker hire backend --model anthropic:claude-sonnet-4-20250514 --desc "Backend developer — writes Node.js APIs" → Container started with --cap-drop=ALL, --user 1000:1000 hire tester --model anthropic:claude-sonnet-4-20250514 --desc "QA engineer — writes and runs tests" send backend "Build a REST API for a todo app with CRUD endpoints using Express" What happens behind the scenes: DockerProvider builds the pi-sandbox image once, cached - Two containers start on ports 13100 and 13101 backend agent runs inside its container:- Uses bash , write file , edit file tools locally in /workspace - Creates server.js , package.json , route files - Files appear at ~/.agent-office/offices/<id /agents/backend/workspace/ on host - Uses - You send: @tester Review backend's code and write tests tester calls list agents proxy - Host API - returns agent list tester calls read agent file proxy - Host API - reads backend's files from host disk tester writes test files in its own /workspace tester sends feedback to backend via message agent proxy - Host API - message bus Each agent is fully isolated — a misbehaving agent cannot crash the host, read secrets, or access another agent's filesystem directly. An agent uses pre-configured secrets to interact with the GitHub API — the secret never touches the agent process: js Set the host env var with your GitHub PAT export MY GH TOKEN="ghp ..." Option A: Via Web UI/API hire github-bot --model anthropic:claude-sonnet-4-20250514 \ --desc "GitHub integration bot" \ --secret-ref GITHUB TOKEN=MY GH TOKEN send github-bot "List my GitHub repos using authenticated fetch with secretName GITHUB TOKEN" Option B: Via office.yaml ~/.agent-office/offices/my-team/office.yaml office: name: My Team agents: github-bot: model: anthropic:claude-sonnet-4-20250514 description: "GitHub integration bot" secrets: GITHUB TOKEN: ${MY GH TOKEN} disclose secrets: true office reload send github-bot "List my GitHub repos" What happens: Spawn: ${MY GH TOKEN} is resolved from process.env fails fast if not set Tool injection: authenticated fetch is automatically added because the agent has secrets Agent calls tool: authenticated fetch url: "https://api.github.com/user/repos", secretName: "GITHUB TOKEN" Host resolves secret , injects Authorization: Bearer ghp ... , makes the HTTPS request Response redacted — ghp ... value is scrubbed from the response body before the agent sees it Agent processes the clean JSON response and reports results to the user The agent never sees ghp ... — only the name GITHUB TOKEN . In Docker sandbox mode, the secret never enters the container at all. Three agents collaborate with Kanban-style task management: send task-manager "Build a login page with email/password auth" What happens: task-manager creates two tasks with dependencies: T-xxx : "Implement login page" → assigned to coder status: todo T-yyy : "Review login page" → assigned to reviewer , dependsOn: T-xxx status: waiting coder receives New Task notification, implements the feature, marks task done TaskService detects dependency resolved → moves review task to todo reviewer receives Task Ready notification, reviews code, marks task done - Track progress: task board via API, or Tasks Kanban view in the Web UI See examples/feature-team/ /baturyilmaz/agent-office/blob/main/examples/feature-team for the full office.yaml . src/ index.ts CLI entry + startup workspace.ts Central facade wires scheduler, bus, watchdog, sandbox types.ts Shared types Priority, AgentConfig, OfficeYaml, OfficeContext, etc. constants.ts Shared constants, office path helpers, officeId validation config/ office-yaml.ts Office loader, validator, mutations, env/secret merge office-yaml-mutations.ts Office YAML mutation helpers add/remove agents, cron, etc. yaml-utils.ts Shared validation, cron extraction, atomic writes yaml-validation.ts YAML schema validation agent names, office IDs, cron fields hierarchy.ts Agent hierarchy helpers manager lookup, org traversal env-substitution.ts ${VAR} env ref resolution with validation lock.ts Two-layer lock in-process queue + cross-process file lock security/ redact.ts Secret redaction text + deep object walker skills/ fetch.ts Skill fetching, source map, reverse lookup registry.ts Skills registry install/remove/search/list agent/ handle.ts Agent lifecycle init, prompt, steer, abort, destroy handle-init.ts initInProcessAgent / initSandboxAgent factory functions prompt.ts Convenience wrapper over prompt-manager workspace-scaffold.ts Workspace directory scaffold memory/, logs/ prompts/ base-v1.md Versioned base prompt messaging, tools, safety base-v1.ts TS companion reads .md, exports PROMPT VERSION prompt-manager.ts Layered composition + deterministic hashing prompt-loader.ts XOR prompt resolution inline vs file effective-prompt.ts .effective-prompt.md snapshot writer truncate.ts Prompt truncation head/tail split, per-block limits skills/ on-demand.ts Skill summary extraction for on-demand mode entrypoints/ sandbox-entry.ts Standalone process for Docker containers tools/ contracts.ts Shared tool metadata name, label, description, parameters fetch-helpers.ts Shared SSRF, URL validation, auth header builder index.ts Barrel re-export for host-side tools message-user.ts message user — host implementation egress-impl.messageUser post-channel.ts post channel — host implementation egress-impl.postChannel message-agent.ts message agent — host implementation bus.send list-agents.ts list agents — host implementation direct call read-agent-file.ts read agent file — host implementation local fs authenticated-fetch.ts authenticated fetch — host implementation secret injection + fetch task-create.ts task create — host implementation task-update.ts task update — host implementation task-list.ts task list — host implementation task-get.ts task get — host implementation task-delete.ts task delete — host implementation task-impl.ts Shared task tool logic policy.ts Tool policy allow/deny filtering read-skill.ts read skill — host implementation skill-create.ts skill create — host implementation skill-install.ts skill install — host implementation skill-remove.ts skill remove — host implementation skill-search.ts skill search — host implementation skill-impl.ts Shared skill tool logic cron-impl.ts Shared cron tool logic add/remove/list cron-add.ts cron add — host implementation cron-remove.ts cron remove — host implementation cron-list.ts cron list — host implementation proxy/ index.ts Barrel + HostFetch type message-user.ts message user — proxy implementation HTTP post-channel.ts post channel — proxy implementation HTTP message-agent.ts message agent — proxy implementation HTTP list-agents.ts list agents — proxy implementation HTTP read-agent-file.ts read agent file — proxy implementation HTTP authenticated-fetch.ts authenticated fetch — proxy implementation HTTP task-create.ts task create — proxy implementation HTTP task-update.ts task update — proxy implementation HTTP task-list.ts task list — proxy implementation HTTP task-get.ts task get — proxy implementation HTTP task-delete.ts task delete — proxy implementation HTTP cron-add.ts cron add — proxy implementation HTTP cron-remove.ts cron remove — proxy implementation HTTP cron-list.ts cron list — proxy implementation HTTP read-skill.ts read skill — proxy implementation HTTP skill-create.ts skill create — proxy implementation HTTP skill-install.ts skill install — proxy implementation HTTP skill-remove.ts skill remove — proxy implementation HTTP skill-search.ts skill search — proxy implementation HTTP egress/ types.ts EgressContext, EgressDeps, EgressResult, constants MAX HOPS, rate limits egress-impl.ts messageUser + postChannel — shared persist-then-notify logic sandbox/ types.ts SandboxProvider interface, SandboxMode, SandboxStartOpts host-api.ts HTTP server for sandbox-to-host communication host-api-handlers.ts Core Host API route handlers tools, prompt, secrets host-api-ext-handlers.ts Extended Host API handlers tasks, cron, skills docker-provider.ts Docker container lifecycle build, run, stop, health Dockerfile Container image definition node:22-slim, non-root package.json Sandbox-specific npm dependencies index.ts Barrel export tasks/ types.ts Task, TaskStatus, STATUS TRANSITIONS, TaskFilter task-store.ts Persistence ~/.agent-office/offices/<id /tasks/tasks.json task-service.ts Task orchestrator create, update, dependency resolution, notifications task-audit.ts Audit logger logs/task-audit.jsonl cron/ types.ts CronJobConfig, CronJobState, CronJobEntry cron-parser.ts Thin wrapper over cron-parser 5-field only cron-store.ts State persistence ~/.agent-office/cron/state.json cron-service.ts Timer orchestrator setTimeout per job, catch-up, dispatch cap cron-audit.ts Audit logger JSONL + stdout cron-audit scheduler/ scheduler.ts Tick-based priority scheduler watchdog.ts Heartbeat monitor + stuck detection heartbeat.ts Heartbeat system periodic proactive agent wake-up messages/ types.ts PersistedInbox, DmRecord interfaces message-store.ts SQLite-backed inbox + DM persistence node:sqlite, Node 22+ session-key.ts Session key helpers sessionKey, parseSessionKey sessions/ session-writer.ts JSONL append + rotation utility 500 lines max, keeps last 400 transport/ local.ts In-process priority inbox queues with SQLite persist hooks message-bus.ts Bus wrapper over transport store integration, pop, purge auth/ oauth-store.ts OAuth credential persistence load/save/path, atomic writes oauth-resolver.ts Dynamic getApiKey callback auto-refresh + sync resolver commands/ oauth-login.ts OAuth CLI: login interactive , logout, list providers office-apply.ts Apply office.yaml + reload/validate/path commands hire.ts Agent creation with YAML auto-sync roster.ts Agent status table send.ts Message queueing fire.ts Agent teardown with YAML auto-sync status.ts Scheduler/watchdog overview skill.ts Skill install/remove with YAML + source map sync agent-config.ts Per-agent env/secret-ref/prompt commands + config show cron.ts Cron CLI handlers add/remove/enable/disable/list/status/trigger task.ts Task CLI handlers list/board/get migrate.ts Two-step legacy migration copy + finalize prompt-report.ts Prompt report command block sizes, tool count cost.ts Cost status/today/report commands metrics/ usage-tracker.ts Usage/cost JSONL tracker record, read, summarize ui/ server.ts HTTP server :3847 , SSE streaming, static file serving routes.ts REST API route definitions typed endpoints + getModelsResponse types.ts UI-specific type definitions event-buffer.ts SSE event buffering and batching manifest.ts UI build manifest loader handlers/ agent-config.handler.ts Agent config prompt, permissions, env, secrets, heartbeat agent-core.handler.ts Agent CRUD hire, fire, detail agent-files.handler.ts Agent workspace file listing/reading agent-messaging.handler.ts Agent DMs, inbox, peer conversations agent-skills.handler.ts Agent skill install/remove/search analytics.handler.ts Cost metrics auth.handler.ts Session auth + CSRF channels.handler.ts Channel CRUD + messaging cron-agent.handler.ts Per-agent cron jobs cron-office.handler.ts Office-level cron jobs oauth.handler.ts OAuth provider listing + credential removal office.handler.ts Office apply/validate/path + scheduler sse.handler.ts SSE event streaming state.handler.ts Bootstrap state + status tasks.handler.ts Task CRUD + board api/ types.ts Shared API types ModelInfo, ModelCost, ModelsResponse use-models.ts React Query hook for fetching GET /api/models with 5-min stale time ui/src/ routes.tsx createBrowserRouter route definitions all app routes main.tsx App entry — RouterProvider + Mantine + QueryClient providers components/ layout/ RootLayout.tsx Top-level layout: auth, SSE, bootstrap, sidebar + Outlet app-state-context.ts AppStateContext + useAppState hook BootstrapState for pages app-actions-context.ts AppActionsContext + useAppActions hook openAgentProfile slack/ SlackSidebar.tsx Sidebar with useNavigate/useLocation URL-based active state ChannelView.tsx DM + channel conversation thread view tabbed: Messages, Internal, Files, Prompt, Skills, Configure MessageInput.tsx Chat input with mentions, supports disabled mode for read-only views ... Other shared UI components agent-detail/ PeerConversations.tsx Read-only inter-agent conversation viewer with peer selector ... Agent config/prompt/skills panels heartbeat/ HeartbeatCard.tsx Card component with avatar, interval, next run, active hours HeartbeatForm.tsx Modal form for adding/editing heartbeat config HeartbeatDetailModal.tsx Detail modal with edit/remove actions pages/ tasks/ KanbanBoard.tsx /tasks — task board with columns and per-agent filter cron/ CronChannelView.tsx /cron — cron job management with schedule builder heartbeat/ HeartbeatView.tsx /heartbeat — heartbeat management dashboard files/ AllFilesPanel.tsx /files — centralized file browser for all agents dm/ DmView.tsx /dm/:agentName — wrapper that extracts param → ChannelView channel/ ConversationView.tsx /channels/:name — wrapper that extracts param → ChannelView cost/ CostPanel.tsx /cost — per-agent token usage and cost breakdown settings/ SettingsPanel.tsx /settings — office settings and channel management debug/ OfficeDebugPanel.tsx /debug — live debug log capture panel org-chart/ OrgChartPanel.tsx /org-chart — interactive agent hierarchy visualization test/ office-yaml.test.ts Office config: officeId validation, load, validate, merge, mutations, lock agent-config.test.ts Per-agent env/secret-ref/prompt CLI commands + config show env-substitution.test.ts ${VAR} resolution, missing vars, reserved keys hierarchy.test.ts Agent hierarchy helpers, manager lookup redact.test.ts Secret redaction text, deep objects, edge cases docker-provider.test.ts Docker provider mocked execFile + fetch authenticated-fetch.test.ts authenticated fetch tool + SSRF + auth modes + redaction host-api.test.ts Host API endpoints, auth, secrets, prompt correlation host-api-cron.test.ts Host API cron endpoints: auth, isolation, parity host-api-tasks.test.ts Task proxy Host API endpoints create/update/list/get tool-contracts.test.ts Verifies host + proxy tools share contracts tool-policy.test.ts Tool policy allow/deny filtering + server-side enforcement sandbox-validation.test.ts CLI --sandbox option validation tools.test.ts Host-side tool behavior skill-tools.test.ts Skill tool behavior create, install, remove, search skills-registry.test.ts Skills registry install, remove, search, list scheduler.test.ts Tick loop, priority ordering watchdog.test.ts Heartbeat, stuck detection, restart heartbeat.test.ts Heartbeat system interval, active hours, dispatch message-bus.test.ts Inbox routing, rate limiting message-bus-persistence.test.ts SQLite persist/restore, pop, purge message-store.test.ts MessageStore CRUD, ordering, pagination local-transport.test.ts Priority queue ordering handle-skills.test.ts Skill paths for in-process + sandbox agents cron-parser.test.ts Cron expression parsing, timezone, describeCron cron-store.test.ts State persistence round-trip, atomic writes cron-service.test.ts Timer lifecycle, catch-up, dispatch cap, busy skip cron-commands.test.ts Cron CLI add/remove/enable/disable + validation cron-tools.test.ts Cron tool impl: validation, scopes, permissions, audit, limits prompt.test.ts System prompt composition prompt-manager.test.ts Prompt composition, layering, hashing, office block, determinism prompt-loader.test.ts Prompt source resolution inline, file, path safety effective-prompt.test.ts Effective prompt snapshot generation truncate.test.ts Prompt truncation head/tail split, per-block limits workspace-scaffold.test.ts Workspace scaffold memory/, logs/ directory creation office-cron.test.ts Office-level cron lifecycle, targets, broadcast, state keys task-service.test.ts Task creation, status transitions, dependencies, notifications task-store.test.ts Task persistence, filtering task-tools.test.ts Task tool behavior + audit on-demand-skills.test.ts Skill summaries, read skill tool, proxy prompt-report.test.ts Prompt report command output usage-tracker.test.ts Usage JSONL recording, reading, filtering cost-commands.test.ts Cost status/today/report formatting cli-behavior.test.ts CLI flag/option validation session-context.test.ts Session key helpers sessionKey, parseSessionKey chat-feed-routing.test.ts SSE event routing chat-relevant vs suppressed command-parser.test.ts Chat command parsing slash commands, natural language debug-capture-store.test.ts Debug capture store event buffering, filtering debug-helpers.test.ts Debug helper utilities ui-parity.test.ts UI API parity REST endpoints match command coverage ui-send-message.test.ts UI send message endpoint behavior ui-server.test.ts UI HTTP server lifecycle, routes, SSE, SSE payload contracts no-ui-option.test.ts --no-ui CLI option behavior egress-impl.test.ts Egress service: messageUser/postChannel persistence, idempotency, rate limiting use-events-invalidation.test.ts React Query cache invalidation on message user SSE events | Package | Purpose | |---|---| @mariozechner/pi-agent-core | Pi agent runtime | @mariozechner/pi-coding-agent | Coding tools read, write, edit, bash, grep, find, ls + skills | @mariozechner/pi-ai | Model registry + streaming | @sinclair/typebox | Tool parameter schemas | commander | CLI argument parsing | dotenv | Load .env into process.env | | cron-parser | Cron expression parsing next/prev fire times | | yaml | YAML parsing with comment-preserving Document API | | proper-lockfile | Cross-process file locking for per-office config safety | pnpm install Install dependencies pnpm build TypeScript type check tsc --noEmit + UI build Vite pnpm lint:check ESLint pnpm test Run test suite vitest — ~1000 tests pnpm test:watch Run tests in watch mode pnpm dev start Run in dev mode tsx Tests live in test/ one file per module, <feature .test.ts naming . Host API tests test/host-api.test.ts , test/host-api-cron.test.ts require port binding and are skipped by default. Run them when available: HOST API TESTS=1 pnpm exec vitest run test/host-api.test.ts test/host-api-cron.test.ts Requires Node 22+ and Docker for sandbox mode .