Guide · Open source

How to use Archon: install, run workflows and approve runs

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

Archon is an open-source tool that lets you describe a coding process as a YAML workflow: a graph of steps where AI agents handle judgment, scripts run checks such as tests, and a person is asked to decide at points you choose. This guide shows you how to install it, run a workflow in a git repository and respond when a run pauses for your decision. You need Claude Code or Codex installed and signed in, plus Git.

Archoncoleam00/Archon · ★ 23.8k · MIT Install options & downloads

Quick start

1Install your agent. Install Claude Code and sign in, or install Codex. Archon requires one of these agents to be installed and signed in.
2Install Archon. Run the install command for your operating system, or install with Homebrew and then run archon setup.
3Open your repository. Change into a git repository you want Archon to work on.
4List workflows. Run archon workflow list to see the workflows available to you.
5Run a workflow. Start a workflow with a request in quotes using archon workflow run.
6Answer attention items. Open the web console with archon serve or run archon workflow attention to respond when a run pauses.

Check the prerequisites before you install

Archon does not replace your coding agent. It runs Claude Code, Codex and Pi through their own CLIs and SDKs, so those agents must already be installed and signed in with your own accounts. You also need Git, and the project you want to work on should be a git repository.

Claude Code or Codex installed and signed in
Git
A git repository for the project you want Archon to work on

Install Archon on macOS, Linux or Windows

Pick the command that matches your system. The installer asks which providers to add. You can also install with Homebrew, then run setup.

macOS or Linux: use the curl installer
Windows: use the PowerShell installer
Homebrew: install, then run archon setup

curl -fsSL https://archon.diy/install | bash
irm https://archon.diy/install.ps1 | iex
brew install coleam00/archon/archon

Run your first workflow in a repository

Change into your project, list the workflows Archon can see, then run one with a request in quotes. The example workflow archon-investigate looks into a question about your code.

Repository runs get their own git worktree by default, so several runs can work on one repository at once.

cd your-project
archon workflow list
archon workflow run archon-investigate "Why does the login test fail?"

Understand how a workflow is written

A workflow is a YAML file saved in your repository's .archon/workflows/ folder. It is a graph of nodes. A node can be an agent prompt, a bash command, a script, a loop, a wait for a person or a child workflow. Nodes declare what they depend on with depends_on, so the order is fixed by you.

A loop node can run an agent repeatedly until a command succeeds, using until_bash. A wait node pauses the run and asks you for a decision. A when condition lets a later node run only for a given answer.

Put the file in .archon/workflows/, for example build-feature.yaml
Use depends_on to set the order of steps
Use until_bash with your own test command to decide when a loop is done
Use wait with form: approval to stop for a human decision

name: build-feature
description: Plan, implement until the tests pass, ask for approval, open the PR.
nodes:
  - id: plan
    prompt: "Read the request and the code. Write an implementation plan."
  - id: implement
    depends_on: [plan]
    loop:
      prompt: "Implement the next step of the plan."
      until_bash: "bun run test"
      max_iterations: 10
      fresh_context: true
  - id: approve
    depends_on: [implement]
    wait:
      attention: "Review the change. Approve, or reject to stop."
      form: approval

Answer runs that need a decision

When a run reaches a wait node, it pauses and creates one attention item. The item says what the decision is, why it matters, a recommendation and the choices. You answer and the run carries on. You can watch runs and answer questions in the web console, or from the terminal.

The README says every run keeps an event log and transcript, and records the cost of each run, stored in your own database. The default database is SQLite; PostgreSQL is also supported.

Web console: run archon serve, then open the console in your browser
Terminal: run archon workflow attention

archon serve
archon workflow attention

Let your coding agent drive Archon

You can add Archon's skill to a project so your coding agent can start runs for you. Ask it in plain language, for example to use Archon to fix a numbered issue. Review what it starts, because runs can open pull requests and change your repository.

Run archon skill add inside your project
Then ask the agent to use Archon on a specific task

archon skill add

What people use it for

Make every AI-assisted bug fix follow the same plan, test and review steps
Run an approval gate so a person signs off before a pull request is opened
Keep a record of each run's events, transcript and cost in your own database
Automate a non-software process, such as content production or research, using the same YAML engine

Frequently asked questions

Is Archon free to use?

Archon is released under the MIT licence, which is an open-source licence. The README does not list prices, but you still need your own Claude Code or Codex setup, which has its own terms.

What do I need before installing Archon?

You need Claude Code or Codex installed and signed in, and Git. The README describes the agents as required, so Archon cannot run without one of them.

How do I install Archon on Windows?

Run the PowerShell command irm https://archon.diy/install.ps1 | iex. The README also lists a Homebrew route for macOS and Linux users.

Is Archon a chat-style coding assistant?

No. The README describes Archon as a workflow engine that runs your YAML process with AI agents, scripts and your decisions. It needs configuration, so it is not a single chat window with no setup.

Does Archon need a hosted service?

No. The README describes Archon as self-hosted, installed on your own machine or server, with SQLite by default and PostgreSQL as an option.

How does Archon compare with Aider, OpenHands, Cline or Continue?

Those tools are listed as comparable projects. Archon's distinguishing focus, according to its README, is running a fixed, repeatable YAML workflow with approval gates and a record of each run, on top of Claude Code, Codex or Pi.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Archon suits developers and repository owners who want AI coding runs to follow the same plan, test and review steps, with approval gates and a record of every run. It is a poor fit if you want a simple chat assistant with no setup, or if you cannot let automated runs open pull requests in your repository.

Install options & downloads