Archon

Archon is a ticket-driven interface for AI-assisted code automation. Create tickets, plan features, then let an AI agent such as Claude 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 | | 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.

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