auto-agents Help

Configuration reference

auto-agents reads auto-agents.toml from repository root on each launch. Legacy dev.toml is still supported as fallback.

All fields are optional. Start with defaults and add only required overrides.

Frequently used top-level fields

project_name = "my-project" workflow_preset = "default" bootstrap_agent_files = true bootstrap_snapshot = false use_subscription = false

Agent selection and model defaults

Use --agent per invocation, or persist model preferences in config.

[agent_models] claude = "claude-opus-4-7" codex = "gpt-5-codex"

--model <id> and AUTO_AGENTS_MODEL can override model choice for one run.

Skill path resolution

When [skills] entries are omitted, auto-agents resolves skill files in this order:

  1. .auto-agents/skills/.../SKILL.md (recommended override layout in downstream repos)

  2. assets/skills/.../SKILL.md (bundled source layout)

  3. Materialized bundled copies under OS app-data directory

If both .auto-agents/skills and assets/skills exist, .auto-agents/skills wins.

Telemetry opt-out

Disable telemetry with any of these methods:

  • DO_NOT_TRACK=1

  • AUTO_AGENTS_NO_TELEMETRY=1

  • Config file:

[telemetry] enabled = false

Bot account setup for code review

code-review submits PR reviews through GitHub APIs and requires a bot identity that is separate from the PR author.

Recommended mode: GitHub App credentials:

  • DEV_BOT_APP_ID

  • DEV_BOT_INSTALLATION_ID

  • DEV_BOT_PRIVATE_KEY (path to PEM file)

Alternative mode: second-user PAT:

  • DEV_BOT_TOKEN or DEV_BOT_TOKEN_PATH

Non-secret values can be saved to auto-agents.toml. Secrets are persisted through OS credential storage, not plaintext config.

Workspace feature

Use --workspace <name> to load context overrides from .auto-agents/workspaces/<name>/.

  • --workspace none disables workspace selection explicitly.

  • When omitted and workspaces exist, auto-agents can prompt interactively.

  • Commit only non-secret defaults to VCS.

  • Keep API keys/tokens in environment variables or keychain storage.

  • Prefer explicit workflow_preset in shared repositories.

16 July 2026
Desktop and web UIArchitecture