config.yml schema

Every project has a config.yml at its root. Created by init, edited by the user, committed to git.

Full schema

# Required
name: my-handbook                # slug; must match the folder name
description: "Internal team handbook for the support org"

# Demo questions — dual-purpose:
#   1) `build` runs each one through the full chat pipeline as a
#      smoke test (disable with `build --no-smoke-test`).
#   2) The dashboard surfaces them as suggested prompts after `import`.
# Travel with the share zip.
demo:
  - "What's our return policy?"
  - "Who's on call this week?"
  - "How do I file an expense report?"

# Wiki generator backend. v1 ships only `local`. v2 adds claude-code/codex/command.
wiki:
  generator: local

# Commands that produce input for the LLM to turn into wiki articles.
# Each entry produces exactly one wiki article named after `name`.
commands:
  - name: github-issues
    description: "Open GitHub issues across our team's repos"
    run: gh issue list --repo OWNER/REPO --state open --json number,title,body

  - name: oncall
    description: "Current PagerDuty on-call rotation"
    run: pd oncall --json

# RAG knobs (optional; defaults shown)
rag:
  enabled: true
  chunk_tokens: 400
  top_k: 8
  graph_threshold: 0.75
  graph_hops: 2

# Optional model override (advanced — normally inherits machine default)
# model:
#   id: gemma-4-e4b-q4_k_m

# LLM-as-judge eval (dev-time only; requires internet + API key).
eval:
  generator: claude               # claude | openai | command
  generator_model: claude-sonnet-4-7
  judge: claude
  judge_model: claude-opus-4-7
  count: 20
  pass_threshold: 7.0

Validation rules

local-agents doctor and local-agents init enforce all of:

• name required; must equal the folder name (slug-cased).
• description required; used by the dashboard and the share manifest.
• commands[].name unique within the project and slug-cased.
• commands[].run is a shell command — exec'd via sh -c (or cmd.exe /c on Windows). No sandbox: trust the project author.
• demo is optional but recommended.
• wiki.generator must be local in v1.

Slug rule

name must match ^[a-z][a-z0-9]*(-[a-z0-9]+)*$. The project package exports Slugify (idempotent) and IsSlug for callers that need to normalize user input.

Init-time template

local-agents init writes a starter config.yml with commented-out examples for common platforms (gh, acli, az, kubectl, psql, curl). The user uncomments and edits. There's no platform-specific Go code — just example shell commands.

Full spec

spec 03 on GitHub →