Do not run as root. Archon (and the Claude Code CLI it depends on) does not work when run as the root user. If you’re on a VPS or server that only has root, create a regular user first:
Terminal window
adduserarchon# create user (Debian/Ubuntu)
usermod-aGsudoarchon# give sudo access
su-archon# switch to the new user
Then follow this guide from within that user’s session.
Windows users: Archon runs natively on Windows — no WSL2 required. Install Git for Windows (which includes Git Bash) and Bun for Windows. One caveat: DAG workflow bash: nodes need a bash executable — Git Bash provides this automatically.
Bun replaces Node.js — you do not need Node.js or npm installed. Bun is the runtime, package manager, and test runner for this project. If you already have Node.js, that’s fine, but Archon won’t use it.
Required for Web UI / server mode. Optional for CLI-only usage — the CLI uses your existing Claude authentication by default.
Terminal window
cp.env.example.env
Open .env in your editor and set these two values:
# Paste your GitHub token in both (they serve different parts of the system)
GH_TOKEN=ghp_your_token_here
GITHUB_TOKEN=ghp_your_token_here
# Use your existing Claude Code login
CLAUDE_USE_GLOBAL_AUTH=true
That’s it. Everything else has sensible defaults:
Database: SQLite at ~/.archon/archon.db (auto-created, zero setup)
Port: 3090 for the API server, 5173 for the Web UI dev server
AI assistant: Claude (default)
Why two GitHub token variables?GH_TOKEN is used by the GitHub CLI (gh), and GITHUB_TOKEN is used by Archon’s GitHub adapter. Set them to the same value.
Homelab / remote server? The backend API already binds to 0.0.0.0 by default, so it’s reachable from other machines. However, the Vite dev server (Web UI) only listens on localhost. To expose the Web UI on your network:
Terminal window
bunrundev:web----host0.0.0.0
Then start the backend separately with bun run dev:server. The Web UI will be reachable at http://<server-ip>:5173. Make sure your firewall allows ports 5173 and 3090.
This registers the archon command globally so you can run it from any repository.
You’ll see output like Success! Registered "@archon/cli" followed by a message about bun link @archon/cli — ignore that second part, it’s for adding Archon as a dependency in another project.
Bun installs linked binaries to ~/.bun/bin/. If the archon command isn’t found, that directory is not in your PATH yet. Fix it:
Terminal window
# Add to your shell profile (~/.bashrc, ~/.zshrc, etc.)
That’s it. The CLI auto-detects the git repo, uses SQLite for state tracking (~/.archon/archon.db), and streams output to stdout.
The target directory must be a git repository. Archon uses git worktrees for isolation, so it needs a .git folder. If your project isn’t a git repo yet, run git init && git add . && git commit -m "initial commit" first.
Thorough PR validation testing both main and feature branches
archon-resolve-conflicts
Detect, analyze, and resolve merge conflicts in PRs
archon-refactor-safely
Safe refactoring with type-check hooks and behavior verification
archon-architect
Architectural sweep, complexity reduction, codebase health
archon-ralph-dag
PRD implementation loop (iterate through stories until done)
archon-issue-review-full
Comprehensive fix + full multi-agent review for GitHub issues
archon-test-loop-dag
Iterative test-fix cycle until all tests pass
archon-remotion-generate
Generate or modify Remotion video compositions with AI
archon-interactive-prd
Create a PRD through guided conversation
archon-piv-loop
Guided Plan-Implement-Validate development with human-in-the-loop
archon-adversarial-dev
Build a complete application from scratch using adversarial development
These bundled workflows work for most projects. To customize, copy one from .archon/workflows/defaults/ into .archon/workflows/ and modify it — same-named files override the defaults.
Auto-selection: You don’t need to remember workflow names. Just describe what you want — the router reads all workflow descriptions and picks the best match. For example, “fix issue #42” routes to archon-fix-github-issue, while “review this PR” routes to archon-smart-pr-review. If nothing matches clearly, it falls back to archon-assist.
Place .yaml files in your repo’s .archon/workflows/:
name: my-workflow
description: Plan then implement a feature
model: sonnet
nodes:
- id: plan
command: plan
- id: implement
command: implement
depends_on: [plan]
context: fresh
Workflows chain multiple commands as DAG nodes, support parallel execution, conditional branching, and carry context between nodes via $nodeId.output substitution.
Where are commands and workflows loaded from?
Commands and workflows are loaded at runtime from the current working directory — not from a fixed global location.
CLI: Reads from wherever you run the archon command. If you run from your local repo, it picks up uncommitted changes immediately.
Server (Telegram/Slack/GitHub): Reads from the workspace clone at ~/.archon/workspaces/owner/repo/. This clone only syncs from the remote before worktree creation, so you need to commit and push changes for the server to see them.
In short: the CLI sees your local files, the server sees what’s been pushed.
When you use the --branch flag, the CLI creates a git worktree so your work happens in an isolated directory. This prevents parallel tasks from conflicting with each other or your main branch.
~/.archon/
├── archon.db # SQLite database (auto-created)
└── workspaces/ # Project-centric layout
└── owner/repo/
├── source/ # Clone or symlink to local path
├── worktrees/ # Isolated working copies per task
│ ├── fix/issue-42/
│ └── feat/dark-mode/
├── artifacts/ # Workflow artifacts (never in git)
If you want Claude Code to be able to invoke Archon workflows on your behalf, install the
Archon skill into your project. The setup wizard handles this automatically — just run
archon setup and accept the skill installation prompt.
The CLI is standalone, but if you also want to interact via Telegram, Slack, Discord, or GitHub webhooks, see the README Server Setup or run the setup wizard by opening Claude Code in the Archon repo and saying “set up archon”.