Archon

Archon is a ticket-driven interface for AI-assisted code automation. Create tickets, plan features, then let an AI agent such as Claude, Codex, or OpenCode implement them in isolated git worktrees.

Install

Archon ships as a global npm package:

npm install -g @straiffi/archon

Then start it with:

archon

Archon will:

1. start the backend and frontend as one local process
2. serve the UI and API from the same origin
3. open your default browser automatically
4. stay attached until you press Ctrl+C

Typical startup output:

Archon running at http://localhost:43110
Press Ctrl+C to stop.

Archon starts on port 43110 by default and scans upward if that port is already in use.

Update

archon update

Supported platforms

V1 targets macOS and Linux first.

External Tool Prerequisites

Archon does not bundle external developer tools.

Required or commonly expected tools:

| Tool | Why it matters | | --- | --- | | git | Required for project repositories, worktrees, diffing, and commit operations | | opencode | Needed for OpenCode-backed plan, build, chat, and review workflows | | claude | Needed for Claude-backed workflows | | codex | Needed for Codex-backed plan, build, chat, spec, and review workflows. Install it separately with npm install -g @openai/codex, then authenticate externally with codex login. | | gh | Optional for GitHub PR and review workflows; GitHub API key integration also works without it |

Archon should still start if an optional tool is missing, but features that depend on that binary or integration path will return actionable errors.

Codex

Archon runs codex app-server --listen stdio:// and discovers the models, reasoning efforts, and skills available to the authenticated execution environment. Archon does not accept, store, refresh, rotate, revoke, or log Codex credentials. Complete host enrollment, cancellation, logout, and reauthentication with the Codex CLI; Docker Sandbox credentials remain owned by Docker's external credential broker.

Host and Docker Sandbox authentication and catalogs are separate. A host-discovered model is only a selection hint for a sandbox: exact sandbox validation and the selected-model destination probe are authoritative before execution. See the Codex agent qualification guide.

OpenCode and Docker Sandbox

Host OpenCode and Docker Sandbox OpenCode are qualified independently. Archon understands the OpenCode v2 runtime and session API on supported host installations, but a sandbox may use v2 only when its Docker Sandbox-compatible template is pinned by immutable OCI index and Linux amd64 manifest digests and passes the complete runtime workflow matrix.

Docker Sandbox execution of OpenCode v2 is intentionally disabled until an official, compatible v2 template is published and qualified. New Docker Sandbox OpenCode environments therefore continue to use the qualified v1 template, and runtime validation rejects v2 before running provider checks. Existing environments pinned to docker.io/docker/sandbox-templates@sha256:88a078fc021d0a2b4c3315f21a6f05dfdda5a6b30369a53d185b5b6544465efc remain resolvable; Archon does not automatically perform cross-major upgrades, convert OpenCode data, or import/export sessions. A cross-major continuation starts a fresh provider session and uses persisted conversation context for the handoff.

The upstream OpenCode 2.0.7 container is recorded only as build provenance and is not itself a Docker Sandbox agent template. Upstream arm64 publication does not imply arm64 support: Docker Sandbox remains qualified only on Linux x64. See Docker Sandbox CLI qualification for the fixed release tuple, provenance digests, validation contracts, and outstanding qualification matrix.

How It Works

Archon has three main workspaces:

1. Board: create tickets, move them through planning and implementation, and run builds in isolated git worktrees on dedicated branches.
2. Chat: use persistent project chat sessions for planning, implementation help, and follow-up questions. Chat supports both planning-oriented and build-oriented turns so you can scope work first, then continue in the same conversation.
3. Memory: optionally save project conventions, accepted decisions, and other prompt context in Archon so future ticket, chat, build, and review runs stay aligned with how your project works.

Within the board workflow, tickets move through three stages:

1. Plan: write a title and description for the feature or task
2. Build: Archon runs your configured AI tool in a new git worktree and streams progress back to the UI in real time
3. Review: an agent reviews the resulting changes and suggests fixes that you can inspect and accept manually

Project Setup

After Archon starts, create a project from the UI:

1. Click Create project
2. Enter a project name and repository path
3. Optionally click Auto-config to fill any empty setup, service, or worktree sync settings
4. Optionally open Advanced settings to review or edit setup, service, worktree sync, and IDE settings
5. Save the project, select it in the project switcher, and create tickets inside that project

Project Configuration

Use the project form in the UI to configure how Archon prepares worktrees and runs project-specific services.

Required fields

| Field | What to enter | |-------|---------------| | Project name | The label shown in the project switcher, such as Platform API or Marketing Site | | Repository path | Any path inside the target git repository; Archon resolves it to the repo root before saving |

Auto-config is available in both the create and edit project modals. It fills only empty Setup commands, Services, and Worktree sync sections, and it never changes IDE command.

Advanced fields

| Field | Guidance | |-------|----------| | Setup commands | Optional newline-separated commands that run inside the new worktree before any services start. Use this for dependency install, code generation, or other one-time setup such as pnpm install or pnpm db:generate. | | Worktree sync | Optional file sync rules that run only when Archon creates a worktree for the first time. Each entry can either copy a file or directory into the new worktree, or symlink back to the project repo. | | Services | Optional background processes to launch after setup completes. Each service needs a command, and can also include a cwd. | | cwd | Optional working directory for a service, relative to the worktree root. For example, use client for a frontend dev server or server for an API process. Leave it blank to run from the worktree root. | | IDE command | Optional command to open the finished worktree in your editor after services start, such as code --reuse-window or idea. |

Example project setup

Project name: My App
Repository path: /Users/you/projects/my-app
Setup commands:
pnpm install
pnpm db:generate

Worktree sync:
- source: node_modules
  mode: symlink
- source: .env
  mode: copy

Services:
- cmd: pnpm dev
  cwd: client
- cmd: pnpm dev
  cwd: server

IDE command: code --reuse-window

Each ticket gets its own worktree and branch derived from the ticket title, using the active project's repository settings. Archon reuses an existing local branch when one already exists; otherwise it creates a new branch for the worktree.

Data Storage

Archon keeps runtime state out of the installed package tree.

Default database locations:

| Platform | Default path | | --- | --- | | macOS | ~/Library/Application Support/Archon/archon.db | | Linux | ~/.local/share/archon/archon.db |

You can override the database location with DB_PATH.

Mobile Access Remote Setup

• Remote mobile access guide: docs/MOBILE_ACCESS_REMOTE_ACCESS_GUIDE.md

License

Archon is distributed under the Archon Package License included with the npm package.

Development And Maintenance

• Contributor workflow: DEVELOPMENT.md
• Release workflow: RELEASING.md