Configuration file

The canonical file is .agentflow/config.yaml, created by agentflow init from config.yaml.example. Unless a path is absolute, AgentFlow resolves it from the repository root. For machine-readable validation, the generated JSON Schema lives at /schemas/config.schema.json on the docs site.

The sections that follow mirror the file layout: each block controls a slice of behavior (intent, work defaults, sources, persistence, agents, validation, models, cost, routing, UI, MCP, and repo policies).

project

project carries a human-facing name and the default branch AgentFlow uses for worktree-oriented flows.

project:
  name: my-project
  default_branch: main

intent

The intent block configures natural-language resolution for work and continue (application/internal/intent): whether the resolver runs, which mode it uses, and how it behaves when confidence is low or Ollama is available as a fallback.

intent:
  enabled: true
  default_mode: guided   # guided | auto
  resolver:
    use_ollama_fallback: true
    min_confidence: 0.75
    ask_when_below_confidence: true

work

work sets repo-wide defaults for orchestration: which agents run which roles, where the pipeline stops, verification and review toggles, task limits, and whether plan confirmation is required.

work:
  default_agent: cursor
  default_reviewer: codex
  default_enricher: ollama
  stop_after: report
  auto_verify: true
  auto_review: false
  max_tasks_per_run: 1
  require_plan_confirmation: true

sources

Local sources scan fixed paths for specs and active handoff material; Notion is optional and pulls snapshots into the tree. The table summarizes the two blocks; the YAML shows typical paths and Notion placeholders.

sources:
  local:
    enabled: true
    paths:
      - .agentflow/specs
      - .kiro/specs
      - docs/ai/active
  notion:
    enabled: false
    token_env: NOTION_TOKEN
    specs_database_id: ""
    import_path: .agentflow/specs

specs, state, worktrees

These blocks wire Kiro-style spec paths, SQLite state, and worktree layout. cleanup_policy controls what happens when a run leaves debris under worktrees.base_path.

specs:
  kiro_path: .kiro/specs
  active_spec_path: docs/ai/active/current-spec.md
  handoff_path: docs/ai/active/handoff.md

state:
  backend: sqlite
  path: .agentflow/state.sqlite

worktrees:
  base_path: .agentflow/worktrees
  branch_prefix: agentflow
  cleanup_policy: keep_failed

agents

Map logical agent ids to subprocess commands and agent-specific options. The dedicated page walks through fields and examples: Agents configuration.

validation

validation.commands lists checks the pipeline can require (tests, linters, custom scripts). Go repositories often get sensible defaults from bootstrap when go.mod exists.

validation:
  commands:
    - name: tests
      command: go test ./...
      required: true

models

models holds logical profiles for routing and cost (specv3). Keys are arbitrary ids; each entry ties a provider, cost class, model name, and which step classes may use it.

models:
  ollama_local_qwen:
    provider: ollama
    class: local
    model: qwen2.5-coder:14b
    input_cost_per_1m_tokens: 0
    output_cost_per_1m_tokens: 0
    usage: [summarize, classify, pre_review, context_selection]

budgets

Per-run, per-task, and daily caps live under budgets. See Budgets.

pricing

Cloud and local marginal rates come from your YAML — there are no hardcoded cloud prices in code. Keep updated_at honest so you know when someone last aligned numbers with a price list.

pricing:
  currency: EUR
  models:
    gemini-3-flash-preview:
      input_per_1m_tokens: 0.00
      output_per_1m_tokens: 0.00
      source: manual
      updated_at: "2026-05-17"

token_estimation

Token counts for budgeting use character-per-token heuristics (application/internal/cost/token_counter.go). Tuning these ratios nudges estimates closer to how your content looks (code-heavy versus prose-heavy).

token_estimation:
  default_chars_per_token: 4.0
  code_chars_per_token: 3.2
  markdown_chars_per_token: 4.2
  json_chars_per_token: 3.6

routing

Step classes map to local versus cloud agents through routing. Details: Routing.

ui

Terminal behavior is configured under ui (application/internal/tui): rendering mode, live logs, progress bars, and compact output.

ui:
  mode: auto      # auto | rich | plain | json
  live_logs: true
  progress_bars: true
  compact: false

mcp

When mcp.enabled is true, AgentFlow can run a local stdio MCP server with tool timeouts, output limits, investigation caps, and paths that investigation tooling must not read.

mcp:
  enabled: false
  max_output_bytes: 1048576
  command_timeout_seconds: 120
  secret_path_denylist: [".env", "credentials.json", "id_rsa"]
  investigation:
    large_file_bytes: 524288
    max_grep_output_bytes: 262144
    command_timeout_seconds: 120
    sensitive_globs: ["*.pem", ".git/*"]

policies

policies encodes guardrails at repo level: clean git, secret file patterns, changed-file limits, network allowance, and labels that require human approval before certain classes of change proceed.

policies:
  require_clean_git: true
  forbid_untracked_secret_files: true
  max_files_changed_per_task: 20
  allow_network: false
  require_human_approval_for:
    - database_migration
    - security_sensitive_change
    - dependency_upgrade

Validate changes

After you edit YAML, agentflow doctor is the fast sanity check before you run work against real agents.

agentflow doctor