Skip to content

Architecture

Archon is a Bun and TypeScript monorepo. A small set of packages carries the engine and its contracts; the server, CLI, console and integrations compose around them.

  • Contracts. provider-contract, chat-contract and plugin-manifest define how providers, chat platforms, forges and workflow packs attach. forge owns the forge seam.
  • Engine. workflows loads, validates and runs workflow graphs, records events through a store contract, and pauses runs durably. It reaches providers and persistence only through injected dependencies.
  • Isolation. isolation provides git worktrees for repo projects, and in-place and container execution backends.
  • Host. core owns the database, conversations, the chat orchestrator and workflow operations. server serves the API, webhooks and the console; cli is the archon command.
  • Integrations. providers holds the maintained Claude, Codex and Pi providers and the deprecated bundled OpenCode and Copilot providers. adapters holds the bundled chat and forge integrations; chat-slack is the maintained Slack chat plugin, installed with archon plugin add. New integrations ship as plugins.

The maintained map, with each package’s ownership, the main flows, extension points and the checks that enforce each boundary, is .archon/architecture.md in the repository. It is kept beside the code, and CI checks declared package dependencies against the linked layering policy.

Fresh --branch runs first reuse a healthy active task worktree registered in Archon for the project and branch, regardless of its path. If no healthy active task registration was reused, the provider can reuse a usable checkout at the configured target path; a holder at another path produces branch_checked_out, whether or not it is registered in Archon. Before detaching or removing the named holder, check whether a live Archon run still needs it and preserve its changes once it is safe to proceed. Exact-branch continuation can also adopt a Git-registered holder at another path. Reuse emits a worktree_adopted warning and records adoption provenance; it does not grant cleanup ownership. The shared store recipe owns registration and guarded adoption. The worktree provider creates checkouts. The isolation resolver selects worktrees. The resolver and launch helper call the store recipe.