astro-code

The AI coding crew of the Astro family, with a human at the helm.
Plans, builds and verifies code with agents, and closes nothing until a human signs off.

What astro-code is

Planning and execution for coding agents. It runs a
discuss → plan → execute → verify → accept loop over milestones and phases, kept as
plain files in your repo — so an agent can't wander off, and nothing is ever marked done
without a human saying so.

Works with Claude Code, Codex CLI, Cursor (IDE agent and cursor-agent
CLI) and OpenCode from one install, on Claude or on a local model (every agent then runs on the
session's model). Requires Node ≥ 22.

📘 Open the visual guide →
The fastest way in if you've never seen astro-code. For the full reference, read
MANUAL.md.

Install

git clone [email protected]:uublive/astro-code.git
cd astro-code
npm install -g .     # puts `ac` on your PATH
ac install           # publishes commands to every agent harness it finds

Idempotent. ac uninstall reverses it, /astro-update keeps it current.

ac install also grants Claude Code the permission to run the workflows from ~/.astro/code
(the output of ac path, added to permissions.additionalDirectories), and ac doctor checks
the install is consistent — see
MANUAL.md.

Windows: use astrocode install — PowerShell's built-in ac alias shadows the CLI.
See MANUAL.md.

Your first phase

Work inside the repo you're building. Give it an origin remote first — phase numbers are
claimed from a shared registry so two people can never grab the same one.

ac registry init          # once per project

Then, in Claude Code:

/astro-new-project        set up .astrocode/  (or /astro-adopt on existing code)
/astro-phase "Billing"    add a piece of work — claims its number
/astro-discuss 1          it asks, you answer → CONTEXT.md
/astro-plan 1             parallel research → PLAN.md
/astro-execute 1          builds it in parallel, then checks itself
/astro-accept 1           your sign-off — this is what closes it

Lost at any point? /astro-status tells you where you are and what to run next.

On Codex, type $astro-plan 1 instead — it has no slash commands. Everything else is
identical. On Cursor, the same /astro-plan 1 works; install Cursor's CLI with
brew install --cask cursor-cli (gives cursor-agent) and re-run ac install. On
OpenCode, the same /astro-plan 1 works too — see
MANUAL.md for mapping roles to your provider's models.

The five steps

verified means the machine checked it. complete means a human accepted it. They are
different claims and the tool refuses to conflate them.

Other ways in: /astro-autonomous <n> runs steps 1–4 unattended then stops,
/astro-fast "<prompt>" takes a long off-the-cuff request straight to execution, and
/astro-fix "<bug>" fixes a bug without burning a phase number.

Three things not to do

• Don't hand-edit .astrocode/roadmap.json, state.json, or the registry. They're
  bookkeeping for the shared numbering; editing them corrupts it silently.
• Don't write in ROADMAP.md — it's generated. Use ac phase note <n> "<text>".
• Don't file a bug as a phase. That's what /astro-fix is for.

Found a bug?

Please open one — new issue.
What helps most:

• the version — cat ~/.astro/code/version
• what you ran, and what it printed — paste the console output verbatim
• what you expected instead
• whether your project has an origin remote and a registry (ac registry show)

Small, reproducible reports are genuinely more useful than polished ones. If something is
merely confusing rather than broken, that's worth an issue too — confusing is a bug in the
docs.

Docs

Development

npm test     # engine units + a real bare-remote registry/canon integration test

Contributions follow git-flow — PRs target develop, never main. See
CONTRIBUTING.md.

Licence

Apache License 2.0 — see LICENSE and NOTICE. The licence
does not cover the "astro-code" and "Astrolize" names or the logo.