New advertisers: 50% off your first month with code FIRSTMONTHSee slots

Planning-first LLM OS for Claude Code with durable plans, TDD phases, and agent-separated review.

version
3.8.0-alpha.21
GitHub stars
26

What it does

  • Adds 15 agents, 56 skills, 24 commands, 46 hooks, and 8 MCP servers, including /run and /project init
  • Covers a 5-phase TDD workflow with two approval gates, plus hierarchical plans saved to .claude/plans/
  • Enforces that the reviewing agent is never the agent that wrote the code, and flags ungrounded claims
  • Designed for solo developers and small teams who want plans to survive session resets and reboots

Planning-first LLM OS for software engineering. Hierarchical planning (T0-T4) survives session reset · forensic reasoning traces · L1+L2 conflict detection · self-healing safety gates · per-agent MCP security · durable project-context snapshots · cross-tool porter (Copilot/Codex/Cursor) · CLI dashboard. 15 agents, 5-phase TDD, 71 rules, 56 skills, 24 commands, 46 hooks, 8 MCP servers. Backward-compatible — /run unchanged.

Add marketplace

/plugin marketplace add nguyenthienthanh/aura-frog

Run it inside Claude Code once, then install the plugin below.

Install

/plugin install aura-frog@archon

Run it inside Claude Code after adding the marketplace.

From the nguyenthienthanh/aura-frog README

Archon OS — a planning-first LLM operating system for software engineering

Archon OS

Claude Code, with a plan it doesn't forget.

A plugin for Claude Code that asks the questions first, writes a failing test second, and never lets the agent that wrote the code be the one that approves it.

npm Version License Claude Code Portable PRs Welcome

Install · Your first five minutes · What it gives you · Docs


The problem

You type a prompt. Claude writes 500 lines. You read them and realise it solved a different problem. You say "no, I meant—" and it rewrites everything from scratch.

Then you close the terminal, and tomorrow it has forgotten the whole conversation.

You are the project manager, the QA lead, and the architect — while trying to code.

What Archon OS does about it

It asks before it builds. On anything non-trivial, you get the trade-offs and the file list first, and you approve or redirect before a line is written.

It writes the test before the code. Not as a style preference — a failing test is the only statement of "done" that can't be talked out of.

It doesn't grade its own homework. The agent that reviews is never the agent that built. That one rule is why the output is shippable instead of merely self-consistent.

It remembers. Plans live on disk, not in the context window. Close the terminal, run /compact, reboot the machine — the plan is still there tomorrow.


Install in 30 seconds

You need Claude Code, Node 18+, and git.

/plugin marketplace add nguyenthienthanh/archon
/plugin install archon-os@archon
/archon status

That last line should print the roster:

Archon OS v4.0.0-alpha.3 — Ready
  Agents:   15 loaded
  Skills:   45 available (10 auto-invoke, 35 on-demand)
  Rules:    73 loaded (22 core + 20 agent + 31 workflow)
  Hooks:    54 registered
  MCP:      context7, playwright, vitest, firebase, figma, slack

One more thing, once per project:

/project init

This reads your codebase and writes down what it found — framework, conventions, patterns, architecture. Takes under a minute, and every session afterwards starts already knowing where things are.

Install didn't work?
What you seeUsually meansTry
/plugin install failsStale marketplace cache/plugin marketplace refresh
Nothing happens on editsHooks aren't wired into .claude/settings.json/archon setup integrations
archon: command not foundThe CLI isn't on your PATH/archon setup cli
It picks the wrong specialistIt hasn't read your project yet/project init

Longer version: GET_STARTED.md · TROUBLESHOOTING.md

Upgrading from Aura Frog (v3)?

v4 renamed the project. Upgrade and keep working — every old name still functions, nothing on disk moves, and no .envrc approval is revoked. The one-page account of what changed and when the old names go away: MIGRATION_V4.md.

Other ways to get it (npm, other AI tools)

The payload is on npm as archon-os, under the alpha tag. The marketplace above is still the normal route; npm exists so a team marketplace can pull from the registry ("source": {"source": "npm", "package": "archon-os"}), and so you can read what ships before installing it: npm pack archon-os@alpha.

About 87% of Archon OS is markdown, not code, so most of it moves to other tools. Copy archon-os/skills/* into Codex / Gemini CLI / OpenCode and the skills work. Hooks, agent dispatch, and the bundled MCP servers are Claude Code only. Portability guide →


Your first five minutes

There are really only two commands. Both take plain English.

/run — do a thing

/run fix the login button not disabling on submit

Archon OS sizes the job itself. A typo is a direct edit. A bug gets investigate → failing test → minimal fix → verify. A feature gets the full five phases with two approval gates. You never pick. How it decides →

Here is what a real feature run looks like:

You: /run add user authentication

  Phase 1 — Understand + Design
     JWT or session cookies? Here's the trade-off for your stack.
     3 endpoints, 2 new files, 1 migration. Approve?

You: approve

  Phase 2 — Test RED        5 tests written. All failing. Good.
  Phase 3 — Build GREEN     5/5 passing. Approve?

You: approve

  Phase 4 — Review          Reviewed by a different agent. 2 findings, both fixed.
  Phase 5 — Finalize        Docs updated. Plan synced. Done.

Mid-run you can just type words — no slash needed: approve, reject <why>, modify <change>, status, progress, handoff, rollback, stop.

/archon-os:plan — keep track of a big thing

For work that won't fit in one sitting. It breaks a goal down into Mission → Initiative → Feature → Story → Task, writes the tree to .claude/plans/, and hands you one task at a time.

/archon-os:plan            # no arguments: it interviews you
/archon-os:plan next       # what should I do now?
/archon-os:plan status     # where are we?

With a plan active, bare verbs work too: type next, or expand FEAT-A.

The two halves connect. /run feature: FEAT-A <task> ties a run to a plan node, and when the run finishes its results land back in the tree. You can walk away for a week and pick up where you stopped.

Next: First workflow tutorial (15 min, hands-on) or a full transcript of a real run if you'd rather read than type.


What it gives you

Eight things, each one switchable with a single environment variable — so you can take them one at a time rather than all at once.

What it stops happening
Plans that outlive the sessionClosing the terminal loses your plan. Now it's a folder tree on disk that survives /compact, a reboot, and next week.
A record of why"Where did that number come from?" Every claim an agent makes is linked to the file read it came from. Ungrounded claims get flagged, not printed.
Memory that compoundsWeek three re-litigating a week-one decision. Finished features distil into a permanent memo that future sessions load in ~120 tokens.
Bad output caught before diskA generated path like rm -rf $UNSET_VAR landing in a script. Seven linters run on every write.
Parallel work that doesn't collideTwo tasks silently overwriting each other's file. File- and function-level overlap is detected, and descendants freeze until it's resolved.
Failures that diagnose themselvesReading a stack trace from scratch. Local failures come with a proposed patch — proposed, never auto-applied.
External tools on a leashAn agent calling an MCP server it had no business calling. Per-agent allowlists, rate limits, and an audit log.
A reviewer who isn't the authorCode that passes only its own tests. Phase 4's reviewer is structurally not Phase 3's builder.

The 8 Pillars in full → · Why each one exists →


Everyday commands

CommandWhat you'd say out loud
/run <task>"Do this." Feature, bug, refactor, test, review, deploy — it detects which.
/archon-os:plan <verb>"Keep track of this bigger thing." expand · next · status · replan · promote · archive · undo · freeze · thaw · conflicts
/check"Is anything wrong?" security · perf · complexity · debt · coverage · deps
/design"Draw it before we build it." api · db · doc
/project"Learn my codebase." init · status · refresh · env · sync
/archon"How are you doing?" status · agents · metrics · learn · setup
/help"What can you do?" /help <command> also works.

All 26 commands, every flag →


Is this for you?

Worth it if you ship multi-week features, you've been burned by an agent confidently describing code it never read, you have parallel work that can collide, or you lean on MCP integrations and want them audited.

Probably not if you mostly do single-file edits and quick prototypes — the structure won't pay for itself. (/run task: <thing> skips straight past it when you want.) Also note that planning and design phases want Sonnet or Opus; Haiku-only budgets lose some of the value.

We keep an unflattering list of what doesn't work yet, what's still queued, and what we got wrong and corrected: maturity report →. There's also an honest comparison with other Claude Code plugins — they optimise for different things, and all of them coexist fine.


Where to go next

You want to…Read
Get it working, properlyGET_STARTED.md
Follow a tutorialFIRST_WORKFLOW_TUTORIAL.md
See a real run end to endWALKTHROUGH.md
Understand the designos-architecture.md
Know what it costs in tokensTOKEN_BUDGET.md
Fix somethingTROUBLESHOOTING.md
Upgrade from v3MIGRATION_V4.md
Hack on Archon OS itselfCONTRIBUTING.md · contributor docs
Read everythingdocs/README.md

Contributing

New MCP integrations, agents, skills and bug fixes are all welcome. CONTRIBUTING.md covers the setup, the test suite, and what review looks like; the contributor docs cover how the internals fit together.

Godot and SEO/GEO modules ship as separate add-ons.

License

MIT — see LICENSE.


The Archon OS owl watching a plan tree

Your AI writes the code. Archon OS runs the shop.

Install · Tutorial · Report an issue

Built by @nguyenthienthanh · Changelog

Details

Marketplace
nguyenthienthanh/aura-frog
Source
aura-frog
Author
Nguyen Thien Thanh
Category
Community
License
MIT
Keywords
claude-code, ai-agents, workflow, tdd, multi-agent, react-native, vue, laravel, nextjs, flutter

More from nguyenthienthanh/aura-frog

All 2

Similar to aura-frog

More Frontend & UI