Axion — mission control for AI coding agents

A local, open-source web app to run AI coding CLIs in isolated git worktrees, review their diffs, and merge only what you approve. Formerly AI-Orc; the old standalone dashboard is now merged into packages/core.

Two isolated agent sessions on a demo repository, with the diff review open: nothing merges until you approve the exact diff you reviewed.

---

What it does

Feature	Description
Live terminals	Full xterm.js terminals for each CLI — type and see real-time output
Dashboard	See all tools at a glance, launch with one click
Obsidian vault	Browse and edit your .md notes; edits persist directly to your vault
Tool registry	Paste a GitHub URL → repo is cloned → install steps extracted from README
Extensible	Add any open-source AI tool, model, or CLI by pasting its GitHub repo URL
Local & private	All data stays on your machine — no cloud, no telemetry

---

Isolated worktree sessions

Add git repositories under Settings → Repositories, then pick one in the Isolated worktree dropdown when launching a tool. The session runs in its own git worktree on a new axion/<tool>-<session> branch under ~/.axion/worktrees/, so two agents can edit the same repo without touching each other or your checkout.

• Refuses to start when the repository has uncommitted changes to tracked files (they would not appear in the worktree). Untracked files are ignored.
• The browser never sends a path: the WebSocket message carries a repo id, and the server only honours ids of repos in your saved config. Each repo must be an existing git repository root and not / or your home folder.
• Worktrees and branches are kept after a session ends. The Worktrees page shows branch, uncommitted changes and commit count, and removes one (deleting its branch). Removing one with uncommitted or unmerged work needs an explicit confirmation.
• Restarting a terminal reuses its worktree.
• Review and approval: the Worktrees page has a Review button showing the changed files and the full diff (new files included). Approve & merge commits the session's work and merges it into the branch checked out in the main repo with a merge commit (--no-ff). Approval is bound to the exact diff you reviewed: if the agent changes anything afterwards, the merge is refused and you must review again. It also refuses a dirty main checkout, a detached HEAD, an empty diff, and a conflicting merge (which is aborted, leaving main clean and the session intact). After a successful merge the session worktree and branch are removed. Nothing merges without this explicit approval.
• Audit log: merges, refused merges, rejections and removals are appended as JSON lines to ~/.axion/audit.log (newest 20 shown on the Worktrees page, GET /api/audit). Your repository's own git hooks run on the commit and merge, as they would for you.
• Verify before merge (optional): set a verify command per repository in Settings (a program and arguments, run without a shell inside the session worktree, 5 minute limit, e.g. npm test). A session can then only be approved after that command passed on the exact diff you are merging; any later change invalidates the result. Runs and failures are in the audit log (verified, verify-failed).
• Loop warning: if a terminal prints the same line (or the same few lines) over and over, the panel shows a dismissable warning so you can stop a stuck agent. It is advisory and never stops the session by itself.
• All git calls use argument arrays without a shell.

---

Adding an agent adapter

Built-in tools are agent adapters in packages/agents. To support a new CLI, add packages/agents/src/adapters/<name>.ts exporting an AgentAdapter (id, label, bare command, args, installHint, capabilities, optional headlessArgs) and list it in packages/agents/src/registry.ts. Commands must be bare executable names (no paths or spaces); the registry rejects anything else. Existing installs pick up new built-ins automatically because built-ins are not stored in ~/.axion/db.json.

---

Built-in tools

Out of the box Axion launches terminals for:

• Claude Code (claude)
• Gemini CLI (gemini)
• Codex CLI (codex)
• OpenCode (opencode)

Any of these you have installed will work immediately. Add more via the Registry.

---

Prerequisites

• Node.js 20+
• Git on PATH
• The CLI tools you want to use must already be installed (claude, gemini, codex)
• An Obsidian vault folder (optional — for the Vault page)

---

Install & run

git clone https://github.com/WickTech/axion
cd axion
npm install    # installs every workspace from the repo root
npm run dev    # starts apps/web

Open http://localhost:3000.

Note for WSL users: The server binds to 127.0.0.1:3000 by default — WSL2 forwards localhost automatically, so http://localhost:3000 from your Windows browser just works. There is no auth on the terminal/vault APIs, so only set HOST=0.0.0.0 if you understand that exposes process-spawning to your whole LAN.

First-time setup

1. Open Settings → set your Obsidian vault path (e.g. /home/you/MyVault)
2. Return to Dashboard — your tools are ready to launch

---

Pages

Route	Purpose
/	Dashboard — tool cards with one-click launch
/terminals	Live xterm.js terminals, tabbed per tool instance
/vault	Obsidian file tree + markdown editor (Ctrl+S to save)
/registry	Add tools via GitHub URL
/settings	Vault path, server port

---

This is the beginning of the README. Read the rest at the original. Read the full README ↗