DOCSEARCHbyAlgolia
Submit Docs

Archon Workflow Engine

repository·dev·Indexed 12 days ago

https://github.com/coleam00/archon

A workflow engine for AI coding agents that transforms non-deterministic AI interactions into repeatable, structured development processes using YAML-defined workflows. Version 0.8.0 includes support for community chat and forge adapters, a visual workflow builder, and a core framework for implementing platform-specific integrations.

Tokens
235.8K
Snippets
664
Records
948
Agent score
97%

What's inside Archon

  1. Overview of Archon Platform Adapters

    dev

    Archon uses platform adapters to connect to different communication channels. These adapters allow you to trigger workflows and interact with AI agents from various platforms. Adapters handle message ingestion, response delivery (streaming or batching), authorization (via user whitelists), and conversation tracking by mapping platform identifiers (like thread IDs or issue numbers) to Archon conversations.

    Multiple adapters can run simultaneously. An adapter will start automatically when the Archon server is launched, provided all its required environment variables are configured.

  2. What is Archon?

    dev

    Archon is an AI workflow engine designed for coding agents. It allows you to package multi-step development workflows (such as code reviews, bug fixes, feature implementation, and testing) as YAML files.

    Key capabilities include:

    • Repeatable: Package AI coding patterns as shareable YAML workflows.
    • Isolated: Each workflow runs in its own git worktree to prevent conflicts.
    • Portable: Execute workflows via CLI, Web UI, Slack, Telegram, GitHub, or Discord.
    • Composable: Chain nodes into Directed Acyclic Graphs (DAGs) using dependencies, loops, and conditional logic.
    • Multi-provider: Supports Claude Code SDK, Codex SDK, and local models via Pi.

  3. Common use cases for Archon workflows

    dev

    Archon is designed to automate standard development lifecycle tasks. You can use built-in workflows or create custom ones for tasks such as:

    • Fixing GitHub issues: Automating investigation, implementation, validation, and PR creation.
    • Feature development: Moving from a high-level idea/description to a working, reviewed PR.
    • Pull Request reviews: Performing multi-perspective code reviews with structured feedback.
    • Codebase Q&A: Getting contextually-aware answers about your repository.
    • Merge conflict resolution: Analyzing and fixing conflicts using full repository context.

  5. Design and implementation map for Agent Chat (console)

    dev

    This document outlines the architectural plan for adding a project-scoped AI 'agent chat' to the Archon console. The chat is designed as a peer view to the 'Run' view, accessible via a tab swap under each project.

    Key Design Principles:

    • Project-scoped: The chat is tied to a specific project context.
    • Run-management focus: The agent's primary purpose is to run, track, and manage workflow runs using tools.
    • Simplified State Model: Unlike previous chat implementations that used complex client-side state machines for streaming, the console model uses an "invalidate $\rightarrow$ refetch" pattern. Server-Sent Events (SSE) trigger invalidation of the message cache, causing a refetch of the authoritative state from the server.
    • Tooling: A general manage_run tool is planned, supporting both MCP (Claude/Codex/OpenCode) and Pi customTools backends.

  6. Access Archon technical reference documentation

    dev

    Archon provides comprehensive technical documentation covering its architecture, CLI, database schema, and configuration. Developers can access specific reference sections for:

    • Architecture: System overview, interfaces, data flow, and extension guides.
    • Archon Directories: Directory structure, path resolution, and the configuration system.
    • CLI Reference: All CLI commands, flags, and usage examples.
    • Commands Reference: Slash commands available across all platform adapters.
    • Variables Reference: Variable substitution in commands and workflows (e.g., $ARGUMENTS, $BASE_BRANCH).
    • API Reference: REST API endpoints for programmatic access.
    • Database: Schema details, migrations, and SQLite/PostgreSQL setup.
    • Configuration Reference: Full config.yaml options, environment variables, and streaming modes.
    • Security: Permission model, authorization, webhook verification, and data privacy.
    • Troubleshooting: Common issues and solutions.

  7. Navigate the Web UI Layout

    dev

    The Web UI is a dark-themed single-page application organized into four main areas:

    • Left Sidebar: Contains the Conversations list (searchable/grouped by project), the Project selector (to scope workflows to specific codebases), and the Workflow invoker (a quick-launch panel to run workflows immediately).
    • Main Chat Area: The central interface for interacting with the AI assistant via natural language, slash commands, or workflow triggers.
    • Command Center (Dashboard): Accessible via /legacy/dashboard. It provides a high-level view of all workflow runs, including status summaries, run cards with progress/actions (Resume, Cancel, etc.), and a history table.
    • Settings: Accessible via /legacy/settings. Allows configuration of assistant defaults (model, provider) and management of registered projects.

  8. What is an Archon Workflow?

    dev

    An Archon workflow is a YAML file that defines a Directed Acyclic Graph (DAG) of commands to execute. Workflows allow you to orchestrate multi-step automation by chaining AI agents, running independent nodes in parallel, using conditional branching based on node outputs, and passing artifacts between nodes.

    Workflows are built using commands, so you should review Authoring Commands before creating workflows.

    Core Capabilities

    • Multi-step automation: Chain multiple commands together.
    • Parallel execution: Nodes without dependencies run concurrently.
    • Conditional branching: Use the when: key to route execution based on previous node outputs.
    • Artifact passing: Downstream nodes can access the output of upstream nodes.
    • Iterative loops: Repeat nodes until a completion signal is received.
    name: fix-github-issue
description: Investigate and fix a GitHub issue end-to-end

nodes:
  - id: investigate
    command: investigate-issue

  - id: implement
    command: implement-issue
    depends_on: [investigate]
    context: fresh

  9. What is a Command in Archon?

    dev

    A Command is a markdown file that serves as a prompt template for an AI agent within an Archon workflow. When a workflow step calls a command (e.g., - command: investigate-issue), Archon loads the file, substitutes variables (like $ARGUMENTS), and sends the document to the AI as a set of instructions.

    Key Concept: Commands are prompts, not code. They guide AI behavior through natural language instructions rather than executable logic.

    # Command Name

**Input**: $ARGUMENTS

---

[Instructions for the AI agent...]

  10. What is an Archon command?

    dev

    An Archon command is a markdown file that serves as a focused prompt for the AI to execute a single, atomic task. Commands are not code; they are instructions written in plain markdown that the AI interprets to perform work like investigating issues, writing code, or running tests.

    Location

    Commands must be stored in the .archon/commands/ directory of your repository. Archon automatically discovers any files in this directory alongside its own bundled default commands.

  11. Reference previous iteration data with `$LOOP_PREV`

    dev

    A body node within a loop_group can access the output of a sibling node from the immediately preceding iteration using the $LOOP_PREV prefix.

    • Syntax: $LOOP_PREV.<nodeId>.output
    • For structured data: $LOOP_PREV.<nodeId>.output.<field>

    Important Constraints:

    • On iteration 1, all $LOOP_PREV.* references resolve to an empty string.
    • $LOOP_PREV.* references resolve to an empty string when resuming from an interactive pause/gate.
    • You cannot access historical iterations beyond the immediately prior one (no history indexing).
    nodes:
  - id: fix-loop
    loop_group:
      until: TESTS_PASS
      max_iterations: 5
      nodes:
        - id: implement
          prompt: |
            Previous attempt's test output:
            $LOOP_PREV.test.output
            Fix what failed.
          depends_on: []
        - id: test
          bash: bun test
          depends_on: [implement]

  12. Understand the Archon Console (Spike) mental model

    dev

    The Archon Console is a greenfield web UI experiment built around four core primitives. All user-facing copy and navigation are strictly limited to these terms to maintain a consistent vocabulary:

    • Project
    • Run
    • Workflow
    • Worktree

    Note: Terms like Dashboard, Deployment, Infrastructure, Secrets, Activity, Pipeline, or Stage are not used in the Console UI.