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-contractandplugin-manifestdefine how providers, chat platforms, forges and workflow packs attach.forgeowns the forge seam. - Engine.
workflowsloads, 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.
isolationprovides git worktrees for repo projects, and in-place and container execution backends. - Host.
coreowns the database, conversations, the chat orchestrator and workflow operations.serverserves the API, webhooks and the console;cliis thearchoncommand. - Integrations.
providersholds the maintained Claude, Codex and Pi providers and the deprecated bundled OpenCode and Copilot providers.adaptersholds the bundled chat and forge integrations;chat-slackis the maintained Slack chat plugin, installed witharchon 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.
Related
Section titled “Related”- Build a community provider, including how native SDK events map to the provider contract
- Provider capabilities
- Forge operations
- Database
- Worktrees
