danshapiro/kilroy/using-kilroy

Using Kilroy

Kilroy is a local-first Attractor runner:

1. Generate a DOT pipeline from English requirements.
2. Validate DOT structure + semantics.
3. Run in an isolated git worktree with checkpoint commits.
4. Resume interrupted runs from logs, CXDB, or run branch.

If you only need to delegate a one-shot task to a single agent (investigation, research, a small code change you don't need to supervise live), use skills/quick-launch/ instead — it's the fire-and-forget workflow built on top of this command surface and handles tagging, detached launch, and result retrieval with one command each.

Command Surface

Use these exact command forms:

kilroy attractor run [--preflight|--test-run] [--detach] [--tmux] [--allow-test-shim] [--confirm-stale-build] [--no-cxdb] [--skip-cli-headless-warning] [--force-model <provider=model>] [--graph <file.dot>] [--package <dir>] [--config <run.yaml>] [--run-id <id>] [--logs-root <dir>] [--workspace <dir>] [--input <json-or-path>] [--prompt-file <path>] [--label KEY=VALUE]
kilroy attractor resume --logs-root <dir>
kilroy attractor resume --cxdb <http_base_url> --context-id <id>
kilroy attractor resume --run-branch <attractor/run/...> [--repo <path>]
kilroy attractor status [--logs-root <dir> | --latest] [--json] [--follow|-f] [--cxdb] [--raw] [--watch] [--interval <sec>]
kilroy attractor stop --logs-root <dir> [--grace-ms <ms>] [--force]
kilroy attractor runs list [--json] [--label KEY=VALUE] [--status STATUS] [--graph PATTERN] [--limit N]
kilroy attractor runs show (<id-or-prefix> | --latest [--label KEY=VALUE]) [--json] [--outputs] [--print <file>]
kilroy attractor runs wait (<id-or-prefix> | --latest [--label KEY=VALUE]) [--timeout <duration>] [--interval <duration>] [--json]
kilroy attractor runs prune [--before YYYY-MM-DD] [--older-than DURATION] [--graph PATTERN] [--label KEY=VALUE] [--orphans] [--dry-run | --yes]
kilroy attractor validate --graph <file.dot>
kilroy attractor ingest [--output <file.dot>] [--model <model>] [--skill <skill.md>] [--repo <path>] [--max-turns <n>] [--no-validate] <requirements>
kilroy attractor serve [--addr <host:port>]

Run flags you may not have seen before

• --package <dir> — load a workflow package (a directory with workflow.toml, graph.dot, scripts/, prompts/). Applies label defaults, validates inputs, materializes scripts into the worktree. Prefer packages over bare graphs for anything reusable.
• --tmux — execute each agent CLI invocation inside a detached tmux session. Required for headless runs that use the Claude/Codex/Gemini CLIs. Combine with --detach for fire-and-forget operation.
• --input <json-or-path> — structured inputs for the graph. Pass a JSON literal (--input '{"key":"value"}') or a path to a JSON/YAML file. Values become KILROY_INPUT_KEY env vars for tool nodes, $input.key placeholders in agent prompts, and sections in .kilroy/INPUT.md. Required inputs are declared via the graph's inputs="key1,key2" attribute.
• --prompt-file <path> — read the file contents verbatim and assign them to the prompt input key. Overrides any prompt already set via --input. Use this instead of inlining multi-line text in a JSON blob — no escaping, no quoting, no newline hazards.
• --no-cxdb — skip the content-addressed event store. Applied automatically when no --config is supplied (the default config doesn't set up cxdb). Explicit in production configs.
• --skip-cli-headless-warning — bypass the interactive CLI-backend confirmation prompt. Applied automatically when stdin isn't a terminal (detached runs, pipes, agent-driven invocations).
• --label KEY=VALUE — attach a label to the run. Repeatable. Labels are stored in the run DB and used by runs list --label and runs prune --label. Always tag detached runs so you can find them later.
• --workspace <dir> — override the workspace dir (default: cwd). If it's a git repo, the engine creates a dedicated run branch + worktree; otherwise it runs in plain-directory mode.

Workflow

1. Run ingest:

kilroy attractor ingest -o pipeline.dot "Build a Go CLI link checker"

1. Validate:

kilroy attractor validate --graph pipeline.dot

1. Create run config (run.yaml or run.json).

1. Run:

kilroy attractor run --graph pipeline.dot --config run.yaml

Optional preflight-only check (validates all preflights, no stage execution):

kilroy attractor run --graph pipeline.dot --config run.yaml --preflight

1. If interrupted, resume from the most convenient source:

kilroy attractor resume --logs-root <path>

1. For long runs, launch detached so work continues after shell/session exits:

./kilroy attractor run --detach --graph pipeline.dot --config run.yaml --run-id <run_id> --logs-root <logs_root>

1. Observe run health and preflight behavior:

./kilroy attractor status --logs-root <logs_root>
cat <logs_root>/preflight_report.json
tail -f <logs_root>/progress.ndjson

1. Intervene when a run is stuck or needs termination:

./kilroy attractor stop --logs-root <logs_root> --grace-ms 30000 --force

Runs: listing, inspecting, cleaning up

Every run (detached or foreground) is recorded in a local SQLite run database. Query it via kilroy attractor runs:

# All runs, newest first
kilroy attractor runs list
 
# Filter by label (repeatable tags on launch come back here)
kilroy attractor runs list --label task=investigate-gadfly
 
# Machine-readable
kilroy attractor runs list --json --status running --limit 10
 
# Full detail for one run (accepts unique prefix)
kilroy attractor runs show 01KP646Y
kilroy attractor runs show 01KP646Y --json
 
# Latest run matching a label (no id needed)
kilroy attractor runs show --latest --label task=investigate-gadfly
 
# List just the declared output files
kilroy attractor runs show 01KP646Y --outputs
 
# Stream a specific output file to stdout
kilroy attractor runs show 01KP646Y --print result.md
kilroy attractor runs show --latest --label task=investigate-gadfly --print result.md
 
# Block until a run reaches a terminal state
kilroy attractor runs wait 01KP646Y --timeout 10m
kilroy attractor runs wait --latest --label task=investigate-gadfly --timeout 10m
 
# Clean up old runs (dry-run by default; add --yes to actually delete)
kilroy attractor runs prune --older-than 7d
kilroy attractor runs prune --label experiment=true --yes

runs show output includes worktree_dir, repo_path, run_branch, and logs_root — use these to cd back into a finished run's workspace or feed them to other commands.

Ingest Details

• Uses Claude CLI (KILROY_CLAUDE_PATH override, default executable claude).
• Default model: claude-sonnet-4-5.
• Default repo: current working directory.
• Default skill path auto-detection: <repo>/skills/create-dotfile/SKILL.md, then binary-relative fallbacks (for example <kilroy-prefix>/share/kilroy/skills/create-dotfile/SKILL.md) and Go module-cache roots from binary build metadata.
• If no skill file exists, ingest fails fast.
• --max-turns defaults to 15 when omitted.
• Validation runs by default; use --no-validate to skip.

Validate Semantics

attractor validate runs parse + transforms + validators and fails on error-severity diagnostics.

Key checks:

• Exactly one start node and one exit node.
• Start has no incoming edges; exit has no outgoing edges.
• All nodes reachable from start.
• Edge conditions parse correctly.
• llm_provider required for codergen nodes (shape=box).
• model_stylesheet is optional, but if present must parse.

Run Config (version: 1)

Required fields:

• repo.path
• cxdb.binary_addr
• cxdb.http_base_url
• modeldb.openrouter_model_info_path

Defaults:

• git.run_branch_prefix: attractor/run
• modeldb.openrouter_model_info_update_policy: on_run_start
• modeldb.openrouter_model_info_url: https://openrouter.ai/api/v1/models
• modeldb.openrouter_model_info_fetch_timeout_ms: 5000

Minimal example:

version: 1
 
repo:
  path: /absolute/path/to/repo
 
cxdb:
  binary_addr: 127.0.0.1:9009
  http_base_url: http://127.0.0.1:9010
 
llm:
  providers:
    openai:
      backend: cli
    anthropic:
      backend: api
    google:
      backend: api
 
modeldb:
  openrouter_model_info_path: /absolute/path/to/openrouter_models.json
  openrouter_model_info_update_policy: on_run_start
  openrouter_model_info_url: https://openrouter.ai/api/v1/models
  openrouter_model_info_fetch_timeout_ms: 5000
 
git:
  require_clean: true
  run_branch_prefix: attractor/run
  commit_per_node: true

Notes:

• Provider keys accept openai, anthropic, google (gemini alias maps to google), kimi, zai, cerebras, and minimax.
• If a graph node uses provider P, llm.providers.P.backend must be set (api or cli).
• backend: cli is currently supported for openai, anthropic, and google (including the gemini alias).
• In v1 behavior, runs require a clean repo and checkpoint each node.
• Prefer first-class run config policy knobs over env tuning:
• runtime_policy for stage timeout, stall watchdog, and retry cap.
• preflight.prompt_probes for prompt-probe mode/transports/policy.

Provider Backends

CLI backend mappings:

• openai -> codex exec --json --sandbox workspace-write -m <model> -C <worktree>
• anthropic -> claude -p --dangerously-skip-permissions --output-format stream-json --verbose --model <model> "<prompt>"
• google -> gemini -p --output-format stream-json --yolo --model <model> "<prompt>"

CLI executable overrides:

• KILROY_CODEX_PATH
• KILROY_CLAUDE_PATH
• KILROY_GEMINI_PATH

API backend credentials:

• OpenAI: OPENAI_API_KEY (OPENAI_BASE_URL optional)
• Anthropic: ANTHROPIC_API_KEY (ANTHROPIC_BASE_URL optional)
• Google: GEMINI_API_KEY or GOOGLE_API_KEY (GEMINI_BASE_URL optional)
• Kimi: KIMI_API_KEY
• Z.ai: ZAI_API_KEY
• Cerebras: CEREBRAS_API_KEY
• MiniMax: MINIMAX_API_KEY

API protocol/base URL/path overrides are configured in llm.providers.<provider>.api in run config.

Run Output and Exit Codes

run and resume print:

• run_id
• logs_root
• worktree
• run_branch
• final_commit

Exit codes:

• 0: final status success (or validation success)
• 1: command failure, validation failure, or non-success final status

Artifacts

Run-level ({logs_root}) commonly includes:

• graph.dot
• manifest.json
• checkpoint.json
• final.json
• run_config.json
• modeldb/openrouter_models.json
• run.tgz
• worktree/

Stage-level ({logs_root}/{node_id}) commonly includes:

• prompt.md
• response.md
• status.json
• stage.tgz
• stdout.log, stderr.log
• events.ndjson, events.json
• cli_invocation.json, cli_timing.json
• api_request.json, api_response.json
• output_schema.json, output.json
• tool_invocation.json, tool_timing.json
• diff.patch

Exact files depend on handler/backend type.

Browser verification notes:

• Browser verify nodes emit tool_browser_artifacts events in {logs_root}/progress.ndjson.
• Collected browser files are stored in {logs_root}/{node_id}/browser_artifacts/; on retries, prior copies are preserved in {logs_root}/{node_id}/attempt_N/browser_artifacts/.

Status Contract for Codergen Nodes

For shape=box nodes:

• llm_provider and llm_model must resolve.
• If backend returns no explicit outcome, Kilroy expects a status.json signal.
• status.json may be written in worktree root; Kilroy copies it into stage directory.
• If auto_status=true, missing status.json becomes success; otherwise stage fails.

Canonical status.json shape:

{
  "status": "success",
  "preferred_label": "",
  "suggested_next_ids": [],
  "context_updates": {},
  "notes": "",
  "failure_reason": ""
}

Valid statuses: success, partial_success, retry, fail, skipped.

Resume Behavior