kilroy v0.1.0

Kilroy v0.1.0

Kilroy is a local-first Go CLI for running agentic software-factory pipelines in a Git repository. You describe work in English or write a Graphviz DOT graph by hand; Kilroy validates the graph, executes each stage with a real coding-agent (Claude, Codex, or Gemini), checkpoints after every node, and records the run history in CXDB. Each completed node becomes a git commit on a run branch, so the full execution trace is a diff-readable history. It's aimed at developers who want to automate multi-step engineering tasks — code generation, testing, review — with any of the major LLM providers, with resume and observability baked in.

Highlights

• Graphviz DOT pipelines — describe workflows as directed graphs; Kilroy handles the rest
• Multi-provider — OpenAI, Anthropic, and Google via CLI or API; Kimi, ZAI, Cerebras, Minimax, and Inception via API; zero-config auto-detection from env vars
• Checkpoint + resume — every node is checkpointed; interrupted runs resume from logs, CXDB, or git run-branch
• Git worktree isolation — each run executes in a throwaway worktree so the working tree is never touched
• Preflight mode — validate providers, probe endpoints, and verify graph semantics before spending a single token
• Detached runs — --detach daemonizes a run and writes a PID file so you can close your terminal
• Zero-config startup — provider backends auto-detected from ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY, etc.; no run.yaml required for simple cases

What's included

CLI

• kilroy attractor run — execute a pipeline; flags: --detach, --preflight/--validate/--test-run, --no-cxdb, --force-model provider=model, --allow-test-shim
• kilroy attractor resume — continue a stopped run from --logs-root, CXDB --context-id, or --run-branch
• kilroy attractor validate — lint a single graph or --batch multiple .dot files (text or --json output)
• kilroy attractor ingest — convert a natural-language requirement string into a .dot pipeline using the bundled create-dotfile skill
• kilroy attractor review — LLM-assisted graph review, outputs findings as text or JSON
• kilroy attractor status — inspect a running or finished run; supports --follow/-f, --watch, --json, --verbose
• kilroy attractor stop — graceful or forced shutdown of a detached run
• kilroy attractor runs list / prune — enumerate local run history, prune by date, graph name, label, or orphan status
• kilroy attractor serve — experimental HTTP+SSE server for remote pipeline submission and live progress streaming
• kilroy attractor modeldb suggest — query the embedded OpenRouter model catalog

Graph primitives

• start / exit (Mdiamond / Msquare shapes) — required entry and terminal nodes
• [shape=box] — codergen node; executes an LLM task with the full coding-agent loop
• conditional — routing node; evaluates edge conditions to select the next hop
• wait.human — blocks until an answer is provided (interactively or via serve API)
• parallel / parallel.fan_in — fan-out to concurrent branches, re-join at fan-in
• tool — executes a shell command directly, no LLM involved
• Per-node attributes: llm_provider, llm_model, max_tokens (default 32768), max_agent_turns, reasoning_effort
• Graph-level model_stylesheet — CSS-like selector rules for provider and model assignment across nodes

Providers

Provider	CLI backend	API backend	Notes
openai	codex exec --json	OpenAI Responses API	Full support
anthropic	claude -p --output-format stream-json	Anthropic Messages API	Full support
google	gemini -p --output-format stream-json --yolo	Google GenerateContent API	Full support
kimi	—	Anthropic Messages protocol	KIMI_API_KEY
zai	—	OpenAI Chat Completions	ZAI_API_KEY
cerebras	—	OpenAI Chat Completions	CEREBRAS_API_KEY
minimax	—	OpenAI Chat Completions	MINIMAX_API_KEY
inception	—	OpenAI Chat Completions	INCEPTION_API_KEY

Inspection and status

• attractor status --logs-root <dir> [--follow] — live tail of stage output during a run
• attractor runs list [--json] — table of all local runs with status and timestamps
• attractor runs prune — garbage-collect old run artifacts by date, graph name, or label
• attractor serve — REST API with SSE stream, human-gate answer endpoint, pipeline cancel
• CXDB integration — typed run events (run started, stage finished, checkpoint, complete/failed) and artifact blobs are written to CXDB for replay and recovery; autostart scripts included for Docker-based CXDB

Provenance

Kilroy is a concrete Go implementation of the StrongDM Attractor specification — an open-source agentic workflow model published at github.com/strongdm/attractor. The Attractor spec defines the DOT-graph pipeline model, the coding-agent loop, edge conditions and retry semantics, and the Unified LLM interface that Kilroy implements. The spec documents live in docs/strongdm/attractor/ and are the authoritative design reference for the engine. Kilroy is a sibling project to Freshell, the agentic terminal IDE, by the same author.

Quick start

# Install — from source, or grab a prebuilt binary from the Releases page
go install github.com/danshapiro/kilroy/cmd/kilroy@latest

# Set an API key — kilroy auto-detects the provider from your environment
export ANTHROPIC_API_KEY=sk-ant-...   # or OPENAI_API_KEY / GEMINI_API_KEY

# Generate a pipeline from a plain-English requirement
kilroy attractor ingest -o hello.dot "Write a hello_world.py script and run it"

# Validate the graph
kilroy attractor validate --graph hello.dot

# Run it — provider auto-detected from env, CXDB skipped for simplicity
kilroy attractor run --graph hello.dot --no-cxdb

On success, stdout prints run_id=, logs_root=, worktree=, and run_branch=. The working tree is untouched; all execution happens in an isolated worktree.

Note: Production use with CXDB (for resume, run history, and artifact storage) requires a run.yaml config file pointing at a running CXDB instance. See README.md for the full config reference and scripts/start-cxdb.sh for a Docker-based setup.

Known limitations

• CXDB is a real dependency — resume-from-CXDB, artifact blobs, and the full run timeline require a running CXDB service. The included Docker scripts help, but there's no single-binary path to zero-setup CXDB yet.
• CLI providers require external binaries — openai CLI mode needs codex installed; anthropic needs claude; google needs gemini. Missing binaries fail at preflight.
• API-only providers have no CLI fallback — Kimi, ZAI, Cerebras, Minimax, and Inception work only via their HTTP APIs; no CLI backend is available.
• attractor serve is experimental — the HTTP/SSE server has no authentication and no stability guarantee; do not expose to untrusted networks.
• Windows is untested for CLI providers — goreleaser produces Windows binaries, but the codex/claude/gemini CLI invocations are not exercised on Windows in CI.
• run.yaml still required for full production setups — zero-config startup handles provider detection, but CXDB addresses and modeldb paths need explicit config for reliable runs.
• --detach has no built-in log tail — use kilroy attractor status --logs-root <dir> --follow in a separate terminal to watch a detached run.
• Model catalog is pinned — the embedded OpenRouter model list is a snapshot; run kilroy attractor modeldb suggest --refresh to fetch a fresh copy.

Credits

Built by Dan Shapiro, with contributions from Matt Leaverton, Matt Van Horn, Vadim Comanescu, Jonathan Park, Chad Woolley, Lee Gonzales, Brian Feucht, Justin Choo, and Michael Bernstein.