Agent OS

A local-first personal control plane for orchestrating AI coding agents — Claude Code, Codex, and whatever you wrap next.

You're not using AI anymore. You're running a team.

Agent OS turns "ask an AI to write some code" into "plan a mission, assign tasks to agents, watch them work in isolated Git worktrees, approve the risky parts, and merge what's good." One developer, multiple agents, one control plane, all running on your machine.

Prerequisites

• Node.js >= 20
• Python >= 3.11
• pnpm >= 9
• git

Windows users: Python 3.11+, Node 20+, pnpm 9+, and Git for Windows are all required. Run in PowerShell or Windows Terminal. WSL2 is supported but not required.

Installation

git clone <your-fork-url> agent-os
cd agent-os

# TypeScript side: CLI, dashboard, shared types
pnpm install
pnpm --filter @agent-os/shared build
pnpm build

# Python side: the gateway
cd packages/gateway
pip install -e ".[dev]"
cd ../..

# Make `agentos` available globally — from npm:
npm install -g @agenti-os/cli

# ...or from this checkout:
pnpm --filter @agenti-os/cli build
npm install -g apps/cli

Set your Anthropic API key if you want mission planning (the planner calls claude-sonnet-4-6 to decompose an objective into a task DAG):

export ANTHROPIC_API_KEY=sk-ant-...

Quickstart

1. Install

git clone https://github.com/your-username/agent-os
cd agent-os
pnpm install
pip install -e packages/gateway[dev]
pnpm build
pnpm build:dashboard
pnpm link --global

2. Initialize your project

cd your-project
agentos init

3. Start Agent OS

export ANTHROPIC_API_KEY=sk-ant-...   # or set in PowerShell
agentos start
# Opens browser automatically at http://localhost:47821/ui
# Streams live events to terminal

4. Register an agent

# In a new terminal (or Ctrl+C from logs first):
agentos agent add claude --role backend --cmd claude

5. Run a mission

agentos mission create "Build a users REST API"
agentos mission plan
agentos mission run
# Watch agents work in real time

When a task finishes, review it with agentos diff <task_id> and merge with agentos merge <task_id>. If an agent's credential expires mid-run, check agentos inbox — failed runs get frozen, not lost. agentos start's Ctrl+C only detaches from the log stream — the gateway keeps running in the background; stop it with agentos stop (or agentos daemon stop).

Command reference

| Command | Description | Example | |---|---|---| | agentos init | Scaffold .agentos/ in the current repo | agentos init | | agentos start | Start the gateway + dashboard, open the browser, stream live events | agentos start | | agentos stop | Stop the gateway (warns if a mission is still running) | agentos stop | | agentos daemon start\|stop\|status | Manage the gateway process directly | agentos daemon start | | agentos agent add <name> | Register a new agent | agentos agent add claude --role backend | | agentos agent remove <id> | Unregister an agent | agentos agent remove ag_01... | | agentos agents | List registered agents | agentos agents | | agentos agents health | Credential health per agent | agentos agents health | | agentos mission create <objective> | Create a mission | agentos mission create "Fix login bug" | | agentos mission plan <id> | Decompose into a task DAG | agentos mission plan ms_01... | | agentos mission run <id> | Start ready tasks | agentos mission run ms_01... --parallel | | agentos mission pause <id> | Pause a running mission — stops live agent runs, freezes their workspaces | agentos mission pause ms_01... | | agentos mission resume <id> | Resume a paused mission — relaunches tasks with their preserved work | agentos mission resume ms_01... | | agentos diff <task_id> | View an agent's changes | agentos diff tk_01... | | agentos merge <task_id> | Merge approved work | agentos merge tk_01... | | agentos rollback <task_id> | Discard a task's work | agentos rollback tk_01... | | agentos route <task_id> --to <agent_id> | Hand a task to another agent | agentos route tk_01... --to ag_02... | | agentos stop-task <task_id> | Stop a live agent run, preserving partial work | agentos stop-task tk_01... | | agentos inbox | Pending approvals, credential events, conflicts | agentos inbox | | agentos approve <id> | Approve a pending action | agentos approve ar_01... --once | | agentos deny <id> | Deny a pending action | agentos deny ar_01... | | agentos conflicts | List active conflicts | agentos conflicts | | agentos context add <file> | Add a doc to the context vault | agentos context add docs/api.md | | agentos context show <pack_id> | Inspect a handoff context pack | agentos context show cp_01... | | agentos logs [--follow] | Stream or view event history | agentos logs --follow | | agentos credentials rotate <agent_id> | Rotate a stored credential | agentos credentials rotate ag_01... |

Run agentos <command> --help for full flag documentation on any command.

Architecture

 ┌──────────┐        HTTP/SSE        ┌──────────────────┐
 │   CLI    │ ─────────────────────> │                  │
 │ (agentos)│ <───────────────────── │   FastAPI        │
 └──────────┘                        │   Gateway        │
                                      │  (127.0.0.1      │
 ┌──────────┐        HTTP/SSE        │   :47821)        │
 │Dashboard │ ─────────────────────> │                  │
 │(Next.js) │ <───────────────────── │  source of truth │
 └──────────┘                        └─────────┬────────┘
                                                │
                          ┌─────────────────────┼─────────────────────┐
                          │                     │                     │
                    ┌─────▼─────┐        ┌──────▼──────┐       ┌──────▼──────┐
                    │  SQLite   │        │  .agentos/  │       │  Adapters   │
                    │ (state,   │        │  (worktrees,│       │ (translate  │
                    │  events)  │        │  context,   │       │  gateway <->│
                    └───────────┘        │  policies)  │       │  agent CLI) │
                                          └─────────────┘       └──────┬──────┘
                                                                        │
                                                                 ┌──────▼──────┐
                                                                 │ Agent CLIs  │
                                                                 │ (claude,    │
                                                                 │  codex, …)  │
                                                                 └─────────────┘

The gateway is the only process that writes to SQLite. The CLI and dashboard are thin clients — every command goes over HTTP, every live update comes over SSE. Adapters are the only thing that knows how to actually talk to a given agent's CLI; the gateway core never branches on agent type.

Further reading

• docs/architecture.md — system design, the five core decisions, data flow, event system, security model
• docs/cli-reference.md — every command, every flag, with examples
• docs/adapters.md — how to wrap a new agent CLI