How coleam00/archon works
Purpose and Entry Points
Archon is a Bun/TypeScript monorepo for deterministic AI-coding workflows: YAML-defined DAGs combine AI-agent prompts with bash, scripts, loops, approvals, and Git operations. Primary user entry points are the CLI (packages/cli/src/cli.ts), HTTP server (packages/server/src/index.ts), and React dashboard (packages/web/src/main.tsx). Project-local workflow assets live under .archon/workflows/ and .archon/commands/.
Interaction and Adapter Boundary
Inputs arrive from CLI, web, and chat/forge integrations, normalized behind adapter packages before reaching core orchestration. The server exposes REST/webhook routes and bridges persisted workflow updates to the web transport; chat adapters translate Slack, Telegram, Discord, GitHub, Gitea, and GitLab semantics.
• packages/adapters/src/index.ts
• packages/server/src/routes/api.ts
• packages/server/src/routes/webhooks.ts
Core Orchestration
The core orchestrator owns conversation context, session lifecycle, prompt construction, command dispatch, agent invocation, and message delivery. It is the central control boundary: adapters should not directly manage provider processes or workflow state.
• packages/core/src/orchestrator/orchestrator.ts
• packages/core/src/orchestrator/prompt-builder.ts
• packages/core/src/handlers/command-handler.ts
Workflow Definition, Planning, and Execution
Workflow YAML is discovered from bundled, global, and repository locations; repository definitions can override defaults. Loader/validator stages expand includes, validate schemas and requirements, resolve node models/inputs/output references, then execute a dependency DAG with conditions, retries, subruns, loops, approvals, deterministic nodes, and emitted events.
• packages/workflows/src/loader.ts
• packages/workflows/src/validator.ts
• packages/workflows/src/dag-executor.ts
Bundled process templates are concrete product behavior, not merely examples: .archon/workflows/defaults/archon-idea-to-pr.yaml, .archon/workflows/defaults/archon-fix-github-issue.yaml, and corresponding reusable prompt commands in .archon/commands/defaults/.
AI Provider Runtime
A provider registry abstracts assistant-specific launch, configuration, capabilities, session continuation, native tools, MCP, structured output, and OAuth. Supported first-party implementations include Claude and Codex; community providers include Copilot, OpenCode, and Pi. Providers are typically local CLI/runtime integrations, while models and credentials are external services.
• packages/providers/src/registry.ts
• packages/providers/src/claude/provider.ts
• packages/providers/src/codex/provider.ts
Isolation and Git Boundary
Each run can execute against an isolated checkout. Isolation selects in-place or container backends and worktree providers; Git operations provide repository/branch/forge primitives. This boundary prevents concurrent workflow runs from modifying the same working tree and contains agent command execution.
• packages/isolation/src/backend-router.ts
• packages/isolation/src/providers/worktree.ts
• packages/git/src/worktree.ts
Docker-based execution is supported through packages/isolation/docker/runner.Dockerfile; deployment uses docker-compose.yml and Dockerfile.
Persistence, Identity, and Operations
Core persistence supports SQLite and PostgreSQL, recording codebases, conversations, messages, sessions, isolation environments, workflow runs/events, node sessions, and encrypted/provider credentials. Migrations define the durable compatibility contract. Server auth and GitHub-auth bootstrapping establish multi-user and external-forge boundaries.
• packages/core/src/db/connection.ts
• packages/core/src/db/workflows.ts
• migrations/000_combined.sql
• packages/server/src/auth/instance.ts
• packages/server/src/github-auth-bootstrap.ts
The dashboard consumes APIs and live run/event streams to provide chat, monitoring, workflow execution views, and visual authoring; it remains a client of server/core rather than an execution authority.
• packages/web/src/App.tsx
• packages/web/src/components/workflows/WorkflowExecution.tsx
• packages/web/src/components/workflows/WorkflowBuilder.tsx
Main entry points: orchestrator.ts Orchestrator · dag-executor.ts DAG Executor · api.ts API Routes · registry.ts Provider Registry
Components 22
Entry & Integration
- CLI · Primary local user entry point.
packages/cli/src/cli.ts - HTTP Server · Serves APIs, webhooks, authentication, and live updates.
packages/server/src/index.ts - Dashboard · Chat, run monitoring, execution, and workflow authoring UI.
packages/web/src/main.tsx - API Routes
packages/server/src/routes/api.ts - Webhook Routes
packages/server/src/routes/webhooks.ts - Integration Adapters · Normalizes Slack, Telegram, Discord, and forge semantics.
packages/adapters/src/index.ts
Core Control
- Orchestrator · Owns sessions, context, dispatch, agent invocation, and delivery.
packages/core/src/orchestrator/orchestrator.ts - Prompt Builder
packages/core/src/orchestrator/prompt-builder.ts - Command Handler
packages/core/src/handlers/command-handler.ts
Workflow Engine
- Workflow Loader · Finds layered YAML definitions and expands includes.
packages/workflows/src/loader.ts - Workflow Validator · Validates requirements and resolves node references, models, and inputs.
packages/workflows/src/validator.ts - DAG Executor · Runs dependency nodes, conditions, retries, loops, approvals, and subruns.
packages/workflows/src/dag-executor.ts - Bundled Workflows · Default idea-to-PR and issue-fix workflows are product behavior.
.archon/workflows/defaults/archon-idea-to-pr.yaml
Agent Execution
- Provider Registry · Selects providers and manages capabilities, sessions, tools, MCP, and OAuth.
packages/providers/src/registry.ts - Claude Provider
packages/providers/src/claude/provider.ts - Codex Provider
packages/providers/src/codex/provider.ts - Isolation Router · Selects in-place, container, and worktree execution backends.
packages/isolation/src/backend-router.ts - Git Worktrees · Provides isolated repository and branch checkouts.
packages/git/src/worktree.ts
State & Operations
- Core Persistence · Stores conversations, sessions, credentials, environments, workflow runs, and events.
packages/core/src/db/connection.ts - Workflow Run Store
packages/core/src/db/workflows.ts - Database Migrations
migrations/000_combined.sql - Server Auth
packages/server/src/auth/instance.ts
Connections 25
- CLI → Orchestrator: commands
- Dashboard → API Routes: REST and live streams
- HTTP Server → API Routes: hosts
- HTTP Server → Webhook Routes: hosts
- API Routes → Integration Adapters: normalizes input
- Webhook Routes → Integration Adapters: normalizes events
- Integration Adapters → Orchestrator: normalized interactions
- Orchestrator → Prompt Builder: builds prompts
- Orchestrator → Command Handler: dispatches commands
- Command Handler → Workflow Loader: starts workflows
- Bundled Workflows → Workflow Loader: default definitions
- Workflow Loader → Workflow Validator: loaded definitions
- Workflow Validator → DAG Executor: execution plan
- Orchestrator → Provider Registry: invokes agents
- Provider Registry → Claude Provider: selects
- Provider Registry → Codex Provider: selects
- DAG Executor → Provider Registry: AI nodes
- DAG Executor → Isolation Router: isolated runs
- Isolation Router → Git Worktrees: worktree backend
- Orchestrator → Core Persistence: sessions and messages
- DAG Executor → Workflow Run Store: runs and events
- Workflow Run Store → Core Persistence: uses
- Database Migrations → Core Persistence: defines schema
- HTTP Server → Server Auth: authenticates users
- API Routes → Workflow Run Store: run updates · Bridges persisted workflow updates to dashboard clients.