Configuration file

The canonical file is .asagiri/config.yaml, created by asa init from config.yaml.example. Unless a path is absolute, Asagiri 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 Asagiri uses for worktree-oriented flows.

project:
  name: my-project
  default_branch: main

runtime

Persistent engineering runtime (spec-my-A §24.17). Modes: guided, interactive, headless, ci, review, exploration.

runtime:
  mode: guided
  api:
    port: 8765
    socket: .asagiri/runtime/runtime.sock

See Runtime commands and runtime serve.

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:
      - .asagiri/specs
      - .kiro/specs
      - docs/ai/active
  notion:
    enabled: false
    token_env: NOTION_TOKEN
    specs_database_id: ""
    import_path: .asagiri/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: .asagiri/state.sqlite

worktrees:
  base_path: .asagiri/worktrees
  branch_prefix: asa
  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

verification

Trust & verification gates (spec-my-B §19). Profiles define minimum confidence per dimension and checks that must pass before delivery or CI promotion.

verification:
  default_profile: production
  gates:
    production:
      min_confidence:
        architecture: 0.8
        implementation: 0.75
        security: 0.85
      required_checks:
        - contracts
        - flows
        - observability
        - security

• default_profile — gate set used by asa trust gates and asa verify trust --ci
• min_confidence — blocking thresholds on aggregated dimension scores (0.0–1.0)
• required_checks — check type ids from the trust registry (e.g. contracts, flows, security)

See Trust engine, asa verify trust, and asa trust gates.

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, Asagiri 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, asa doctor is the fast sanity check before you run work against real agents.

asa doctor