aster.yaml.example

# Aster config. Copy to `aster.yaml` in your repo root (or
# ~/.aster/aster.yaml for a global default). Every field is optional.
#
# Precedence: CLI flags > shell env > this file > built-in defaults.
# API keys are NEVER read from this file — use ASTER_API_KEY or `aster login`.
#
# Full reference, including defaults and how the two files merge:
# docs/CONFIG.md.

# Models and the review pipeline. `model`, `base_url`, `effort`, and
# `web_search` apply to chat and `aster fix` too; the rest is review-only.
review:
  # Models (any OpenAI-compatible provider). `model` is the fallback used for a
  # stage that has no explicit override.
  # Set `model: auto` to pick from OpenRouter's live benchmark rankings
  # instead of a pinned id (OpenRouter endpoints only). The tier comes from
  # ASTER_ROUTER_TIER (cheap | balanced | strong, default balanced); picks are
  # cached for a day in ~/.aster/model-rankings.json. `aster model router`
  # shows what each tier resolves to.
  model: openai/gpt-4o-mini
  # ChatGPT subscription instead of a key: `aster login codex`, then
  #   base_url: https://chatgpt.com/backend-api/codex
  #   model: gpt-5.6-terra
  base_url: https://openrouter.ai/api/v1
  hypothesis_model: deepseek/deepseek-v4-flash   # cheap, high-recall
  verify_model: anthropic/claude-sonnet-5        # independent adversarial verify

  # Drop findings below this confidence (0.0-1.0). Default 0.5; this example
  # runs a little stricter.
  min_confidence: 0.6

  # Cap the diff size sent to the model.
  max_diff_bytes: 200000

  # Static-analysis backends whose findings also flow through verification.
  # Available: semgrep (needs `semgrep`/`opengrep` on PATH), ast-grep (built
  # in, no binary needed; point ASTER_ASTGREP_RULES at a rule file).
  analyzers: []            # e.g. [ast-grep] or [semgrep, ast-grep]

  # Repo-relative ast-grep rule file for the `ast-grep` backend. An unreadable
  # path warns and runs without rules.
  # astgrep_rules: .aster/rules.yml

  # Reasoning budget for thinking models: off | low | medium | high.
  effort: low

  # OpenRouter web search, off by default. On, the agent gets a web-search
  # server tool and review stages search every request. No effect on
  # non-OpenRouter endpoints. Set true here or ASTER_WEB_SEARCH=1.
  web_search: false

  # Bias the hypothesis pass toward these defect classes.
  focus_areas:
    - correctness
    - security

  # Hypothesis fan-out: the diff is split into file-scoped chunks of at most
  # hypothesis_chunk_bytes bytes and each chunk gets its own model call, up to
  # hypothesis_concurrency at a time. 0 bytes disables chunking (one whole-diff call).
  hypothesis_concurrency: 4
  hypothesis_chunk_bytes: 40000

  # Which files to review. `include` empty = everything except `exclude`.
  include: []              # e.g. ["src/**/*.rs", "**/*.ts"]
  exclude:
    - "target/**"
    - "node_modules/**"
    - "**/*.lock"
    - "**/*.min.js"

# What the agent may edit, read, and run.
permissions:
  # plan   explore and present a plan, never edit or run
  # manual ask before each edit and command (prompts in the TUI; denies when headless)
  # auto   edit and run, pausing on risky commands (sudo, rm, curl, ssh …)
  # edit   as auto, but commands are trusted; only a rule stops one
  # yolo   no rules, no sandbox
  mode: edit
  # Rules in one language: Edit(glob), Read(glob), Bash(command:*).
  # A bare Edit, Read, or Bash covers everything that tool does.
  # Precedence: deny, then ask, then allow, then the built-ins, then the mode.
  # A Bash rule matches the command line and every part of a shell script it
  # carries, so Bash(sudo:*) still fires on `bash -lc "build && sudo install"`.
  allow: []   # e.g. ["Bash(cargo test:*)", "Edit(src/**)", "Read(**/.env)"]
  ask: []     # e.g. ["Edit(migrations/**)", "Bash(git push:*)"]
  deny: []    # e.g. ["Bash(npm publish:*)", "Edit(infra/**)"]
  # Built-ins ask before writing .git/**, .github/workflows/**, and .husky/**,
  # ask before sudo, rm, curl, ssh and friends (in `auto`; `edit` trusts
  # commands), and refuse to read .env, *.pem, *.key and other secrets. One
  # `allow` entry overrides any single built-in; this switch drops the set.
  use_default_rules: true
  # Directories outside the repo the agent may read without asking. Absolute or
  # ~-relative. Anything else outside the repo prompts, and an approval lasts
  # for the rest of the session. Writing outside the repo always prompts.
  additional_directories: []    # e.g. ["~/Desktop", "~/Downloads"]
  # Credential directories a command may read inside the sandbox without being
  # asked, written `<command>:<dir>`. The sandbox denies ~/.ssh, ~/.aws,
  # ~/.gnupg, ~/.config/gh, and ~/.kube by default; a tool that needs one
  # prompts, and an approval covers that command only. Preauthorize here for
  # headless runs, which have no way to answer. Keychains are never grantable.
  allow_credentials: []     # e.g. ["gh:~/.config/gh", "aws:~/.aws"]

# Limits on one agent turn. Env overrides: ASTER_MAX_TOOL_ROUNDS,
# ASTER_COMMAND_TIMEOUT, ASTER_COMPACT_BUDGET.
agent:
  # Tool rounds before the agent has to answer with what it has. It says so
  # when it hits this, rather than quietly wrapping up.
  max_tool_rounds: 60
  # Seconds one `run_command` may take. Builds and test suites live here.
  command_timeout_secs: 300
  # History size (chars) above which older turns are compacted into a summary.
  # Lower it for small-context models.
  compact_budget_chars: 192000

# Experimental, off by default, and may change or disappear in any release.
experimental:
  # Ask TypeSafe's Jev classifier (https://typesafe.ai) at each tool round
  # whether the loop should continue, retry, ask you, or stop. Advisory only:
  # a low-confidence answer is ignored and the round cap still binds. Needs
  # the `jev` cargo feature and ASTER_JEV_API_KEY; ASTER_JEV=1 also turns it on.
  # jev: false

# Fan-out limits for the sub-agents the `agent` tool spawns. Env overrides:
# ASTER_COLLECTOR_MODEL, ASTER_AGENT_MAX_CONCURRENT, ASTER_AGENT_MAX_PER_TURN,
# ASTER_AGENT_TIMEOUT.
agents:
  # Cheap model for collector agents. Falls back to the session model.
  # collector_model: deepseek/deepseek-v4-flash
  max_concurrent: 8         # sub-agents running at once
  max_per_turn: 24          # `agent` tasks accepted in one turn
  agent_timeout_secs: 300   # seconds a single sub-agent may run

# What chat prints on its own. `/welcome` inside a chat toggles this and saves.
ui:
  # Print the session header (model, provider, skills) when chat starts.
  welcome: true
  # Chat color theme: default, light, midnight, forest, or any theme in
  # THEMES.md. `/theme` in a chat picks one and saves.
  theme: default

# Dictation (ctrl+r in chat, the mic button elsewhere) and reading replies
# aloud. `/voice` in a chat shows the setup and saves changes. With nothing
# set, dictation uses the first key found (ELEVENLABS_API_KEY, OPENAI_API_KEY,
# GROQ_API_KEY, DEEPGRAM_API_KEY) and read aloud uses the system voice.
# voice:
#   stt: groq                 # elevenlabs, openai, groq, deepgram, openai-compatible
#   stt_model: whisper-large-v3-turbo
#   stt_url: http://localhost:8000/v1   # for openai-compatible, e.g. speaches
#   tts: system               # system, elevenlabs, openai, openai-compatible
#   tts_voice: af_heart
#   tts_url: http://localhost:8880/v1   # for openai-compatible, e.g. kokoro-fastapi
#   language: en              # unset lets the provider detect it
#   read_aloud: false

# MCP servers that give the agent extra tools. `aster mcp list` shows what they
# expose; `aster mcp enable|disable <name>` flips them without editing by hand.
# Installed plugins add their own here as `<plugin>/<server>`; see
# docs/PLUGINS.md.
#
# Web search and page reading need no server and no key: they ship in the
# binary as `web/search` and `web/extract`. See docs/MCP.md.
mcp:
  # How much of the context the tool inventory may spend before the prompt
  # drops to server names only and the model searches for what it needs.
  context_tokens: 100000
  inventory_percent: 1.5
  search_limit: 10          # matches returned by one `search`
  # The WebMCP bridge: tools a page registers through `document.modelContext`
  # become `webmcp/<tool>` here, called in your own browser tab with your
  # session. Start Chrome with `--remote-debugging-port=9222` first.
  # webmcp:
  #   enabled: true
  #   cdp_url: http://127.0.0.1:9222
  servers:
    # A real browser: navigate, click, type, screenshot. Needs uv and Python
    # 3.11+, then `uvx browser-use install` once to fetch Chromium. It browses
    # in its own profile under ~/.config/browseruse, not your signed-in Chrome.
    browser:
      command: uvx
      args: ["--from", "browser-use", "browser-use", "--mcp"]
      env:
        # browser-use reports usage to its vendor unless this is set.
        ANONYMIZED_TELEMETRY: "False"
        # Without this the browser opens a window on your screen.
        BROWSER_USE_HEADLESS: "true"
        # Uncomment to confine the agent to named hosts.
        # BROWSER_USE_ALLOWED_DOMAINS: "example.com,docs.rs"
      disabled: true
    # A remote server names a url instead of a command. The transport is
    # Streamable HTTP unless `type: sse` asks for the older binding.
    deepwiki:
      url: https://mcp.deepwiki.com/mcp
      # headers:
      #   X-Tenant: acme

  # Turn individual tools off by their `server/tool` id; globs work. `deny`
  # wins over `allow`, and an empty `allow` means every tool. Also settable
  # with `aster mcp disable web/crawl`.
  tools:
    allow: []
    deny:
      # Both want a second LLM API key, and the retry tool runs a whole agent
      # loop inside one tool call.
      - "browser/browser_extract_content"
      - "browser/retry_with_browser_use_agent"

# Scheduled agent runs, installed with `aster cron install` into the OS
# scheduler (launchd on macOS, cron on Linux). Names are lowercase-hyphen and
# unique; cron is a five-field expression in local time. `notify: true` posts
# a native notification when the run finishes; `notify_url` is opened in the
# default browser when that notification is clicked. One-shot reminders are
# simpler: `aster remind "stand up" "in 30m"`.
# schedules:
#   - name: nightly-review
#     cron: "0 9 * * *"
#     agent: sentinel
#     task: "review yesterday's commits on main"
#     notify: true
#     notify_url: "https://github.com/you/you/commits/main"