Archon/docs/getting-started.md

Getting Started

Everything you need to go from zero to a working Archon setup — whether you prefer the Web UI or the CLI.

---

Prerequisites

Before you start, make sure you have:

Requirement	How to check	How to install
Git	git --version	git-scm.com
Bun (replaces Node.js + npm)	bun --version	Linux/macOS: curl -fsSL https://bun.sh/install | bash — Windows: powershell -c "irm bun.sh/install.ps1 | iex"
Claude Code CLI	claude --version	docs.claude.com/claude-code/installation
GitHub account	—	github.com

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:

adduser archon          # create user (Debian/Ubuntu)
usermod -aG sudo archon # 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. If you run into issues, see the Windows notes in the main README.

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.

---

Step 1: Clone and Install

First, pick where to put the Archon server code:

Option A: Home directory (personal use, single user)

Linux/macOS:

cd ~  # or your preferred directory
git clone https://github.com/coleam00/Archon
cd Archon

Windows (PowerShell):

cd $HOME  # or your preferred directory
git clone https://github.com/coleam00/Archon
cd Archon

Option B: /opt (Linux/macOS server installs — keeps things tidy)

sudo mkdir -p /opt/archon
sudo chown $USER:$USER /opt/archon
git clone https://github.com/coleam00/Archon /opt/archon
cd /opt/archon

Then install dependencies:

bun install

This installs all dependencies across the monorepo. Takes about 30 seconds.

---

Step 2: Set Up Authentication

You need two things: a GitHub token (for cloning repos) and Claude authentication (for the AI assistant).

GitHub Token

1. Go to github.com/settings/tokens
2. Click "Generate new token (classic)"
3. Select scope: repo
4. Copy the token (starts with ghp_...)

Claude Authentication

If you already use Claude Code, you're probably already authenticated. Check with:

claude --version

If not authenticated:

claude /login

Follow the browser flow to log in. This stores credentials globally — no API keys needed.

---

Step 3: Create Your .env File

Required for Web UI / server mode. Optional for CLI-only usage — the CLI uses your existing Claude authentication by default.

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.

---

Choose Your Path

Path A: Web UI (Server)

Step 4: Start the Server

bun run dev

This starts two things simultaneously:

• Backend API server on http://localhost:3090
• Web UI on http://localhost:5173

You should see output like:

[server] Hono server listening on port 3090
[web] VITE ready in Xms
[web] Local: http://localhost:5173/

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:

bun run dev:web -- --host 0.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.

Step 5: Verify It Works

Open http://localhost:5173 in your browser. You should see the Archon Web UI.

Quick verification checklist:

1. Health check — In a new terminal:

   curl http://localhost:3090/health
   # Expected: {"status":"ok"}
   

2. Database check:

   curl http://localhost:3090/health/db
   # Expected: {"status":"ok","database":"connected"}
   

3. Send a test message — In the Web UI, create a new conversation and type:

   /status
   

   You should see a status response showing the platform type and session info.

If all three work, you're up and running.

Step 6: Clone a Repository and Start Coding

In the Web UI chat, clone a repo to work with:

/clone https://github.com/user/your-repo

Then just talk to the AI:

What's the structure of this repo?

The AI will analyze the codebase and respond. You can also use workflows:

/workflow list

This shows all available workflows. Try one:

Help me understand the authentication module

The AI router automatically picks the right workflow based on your message.

---

Path B: CLI (No Server)

Step 4: Install the CLI globally

cd packages/cli && bun link && cd ../..

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:

# Add to your shell profile (~/.bashrc, ~/.zshrc, etc.)
echo 'export PATH="$HOME/.bun/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Verify it works:

archon version

Step 5: Run workflows from your repository

cd /path/to/your/repository

# See available workflows
archon workflow list

# Ask a question about the codebase
archon workflow run archon-assist "How does the auth module work?"

# Plan a feature on an isolated branch
archon workflow run archon-feature-development --branch feat/dark-mode "Add dark mode"

# Fix a GitHub issue
archon workflow run archon-fix-github-issue --branch fix/issue-42 "Fix issue #42"

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.

---

CLI Reference

Workflows

# List all available workflows
archon workflow list

# Run a workflow
archon workflow run <name> "<message>"

# Run with worktree isolation (recommended for code changes)
archon workflow run <name> --branch <branch-name> "<message>"

# Run on branch directly without worktree
archon workflow run <name> --branch <branch-name> --no-worktree "<message>"

# Run against a different directory
archon workflow run <name> --cwd /path/to/repo "<message>"

Worktree Management

archon isolation list              # show active worktrees
archon isolation cleanup           # remove stale (>7 days)
archon isolation cleanup 14        # custom staleness threshold
archon isolation cleanup --merged  # remove merged branches (deletes remote too)
archon complete <branch>           # complete branch lifecycle (worktree + branches)
archon complete <branch> --force   # skip uncommitted-changes check

Available Workflows

Workflow	What It Does
archon-assist	General Q&A, debugging, exploration, CI failures — catch-all
archon-fix-github-issue	Investigate → root cause analysis → implement fix → validate → PR
archon-idea-to-pr	Feature idea → plan → implement → validate → PR → parallel reviews → self-fix
archon-plan-to-pr	Execute existing plan → implement → validate → PR → review
archon-feature-development	Implement feature from plan → validate → create PR
archon-comprehensive-pr-review	Multi-agent PR review (5 parallel reviewers) with automatic fixes
archon-smart-pr-review	Complexity-adaptive PR review — routes to relevant agents only
archon-create-issue	Classify problem → gather context → investigate → create GitHub issue
archon-validate-pr	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

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.

---

Customize Your Target Repo

Add an .archon/ directory to your target repo for repo-specific behavior:

your-repo/
└── .archon/
    ├── config.yaml         # AI assistant, worktree copy rules
    ├── commands/            # Custom commands (.md files)
    └── workflows/           # Custom multi-step workflows (.yaml files)

Example .archon/config.yaml:

assistant: claude
commands:
  folder: .claude/commands/archon    # additional command search path
worktree:
  copyFiles:
    - .env.example -> .env           # copy + rename into worktrees
    - .env

Without any .archon/ config, the platform uses sensible defaults (bundled commands and workflows).

Custom Commands

Place .md files in your repo's .archon/commands/:

---
description: Run the full test suite
argument-hint: <module>
---

# Test Runner

Run tests for: $ARGUMENTS

Variables available: $1, $2, $3 (positional), $ARGUMENTS (all args), $ARTIFACTS_DIR (workflow artifacts directory), $WORKFLOW_ID (run ID), $BASE_BRANCH (base branch), $nodeId.output (DAG node output).

Custom Workflows

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.

---

Isolation (Worktrees)

When you use the --branch flag, the CLI creates a git worktree so your work happens in an isolated directory under ~/.archon/worktrees/. This prevents parallel tasks from conflicting with each other or your main branch.

~/.archon/
├── archon.db              # SQLite database (auto-created)
├── workspaces/            # Cloned repos (synced from origin)
│   └── owner/repo/
└── worktrees/             # Isolated working copies per task
    └── repo-name/
        ├── fix/issue-42/
        └── feat/dark-mode/

---

Using With Claude Code (Skill)

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.

To install manually instead:

cp -r remote-coding-agent/.claude/skills/archon /path/to/your/repo/.claude/skills/

Then in Claude Code, say things like "use archon to fix issue #42" and it will invoke the appropriate workflow.

---

Running the Full Platform (Server + Chat Adapters)

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".

---

Troubleshooting

"Cannot create worktree: not in a git repository" (but the repo exists)

The real cause is usually a stale symlink from a previous Archon run with a different path. Look for this in the error output:

Source symlink at ~/.archon/workspaces/.../source already points to <old-path>, expected <new-path>

Fix it by manually deleting the stale workspace folder at ~/.archon/workspaces/<github-user>/<repo-name> and retrying the command.

In the future, archon isolation cleanup will handle this automatically.

---

"command not found: bun"

Install Bun: curl -fsSL https://bun.sh/install | bash, then restart your terminal (or source ~/.bashrc).

"command not found: claude"

Install Claude Code CLI: see docs.claude.com/claude-code/installation.

Port 3090 already in use

Something else is using the port. Either stop it or override:

PORT=4000 bun run dev

Web UI shows "disconnected"

Make sure the backend is running (bun run dev starts both). Check the terminal for errors. Try refreshing the browser.

Clone command fails with 401/403

Your GitHub token is missing or invalid. Verify:

# Test your token
curl -H "Authorization: token $(grep GH_TOKEN .env | cut -d= -f2)" https://api.github.com/user

If it returns your GitHub profile, the token works. If not, regenerate it.

AI doesn't respond

Check that Claude authentication is working:

claude --version   # Should show version
claude /login      # Re-authenticate if needed

"Cannot find module" or dependency errors

bun install

If that doesn't fix it, delete the node_modules folder and reinstall:

bun install

---

Quick Reference

Action	Command
Start everything	bun run dev
Start backend only	bun run dev:server
Start frontend only	bun run dev:web
Run tests	bun run test
Type check	bun run type-check
Full validation	bun run validate
Web UI	http://localhost:5173
API server	http://localhost:3090
Health check	curl http://localhost:3090/health

---

What's Next?

Add a chat platform (optional)

Want to message Archon from your phone? Pick one:

Platform	Difficulty	Guide
Telegram	Easy (5 min)	README: Telegram Setup
Discord	Easy (5 min)	README: Discord Setup
Slack	Medium (15 min)	docs/slack-setup.md
GitHub Webhooks	Medium (15 min)	README: GitHub Setup

Create custom commands and workflows

Add AI prompts to your repo that Archon can execute:

your-repo/
└── .archon/
    ├── commands/        # Markdown files with AI instructions
    └── workflows/       # YAML files chaining commands together

See Authoring Workflows and Authoring Commands.

Deploy to a server

For always-on access from any device, see the Cloud Deployment Guide.

---

Further Reading

• README.md — Full documentation (all platforms, Docker, advanced config)
• New Developer Guide — How Archon works (concepts and architecture)
• Configuration — All configuration options
• Authoring Workflows — Creating custom workflows