agents CLAUDE.md

CLAUDE.md

Project Overview

agents is a self-hosted Go daemon that dispatches AI CLIs (Claude, Codex) to work on GitHub repos. The fleet lives in SQLite and is managed through the dashboard, REST, MCP, or YAML import/export; YAML is a portable strategy format, not the only configuration path. Agents are bound to repos via labels, GitHub event subscriptions (event-driven), and/or cron schedules (autonomous). GitHub operations happen through the AI backend inside a fresh runner container: GitHub MCP tools are preferred, with gh available as fallback for complex local checkout/test/PR loops. The daemon itself is read-only against GitHub. The daemon also ships a built-in Anthropic↔OpenAI translation proxy so the claude CLI can be routed through any OpenAI-compatible backend (local llama.cpp, hosted Qwen, vLLM, etc.), see docs/local-models.md. Agents can additionally invoke each other at runtime via the reactive inter-agent dispatcher (see Architecture Notes).

Directory Structure

cmd/agents/main.go          # Daemon entry point + --db / legacy --import flags
internal/
  fleet/                    # Domain entities: Workspace, Agent, Prompt, Skill, Guardrail, Repo, Backend, Binding (zero deps)
  config/                   # Normalized runtime config types, YAML parsing, defaults, validation (uses fleet)
  ai/                       # Prompt composition + command-based CLI runner (per-backend env)
  anthropic_proxy/          # Built-in Anthropic↔OpenAI Chat Completions translation proxy
  observe/                  # Observability store: events, traces, dispatch graph, SSE hubs; run attribution resolution including artifact-chain walk (attribution.go, attribution_artifacts.go)
  scheduler/                # Cron scheduler + agent memory (SQLite-backed)
  runtime/                  # Runner interface + ContainerSpec/ExitStatus types, Docker implementation, per-backend container setup (env, scripts, paths)
  backends/                 # Backend discovery: CLI probing, GitHub MCP health checks, tool diagnostics, orphan detection
  service/                  # Mutable fleet/config use cases shared by REST and MCP; owns use-case validation and transaction orchestration
  store/                    # SQLite persistence boundary: migrations, config import/load, tx-aware primitives, DB-level safety checks
  workflow/                 # Event routing engine, durable event queue (persist-on-push + replay), processor, dispatcher
  daemon/                   # Daemon as a single composed unit: lifecycle, router, /status, /run, proxy + UI + MCP mounts
  daemon/observe/           # Observability HTTP handlers (events, traces, graph, dispatches, memory, SSE)
  daemon/config/            # /config snapshot, /export, /import HTTP handlers and methods; token budget CRUD and leaderboard endpoints
  daemon/fleet/             # Agents/skills/backends CRUD + GET /agents fleet view + orphans (incl. /agents/orphans/status)
  daemon/repos/             # Repos + per-binding HTTP CRUD handlers and methods
  daemon/runners/           # /runners listing + delete + retry (event_queue × traces JOIN; in-flight + completed runs)
  webhook/                  # GitHub webhook receiver only: HMAC verification, delivery dedupe, /webhooks/github event parsing
  mcp/                      # MCP server exposing fleet-management tools at /mcp
  ui/                       # Embedded Next.js web dashboard (served at /ui/)
  logging/                  # zerolog setup
docs/                       # Long-form docs: quickstart, configuration, events, dispatch, API, local-models, security