archon

Archon CLI Skill

Archon is a remote agentic coding platform that runs AI workflows in isolated git worktrees. This skill teaches you how to run workflows, create new workflows and commands, and manage Archon configuration.

Available Workflows (live)

!archon workflow list 2>&1 || echo "Archon CLI not installed. Read guides/setup.md to set it up."

Routing

Determine the user's intent and dispatch to the appropriate guide:

If the intent is ambiguous, ask the user to clarify.

Richer Context: archon.diy

The references in this skill are a distilled subset. The full, canonical docs live at archon.diy (Starlight site from packages/docs-web/). If the skill's reference pages don't cover what you need — an edge case, a worked example, a diagram, a deeper section on a feature — fetch the matching page from archon.diy.

When to reach for the live docs

• You need an end-to-end example that's longer than what the skill shows (e.g. full patterns for hooks, MCP config, sandbox schema, approval flows)
• You're explaining a concept to the user and want the most readable framing (the book/ series is written as a tutorial, not a reference)
• You hit a feature the skill only mentions in passing (e.g. agents: inline sub-agents, advanced Codex options, the full SyncHookJSONOutput schema)
• The user asks "where is this documented?" — point them at the archon.diy URL, not a skill file path

URL map

URL shape is archon.diy/<section>/<page>/ — the paths mirror the filenames under packages/docs-web/src/content/docs/.

Precedence

This skill's reference pages are the primary source for routine workflow authoring, CLI use, and setup. Reach for archon.diy when the skill is incomplete for your case — don't go to the live docs first by default (skill refs load into context faster and are tuned for agents).

Running Workflows

Core Command

archon workflow run <workflow-name> --branch <branch-name> "<message>"

CRITICAL RULES:

1. Always run in background — Archon workflows are long-running. Always invoke the Bash tool with run_in_background: true. Use /tasks or the TaskOutput tool to check on progress.

2. Always use worktree isolation — Use the --branch flag unless the user explicitly requests otherwise. This creates an isolated environment so Archon works without affecting the main branch.

3. One workflow per shell — Each workflow blocks its shell. Run multiple workflows as separate background tasks.

Isolation Modes

Workflow Selection

Match the user's intent to a workflow from the live list above. Common patterns:

⚡ = Interactive workflow — requires the transparent relay protocol. Read references/interactive-workflows.md before running.

If no specific workflow matches, use archon-assist as the fallback. The live workflow list above is always authoritative — it may include workflows not in this table.

Multi-Issue Invocation

When the user mentions multiple issues, PRs, or tasks — run each as a separate background task:

# Each gets its own worktree — they won't conflict
archon workflow run archon-fix-github-issue --branch fix/issue-10 "Fix issue #10"
archon workflow run archon-fix-github-issue --branch fix/issue-11 "Fix issue #11"
archon workflow run archon-fix-github-issue --branch fix/issue-12 "Fix issue #12"

Never combine multiple issues into a single command.

Other CLI Commands

archon workflow list              # List all available workflows
archon workflow list --json       # Machine-readable JSON
archon isolation list             # Show active worktree environments
archon isolation cleanup          # Remove stale worktrees (default: 7 days)
archon isolation cleanup --merged # Remove branches merged into main
archon complete <branch>          # Complete branch lifecycle (remove worktree + branches)
archon version                    # Show version info

For the full CLI reference with all flags: Read references/cli-commands.md

Authoring Quick Start

Archon uses a single workflow format: nodes (DAG). Workflows are YAML files in .archon/workflows/.

IMPORTANT: The examples below are starting points. Always design the workflow around what the user actually needs — the number of nodes, their types, dependencies, and configuration should match the user's requirements, not these templates.

Workflow Structure

name: my-workflow
description: What this workflow does
provider: claude          # Optional: 'claude', 'codex', 'pi', ... (default: from config)
model: medium             # Optional: tier keyword (small|medium|large), @alias, or literal model
nodes:
  - id: first-node
    command: my-command    # Loads .archon/commands/my-command.md
  - id: second-node
    prompt: "Use the output: $first-node.output"
    depends_on: [first-node]

Node Types

Each node has exactly ONE of: command, prompt, bash, script, loop, loop_group, approval, or `cance

Content truncated.