claude-agent-os

A small company of agents for Claude Code, kept in plain Markdown files.

A ceo agent turns your goal into a plan and tasks. Five roles (marketing, copy, web, soft, research) do the work, and an optional queue picks up one task every 30 minutes with a restricted permission profile. You only get two kinds of work back: tasks that take 15 minutes or less, and decisions with a recommendation already written.

It grew out of a real business that is not a software house (property development, online retail, rentals) and has been running there since August 2026. The 41 rules in this repo were written after things went wrong there.

Status: v0.1.2. Works on Windows, macOS and Linux (CI on all three). Expect rough edges.

Who it is for

A good fit if you

• run several projects at once, alone or with a very small team, and use Claude Code daily;
• want agents to keep working between your sessions, but only inside limits you set;
• prefer files you can read and edit in any editor (or Obsidian) over another web app with a database.

Not a good fit if you

• already run your team in Jira, Linear or similar and need agents to fit that flow;
• want a hosted product with accounts, budgets per agent and a mobile app (look at Paperclip);
• are not comfortable letting an agent edit files in a folder on its own. The queue is off by default, but it is the point of the system.

Start in 5 minutes

Requirements: Python 3.11+, Claude Code installed and logged in, git. No other dependencies: the engine is stdlib only.

git clone https://github.com/KamilMatysikAI/claude-agent-os.git
cd claude-agent-os
python install.py            # wizard: workspace folder, name, language, time zone, queue, panel, notifications, rule packs, demo
cd <your-workspace>
claude

The installer creates a private virtual environment in <your-workspace>/.agentos/venv and installs the engine into it with pip (a normal install, about 20 seconds; it may download setuptools to build the package). Nothing is installed into your system Python. It ends with a "Next steps" block that prints the commands with your real paths.

Then, inside Claude Code:

/setup          a short interview: who you are, your business, how the AI should behave
/new-project    goal -> measurable success criterion with a date -> first plan and tasks from the ceo

Want to look around first? python install.py --with-demo adds two fictional projects (a coffee subscription shop and a podcast launch) with tasks in every state: open decisions, overdue human tasks, blocked chains, work in progress. See demo/README.md. With --language pl the installer copies the Polish demo instead: eight small businesses, 85 tasks, 8 open decisions (demo-pl/README.md).

Non-interactive install, for scripts and CI:

python install.py --non-interactive --workspace ~/agents --owner Alex --language en --no-queue

The installer never overwrites your files (a conflict becomes *.new plus a note in the report) and running it twice gives the same result.

How it works

   you: goal
      |
      v
 +----------+   PROJECT.md (goal, success criterion, out of scope)
 |   ceo    |   PLAN.md (phases)   LOG.md (decisions)
 +----------+
      |  writes tasks, never more than wip_limit (default 5) active per project
      v
 +------------------------+     +-----------------------------------+
 | A-001 agent tasks      |     | H-002 human tasks (<= 15 min)     |
 | owner: copy / web /    |     | type: decision (with a ready      |
 | soft / marketing /     |     |   recommendation and its cost)    |
 | research               |     +-----------------------------------+
 +------------------------+                   ^
      |                                       |
      v                                       |
 +---------------------------+   guard: "blocked" without a human task
 | queue (every N minutes)   |   -> creates one; accepted decision
 | pick 1 -> lock -> claude  |   without an executor -> creates one
 | -p with a profile -> log  |
 | -> unlock -> close only   |
 |    with evidence          |
 +---------------------------+
      |
      v
 projects/dashboard.md + TODO.md block (generated)  -> panel (optional, localhost)
      |
      v
   you: do the short tasks, click the decisions

Everything is a Markdown file with YAML frontmatter:

projects/<slug>/PROJECT.md  PLAN.md  LOG.md  tasks/A-001-*.md  tasks/H-002-*.md  materials/
inbox/                       ad-hoc tasks outside any project
TODO.md                      your view; the block between AGENTOS markers is generated
agentos.toml                 config: owner, language, queue profile, WIP limit, notifications

Engine commands run from the workspace folder with the workspace's own Python. The skills and CLAUDE.md in the workspace use exactly the same command:

.agentos/venv/bin/python -P -m agentos <command>          # macOS / Linux
.agentos/venv/Scripts/python -P -m agentos <command>      # Windows

dashboard     regenerate projects/dashboard.md and the TODO.md block
guard         repair illegal states (idempotent)
status [slug]
run           run one task from the queue (--dry-run to preview)
doctor        check the installation
schedule install|remove|status
panel         local web panel (see below)
usage         token usage per session and subagent, flags runaway agents (--hours 168)

The venv also has an agentos script (.agentos/venv/bin/agentos status). -P keeps the current folder off Python's import path, so a file an agent writes into the workspace can never replace the engine. The scheduled job and the panel's "run now" use the same interpreter.

Offline install: if pip cannot build the package (no network and no setuptools in the venv), the installer says so and links the cloned repo into the venv instead. The commands stay the same, but the engine then runs from the repo folder, so do not move or delete it. Run install.py again when you are online to get a normal install. With --no-venv, run python -m agentos <command> --workspace PATH from the repo folder, or put the repo folder on PYTHONPATH.

To update after git pull, run python install.py again with the same workspace. It reinstalls the engine into the venv and leaves your files alone.

Updates

• What changed: CHANGELOG.md and the releases page. Each entry says whether you have to do anything after updating.
• In the panel: when a newer release is out, the sidebar shows "New version" with a link to the release notes. The panel asks the public GitHub API once a day, sends nothing about your workspace and installs nothing. To turn it off, set check = false under [updates] in agentos.toml, or set AGENTOS_NO_UPDATE_CHECK=1.
• By e-mail: one message when a new version is out: sign up here (po polsku). Unsubscribe with one click.
• On GitHub: Watch → Custom → Releases.

Skills that ship with the workspace: setup, new-project, project, agent-queue, create-task, end, premortem, reflect, memory-update, design-audit, add-idea. Full file and field reference: CONTRACT.md.

The rules (top 11 of 41)

Every rule has the incident behind it. They load into every Claude Code session from .claude/rules/.

Optional packs, switched on in the installer (--rules web,sales): web (verify pages in the render and on mobile, CMS writes with backup first) and sales (do not promise what the product does not do).

Security

Read SECURITY.md before you switch the queue on. The short version:

• The queue is off by default. Nothing runs on a schedule until you say yes in the installer.
• Three permission profiles. safe (default): read, edit and web search inside the workspace, no shell, no MCP servers, no access to .env, ~/.ssh, ~/.aws, keys. developer: adds read-only git and test runners. full: everything, only after you type I understand.
• External input is always safe. Tasks with source: external run with the safe profile whatever the config says. This is enforced in the runner code, not in a prompt.
• Secrets live only in .env. doctor fails if .env is tracked by git.
• The panel has no login. It binds to 127.0.0.1. Do not expose it to the internet.

Terms of service. Running claude -p from a scheduler uses your Claude account or API key. Whether unattended use is allowed, and how much, depends on your plan and on Anthropic's current terms, which change. An API key is the clearest path for automated runs. Check the terms yourself before enabling the queue; this project cannot do it for you.

Costs

• The repo is free (MIT).
• Every queue run that executes a task uses your Claude plan limits or API tokens, the same as if you ran the task by hand.
• A run with nothing to do does not call Claude.
• Defaults keep it bounded: 1 task per run, a run every 30 minutes, 45-minute timeout. You can change all three in agentos.toml.
• When the CLI reports a usage limit, the queue pauses for 60 minutes instead of retrying every tick.

Panel (optional)

A local web page over the same files: Today (what needs you: decisions, your short tasks, agents waiting on you), a decision stack (accept or reject with a note, 5 seconds to undo), projects (health, blocks, WIP; each project page shows what waits on what), the tree (who works on what across the whole portfolio), activity (what was closed, who is working now), all tasks, a form to add a task or an idea (ideas use ideas/.templates/idea.md, like /add-idea), and "run now" for a single agent task. Light and dark theme, works on a phone.

Start it from the workspace folder. --port overrides [panel] port in agentos.toml:

.agentos/venv/bin/python -P -m agentos panel                # then open http://127.0.0.1:8777
.agentos/venv/Scripts/python -P -m agentos panel --port 8787   # Windows, another port

It has no login and binds to 127.0.0.1. Do not expose it to a network you do not control.

Language. The panel speaks English and Polish. The default comes from language in agentos.toml (pl, pl-PL or polish give Polish, anything else English). The PL / EN switch in the sidebar (or the L key, or ?lang=pl in the address) changes it for this browser and is remembered. Plurals and dates follow the language (1 zadanie, 2 zadania, 5 zadań; Sun 11 Oct / niedz. 11.10). Task files stay as they are: section names like ## Goal are part of the file contract and are only shown translated. All texts live in panel/static/i18n.en.json and i18n.pl.json; a new language is one more dictionary plus one line in i18n.js.

Tree. One canvas: you at the root, curves out to every project, then the roles working on it (CEO, Software, Web, Copy, Marketing, Research and you) with their counts, then the open tasks. Colour is state only: grey waiting, blue an agent at work, red blocked or overdue, amber a decision, black your tasks. Filters (Everything, Mine, In progress, Overdue, Blocked), "Expand tasks" / "Collapse to projects", three layouts (compact, expanded, radial; U), "Fit" (F), drag to pan, wheel or pinch to zoom, "Save PNG" for a picture of the whole portfolio. On a phone it opens a shortcut to the projects table, with "Show the tree anyway".

Screenshots from the demo workspaces (--with-demo), English and Polish:

Today	Decisions	Tree

More in English: projects, project, task, activity, tree with tasks; phone: Today, Decisions, Tree, Today, dark.
More in Polish: projekty, projekt, zadanie, aktywność, drzewo z zadaniami, drzewo radialne; telefon: Dziś, Decyzje, Drzewo, Drzewo mimo to, zadanie, Dziś, ciemny.

Recommended external skills

Not bundled, install them from their authors. All MIT.

Install commands change; if one fails, check the package README.

FAQ

Do I need a server or a database?
No. Files, Python stdlib and the OS scheduler (Task Scheduler, launchd, cron or a systemd timer).

Can I use it without the queue?
Yes. Run /project and /agent-queue by hand in a session. That is the best way to spend the first few days.

What does the agent do when it needs me?
It sets the task to blocked and writes an H- task for you: 15 minutes or less, with a first step that takes 1 to 3 minutes. If it forgets, the guard creates one.

What stops it from running in circles?
A task with no progress in 3 runs is blocked and handed to you. Locks expire after 90 minutes. Only one task runs per tick.

Can I change the roles?
Yes, they are plain files in .claude/agents/. Add, remove or rewrite them.

Does it work in languages other than English?
Code and file names stay in English. Set language in agentos.toml and agents write to you in that language.

How is this different from Paperclip, BMAD or ccpm?
Those are mostly built around writing software or need a server. This one is files only, puts the human in as a task owner with time limits, and comes with rules taken from running a non-software business. If you want a hosted dashboard with budgets per agent, Paperclip is the better choice.

How do I uninstall?
python install.py uninstall --workspace PATH --print-only shows what would go; without --print-only it removes the scheduled job, the engine runtime files and the workspace venv (.agentos/venv). Your projects and tasks stay.

Known limits. No budgets per agent, no mobile app, panel without authentication, native Windows runs the developer profile without the Bash sandbox.

Support

Free and MIT. If it saved you a few hours, you can buy me a coffee (the Sponsor button at the top of this repo does the same):

• Buy Me a Coffee (card, Apple Pay, Google Pay)
• buycoffee.to (Poland: BLIK, bank transfer)

A star helps other people find the repo.

Issues and pull requests are welcome. Security problems: see SECURITY.md.

Po polsku

To szablon „firmy z agentów” dla Claude Code. Agent ceo rozpisuje cel na plan i zadania, pięć ról je wykonuje, a kolejka (opcjonalna, domyślnie wyłączona) bierze jedno zadanie co 30 minut w ograniczonym profilu uprawnień. Do Ciebie wracają tylko zadania na 15 minut i decyzje z gotową rekomendacją.

System powstał w firmie spoza IT (deweloperka, e-commerce, wynajem) i działa tam od sierpnia 2026. Każda z 41 reguł ma opisaną wpadkę, po której powstała.

Start:

git clone https://github.com/KamilMatysikAI/claude-agent-os.git
cd claude-agent-os
python install.py
cd <twój-katalog>
claude

W Claude Code: /setup, potem /new-project. Agenci piszą do Ciebie po polsku, gdy w agentos.toml ustawisz language = "pl". Pliki, kod i nazwy pól zostają po angielsku.

Panel (python -P -m agentos panel) też mówi po polsku: przy language = "pl" startuje po polsku, a przełącznik PL / EN w menu (albo klawisz L) zmienia język w tej przeglądarce. Ekran Drzewo pokazuje, kto nad czym pracuje: Ty w środku, od Ciebie projekty, pod nimi role z licznikami, kolor to stan (w toku, zablokowane albo po terminie, decyzja, Twoje). python install.py --language pl --with-demo kopiuje polskie demo: osiem zmyślonych firm, 85 zadań, 8 decyzji.

Instalator tworzy w katalogu roboczym osobne środowisko Pythona (.agentos/venv) i instaluje w nim silnik, systemowego Pythona nie rusza. Polecenia silnika uruchamiasz z katalogu roboczego: .agentos/venv/bin/python -P -m agentos status (Windows: .agentos/venv/Scripts/python).

Zanim włączysz kolejkę, przeczytaj SECURITY.md. claude -p uruchamiane z harmonogramu korzysta z Twojego konta Claude albo klucza API, a to, czy i ile automatycznej pracy wolno, zależy od planu i aktualnego regulaminu Anthropic. Najczystsza droga to klucz API.

Licencja MIT. Jeśli oszczędziło Ci to kilka godzin, możesz postawić kawę: buycoffee.to (BLIK, przelew) albo Buy Me a Coffee (karta).

License: MIT