AgentOS — local-first agent operating system

A self-hosted rebuild of Danny Postma's AgentOS (video) that runs entirely on your machine and executes work through the coding-agent CLIs you already pay subscriptions for — Claude Code, Codex (ChatGPT), and Opencode — never metered API keys.

Write a spec, file it as a task or a goal, close the laptop. Agents plan, review, implement, review again, fix, and document — and ping you (macOS notification, or your phone via ntfy) only when they need a decision. See docs/RESEARCH.md for how Danny's original works and what this build changes.

Quick start

Requirements: Node 20+ and at least one runner CLI installed and logged in — Claude Code (claude), Codex (codex) or Opencode (opencode). No API keys.

npx @cjbuilds/agent-os

That starts the server and opens http://localhost:4141. To keep it around:

npm install -g @cjbuilds/agent-os
agentos                       # start + open the UI  (agentos serve = foreground, no browser)

You get a seeded system: 10 agents (spec, plan, senior-dev, review-coordinator + 3 review specialists, diagnostic, librarian, orchestrator), 10 skills, Danny's 9-step compound-engineer feature workflow and a 5-step bug-fix workflow (diagnose → plan → review → implement → verify) as templates. Everything lives in ~/.agentos/ (SQLite + files); agentos --help lists the CLI. Port taken? agentos serve --port 4242.

From source: git clone https://github.com/Cjbuilds/AgentOS && cd AgentOS && npm install && npm start.

Want to see it full, not empty?

agentos demo

Starts a playground on http://localhost:4142 filled with realistic sample data — 3 projects, ~40 interlinked tasks (chains, subtasks, scheduled, archived), 4 goals in different states (done / stuck / failed / awaiting DoD review), 25 sessions with full transcripts, an inbox with open questions, automations, triggers with fire history, files and a real git repo. It lives in ~/.agentos-demo; your real ~/.agentos is untouched. Nothing runs on its own — press Run on anything and it uses your real runner CLIs. agentos demo --reset wipes it and starts fresh.

The 60-second tour

| Concept | What it does | | --- | --- | | Tasks | Kanban (todo → doing → review → done). Assign an agent; the engine spawns a real CLI session in an isolated workspace. Approval-gated tasks can only be moved to done by you. Schedule once, at a datetime, or cron-recurring. | | Templates | Multi-step workflows with {{variables}}. Steps run strictly sequentially; each step's agent starts only when the previous step is done (gates included). | | Goals | Open-ended work. Paste a spec → the orchestrator drafts a Definition of Done → you approve → it loops: pick specialist, run session, log progress, check off criteria — until done or safety rails trip (max iterations, max minutes, stuck detection). | | Inbox | Agents reach you via agentos-msg send/ask (works inside all three CLIs). Questions can be multiple-choice; replying unblocks the waiting session. | | Sessions | Every run is ephemeral: a fresh git worktree (when the project has a repo), destroyed afterwards — the branch and its commits survive. Live event stream in the UI. | | Triggers | Webhooks (POST /hooks/:slug?secret=…) that create scoped work — the seeded bug-report hook fans a payload into the whole bug-fix chain. | | MCPs / Env Vars | MCP servers and environment variables registered once, granted per agent (and per project for env vars) — wired into each session automatically. | | Automations | Cron entries that file recurring tasks (e.g. weekly content, Monday inbox summary). | | Projects | Point at a local git repo; agents with repo_access work in worktrees of it. | | agentos.yml | Everything (agents, skills, templates, triggers, automations) as YAML: agentos push / agentos pull for stable round-trip sync, with agentos status / agentos diff to see which side moved first. See agentos.example.yml and Sync. |

Runners (subscriptions, not APIs)

Per-agent choice of executor, spawned headless in the session workspace:

• claude → claude -p … --output-format stream-json --dangerously-skip-permissions
• codex → codex exec --json --dangerously-bypass-approvals-and-sandbox
• opencode → opencode run --format json

Each CLI must be installed and logged in already. Mix freely: keep planners on Claude, put fast implementation workers on Codex/Opencode — mirroring Danny's "planners on Fable, workers on fast models" split, at subscription cost (~90% cheaper than his original $500/day API bill, per his own thread).

A real feature build

1. UI → Tasks → New Task → From template → compound-engineer; set feature and branch, pick your project.
2. Step 1 (spec) will interview you through the Inbox, then wait in Review — approve it.
3. Plan → plan review (coordinator + 3 specialists) → revise → implement (+tests) → code review → fixes → wiki update run unattended; you get pinged only for gates/questions.
4. Final step hands you the branch to review and merge.

Drive it from Claude Code

Danny's actual workflow isn't clicking around a UI — it's talking to an agent that files the work for him. Keep a claude (or codex) session open in this repo, or any repo, and tell it what you want:

"Read notes/checkout-bug.md and file it as a bug-fix workflow on the my-app project."

It runs the CLI for you:

agentos task create --title "Checkout 500s" --template bug-fix --var bug="POST /checkout 500s for guest carts" --project my-app
agentos goal create --title "Ship v2 billing" --spec-file specs/v2.md
agentos status --overview

agentos status --overview gives it (and you) a one-screen read on what's running, what's waiting on you, and what got stuck — so the chat session can queue work, then check back later. Everything is also declarative: see Sync below.

Projects are created in the UI only — the switcher's + New Project. There is no agentos project create and no create_project on the agent-facing surface: an agent may enumerate projects and bind to one, never mint one. agentos init --project <slug> binds a working directory to an existing project.

Sync: push, pull, status, diff

agentos push and agentos pull move agents, skills, template-tasks and templates between this repo and the server. Both also refresh the local mirror beside your config file:

.agentos/
  agents/          <slug>.yaml
  skills/          <slug>.md        (frontmatter + body)
  template-tasks/  <slug>.yaml
  templates/       <slug>.yaml
  config.json      the project binding — written by `agentos init`
  .sync.json       sync state: timestamps, file list, and one baseline hash per resource

On their own, push and pull are blind overwrites in either direction — a push can clobber an agent someone just edited in the UI. Two commands close that:

agentos status                  # what drifted, and which way
agentos diff agents/senior-dev  # unified diff, your file vs the server's

status is git's three-state model. For each resource it compares three contents — your local file, the server's current content, and the baseline recorded in .agentos/.sync.json at the last push/pull (the last moment both sides were provably equal) — all sha256 over the same canonical rendering:

| State | Meaning | Do | | --- | --- | --- | | in-sync | identical content | nothing | | local-ahead | you edited it here; the server has not seen it | agentos push | | server-ahead | it changed in the UI; your copy is stale | agentos pull | | conflict | both sides moved since the last sync | agentos diff first | | local-only / server-only | exists on one side, never synced | push / pull |

STATE         RESOURCE           LOCAL                            LOCAL#      SERVER#
server-ahead  agents/senior-dev  .agentos/agents/senior-dev.yaml  0187d639c8  34e1bb42c8

28 resources — 27 in-sync, 1 server-ahead

Only drift is listed; --all includes the in-sync rows. A resource counts as locally changed whether you edited its mirror file or its entry in agentos.yml — the LOCAL column names whichever one differs. Note that push applies agentos.yml, so a mirror-file edit is reported but not yet pushable; move it into agentos.yml (or edit in the UI and pull).

agentos diff <target> prints a standard unified diff, --- local and +++ server, so a + line is what pulling would give you and a - line is what pushing would send. The target is <kind>/<slug> (agents, skills, template-tasks, templates); a bare slug is searched across kinds and a path like .agentos/agents/senior-dev.yaml works too.

agentos init binds a directory to a project: it writes .agentos/config.json (inside .agentos/, never at repo root) and, if there isn't one already, an agentos.yml scaffold. It never overwrites an existing agentos.yml, and works with the server down.

Global options, before or after the command:

agentos --server http://127.0.0.1:4141 --cwd ~/code/my-app status

There is no login / logout / whoami: the server is single-user on 127.0.0.1, with no token and no org to authenticate against.

Triggers, automations, MCPs, env vars and projects round-trip through agentos.yml only — they have no per-resource mirror file, so status and diff do not cover them.

Planner/worker model split. Seeded thinking roles (spec, plan, orchestrator, review-coordinator, diagnostic) leave model empty so they inherit your CLI default — your strongest model. Execution roles (senior-dev, librarian, the three review specialists) pin the fast tier. Danny's rule, verbatim: only use Fable for planning and speccing, never for implementing. Goals can also force one runner for every specialist they spawn (Goal → Runner).

MCP servers are registered once (MCPs view or mcps: in YAML) and granted per agent, so only the agents that need Playwright or GitHub get them. AgentOS writes the per-session wiring: a --mcp-config file for Claude, -c mcp_servers.* overrides for Codex. Env vars (Env Vars view or env_vars:) are injected into the session environment, scoped globally or to one agent/project — values are masked in every list view.

Phone pings

Settings → ntfy_topic: install the ntfy app, subscribe to a private topic string, and AgentOS pushes "needs your input / done / stuck" to your phone. macOS Notification Center works out of the box.

Honest differences vs. Danny's cloud version

• No container walls. His agents run in network-restricted cloud containers; here they're local processes with your user's permissions running in bypass-permissions mode. Least privilege lives in prompts + per-agent grants, not an enforced sandbox — don't point it at repos/secrets you wouldn't hand a contractor.
• Approval gates are enforced by the server against the UI/CLI, but a malicious local process could hit the localhost API directly. Fine for a single-operator machine; not multi-tenant.
• Spend caps are replaced by iteration/time caps — subscriptions have no marginal cost.

Layout

server/   db, runners, sessions, engine, goals, API (Express + SQLite + SSE)
bin/      agentos (CLI), agentos-msg (inbox bridge injected into sessions)
public/   no-build dark SPA (kanban, goals, inbox, live session viewer, editors)
docs/     API contract, research notes
.agentos/    per-repo YAML mirror + config.json + .sync.json (see Sync)
~/.agentos/  database, per-agent files, ephemeral workspaces