The problem every AI coder hits

You ask an AI coding agent to fix a bug. Sometimes it plans carefully, runs tests, and opens a polished pull request. Other times it skips right to editing files, breaks something else, and needs babysitting for an hour.

The same request, different outcomes. Why? Because AI agents improvise — they decide their own process each run. Archon's insight: what if the process was deterministic, even when the intelligence wasn't?

What happens when you use Archon

Imagine you type: "Use Archon to add dark mode to the settings page." Here's exactly what happens next:

The recipe that makes it all work

Here's an actual Archon workflow from the codebase. Notice how it reads almost like a to-do list — that's intentional:

nodes:
  - id: plan
    prompt: "Explore the codebase and create an implementation plan"

  - id: implement
    depends_on: [plan]
    loop:
      prompt: "Read the plan. Implement the next task."
      until: ALL_TASKS_COMPLETE

  - id: run-tests
    depends_on: [implement]
    bash: "bun run validate"
            

Check your understanding

Meet the players

Archon is organized as a monorepo — one repository, many packages. Think of it like a film production company: different departments (packages) each specialize in one thing, but they all work on the same film (your workflow).

Watch the components talk

When you trigger a workflow from the CLI, here's the conversation that happens between packages:

The file tree, demystified

Now that you know the cast, here's where each character lives on disk:

Match the package to its role

Two kinds of work

Think of a workflow like a factory assembly line. Some stations are robots — they do the same thing every time, perfectly, mechanically. Other stations are skilled craftspeople — they bring judgment and creativity, but their output varies. Archon lets you mix both.

Inside the workflow executor

This is from packages/workflows/src/executor.ts — the heart of Archon. It reads the workflow definition and decides what to run:

async executeNode(node: WorkflowNode, context: RunContext) {
  if (node.bash) {
    return await executeBash(node.bash, context);
  }
  if (node.prompt) {
    return await executePrompt(node.prompt, context);
  }
  if (node.loop) {
    return await executeLoop(node.loop, context);
  }
}
            

Watch a workflow execute step by step

Quiz: Workflows in practice

The message pipeline

When a prompt node runs, your workflow YAML isn't sent directly to Claude. It goes through several transformations — like a message passed through relay runners in a relay race, each one adding context or translating the format.

How the provider adapter works

The packages/providers/src/registry.ts file is where Archon figures out which AI service to call. It's like a phone switchboard — the same message can be routed to different destinations based on configuration.

export const PROVIDER_CATALOG: Record<string, ProviderDescriptor> = {
  'claude': { name: 'Claude', factory: createClaude },
  'codex':  { name: 'OpenAI Codex', factory: createCodex },
};

function getProvider(id: string): BaseProvider {
  const descriptor = PROVIDER_CATALOG[id];
  if (!descriptor) throw new Error(`Unknown provider: ${id}`);
  return descriptor.factory();
}
            

Where data lives

Archon stores everything in a database managed by @archon/core. Think of it as a filing cabinet with different drawers for different things:

Quiz: Tracing data through Archon

The four failure modes

When a workflow stops working, it's almost always one of these four things. Like a car that won't start — before calling a mechanic, you check fuel, battery, keys, and neutral. Archon has its own checklist.

Spot the bug: broken workflow

This workflow YAML has a real bug that would cause a node to run before its dependency is ready. Click the line you think is wrong:

Your debugging playbook

When a workflow fails, here's the exact sequence to follow:

Final quiz: Debugging Archon