Configuration Guide

Tack uses a layered config system. tack setup writes global selections and tack init writes project selections. This page walks through what each section does so you can inspect or customize it.

For a complete field-by-field reference, see the Configuration Reference.

Config Layers

Tack merges config from three sources:

Later layers override earlier ones. Effective config is computed when commands run; Tack does not persist a resolved copy.

The daemon reads the user layer on startup. Project-scoped CLI commands read the merged result.

You can inspect the merged config:

tack config list              # All merged values
tack config get models.default # A specific value

Sections Overview

Sandbox

Controls where agents execute. The two options are local git worktrees and remote Daytona VMs.

sandbox:
  provider: local  # local git worktrees; daytona uses remote VMs

local runs agents on your machine in separate git worktrees. daytona runs agents in remote VMs.

If you use Daytona, you also need to configure git credentials and optionally a snapshot:

sandbox:
  provider: daytona
  daytona:
    snapshot: "snap_123"

See Isolation & Sandboxes for the full picture.

Project Setup

Commands that run after a sandbox is created to prepare the environment:

project_setup:
  commands:
    - "bun install"
  verify:
    - "bun --version"

commands run once when the sandbox is created. verify runs lightweight checks to confirm setup succeeded.

Agents

Controls how agents run: which runtime, how many at once, and timeout limits.

agents:
  runtime: pi               # or claude-code
  max_concurrent: 8          # Max parallel agents
  stagger_delay_ms: 500      # Delay between agent spawns
  timeouts:
    default:
      max_duration_minutes: 30
      idle_minutes: 10
    builder:
      max_duration_minutes: 45
    reviewer:
      max_duration_minutes: 15

The runtime determines which agent program Tack uses. See Agent Runtimes for the comparison.

Timeouts prevent agents from running forever. max_duration_minutes is total wall clock time. idle_minutes is time since the agent last produced output.

Runtime Auth

Controls how credentials get from Tack into the running agent. Two modes: tack (Tack manages and injects credentials) and native (the runtime uses your local environment). See Credentials & Auth for the full setup.

Models

Which LLM models to use for different purposes:

models:
  default: gpt-5.4
  agent: gpt-5.4
  planner: gpt-5.4
  small_tasks: gpt-5.4-mini

• default — fallback for any role not explicitly set in config
• agent — builder and reviewer agents
• planner — the planner agent
• small_tasks — lightweight operations where a smaller model suffices

Quality Gates

Shell commands that run after agents make changes:

quality_gates:
  - "bun test"
  - "bunx tsc --noEmit"
  - "bun run lint"

Gates run in order. The first failure stops the chain. See Quality Gates for how file attribution works.

Tools

Control which tools agents have access to:

tools:
  max_per_agent: 20
  always_include: []
  always_exclude: []

Tools can also be restricted per-rule and per-blueprint-step. The effective tool set is the intersection of all restrictions.

Watchdog

Monitors agent health and triggers escalation if an agent stalls:

watchdog:
  check_interval_seconds: 30
  nudge_after_minutes: 10
  escalate_after_nudges: 3

Git

Author identity for commits made by agents:

git:
  author_name: Tack
  author_email: tack@local

Editing Config

Interactive

tack config set models.default gpt-5.4
tack config set sandbox.provider local
tack config remove sandbox.daytona.snapshot

config set writes to the project layer when run inside a project. Use --user to write to the user layer:

tack config set --user agents.max_concurrent 8

Manual

Edit .tack/config.yaml directly. The file is YAML and follows the structure shown above.

Project Layout

After tack init, your project has this structure:

.tack/
  config.yaml          # Project config (committable)
  project-id           # Stable UUID (gitignored)
  blueprints/          # Optional custom blueprints (committable)
  rules/               # Project-specific rules (committable)

Global setup state exists at the user layer under ~/.config/tack/.

Full Reference

See the Configuration Reference for every available option.