# Gza Configuration Reference

This document provides a comprehensive reference for all configuration options available in Gza.

## Configuration File (gza.yaml)

The main configuration file is `gza.yaml` in your project root directory.
You can optionally add `gza.local.yaml` for machine-local overrides.

### Required Configuration

| Option | Type | Description |
|--------|------|-------------|
| `project_name` | String | Project name used for branch prefixes and Docker image naming |

### Optional Configuration

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `tasks_file` | String | `tasks.yaml` | Path to legacy tasks file |
| `log_dir` | String | `.gza/logs` | Directory for log files |
| `use_docker` | Boolean | `true` | Whether to run Claude in Docker container |
| `docker_image` | String | `{project_name}-gza` | Custom Docker image name |
| `docker_volumes` | List | `[]` | Custom Docker volume mounts (e.g., `["/host:/container:ro"]`) |
| `timeout_minutes` | Integer | `10` | Maximum time per task in minutes |
| `branch_mode` | String | `multi` | Branch strategy: `single` or `multi` |
| `max_steps` | Integer | `50` | Maximum conversation steps per task (preferred) |
| `max_turns` | Integer | `50` | Legacy alias for `max_steps` |
| `worktree_dir` | String | `/tmp/gza-worktrees` | Directory for git worktrees |
| `work_count` | Integer | `1` | Number of tasks to run in a single work session |
| `provider` | String | `claude` | AI provider: `claude`, `codex`, or `gemini` |
| `task_providers` | Dict | `{}` | Route task types to providers (e.g., `review: claude`) |
| `providers` | Dict | `{}` | Provider-scoped model/task-type config (preferred) |
| `model` | String | *(empty)* | Legacy global model fallback (compatible) |
| `task_types` | Dict | `{}` | Legacy global per-task fallback (compatible) |
| `claude` | Dict | *(see below)* | Claude-specific configuration section |
| `claude.fetch_auth_token_from_keychain` | Boolean | `false` | Fetch OAuth token from macOS Keychain for Docker (macOS only) |
| `claude.args` | List | `["--allowedTools", "Read", "Write", "Edit", "Glob", "Grep", "Bash"]` | Arguments passed to Claude Code CLI |
| `claude_args` | List | *(deprecated)* | Use `claude.args` instead |
| `review_diff_small_threshold` | Integer | `500` | Total changed-line cutoff (`added + removed`) below which review prompts include full inline diff |
| `review_diff_medium_threshold` | Integer | `2000` | Total changed-line cutoff above `review_diff_small_threshold`; larger diffs use targeted excerpts instead of full inline diff |
| `review_context_file_limit` | Integer | `12` | Maximum number of changed files to include in targeted excerpt mode for large review diffs |

### Local Overrides (gza.local.yaml)

Use `gza.local.yaml` for machine-specific settings that should not be committed.

- Merge behavior: deep merge for dictionaries, replace for scalars/lists
- Precedence: `gza.yaml` < `gza.local.yaml` < env vars
- Guardrails: only approved keys can be overridden in `gza.local.yaml`

Example:

```yaml
# gza.local.yaml
use_docker: false
timeout_minutes: 30
docker_volumes:
  - ~/datasets:/datasets:ro
providers:
  claude:
    task_types:
      review:
        model: claude-haiku-4-5
```

Inspect effective values and source attribution:

```bash
gza config
gza config --json
```

### Branch Naming Strategy

Configure branch naming with the `branch_strategy` option. Three presets are available:

```yaml
# Preset: monorepo (default)
# Generates: {project}/{task_id}
# Example: myproject/20260108-add-feature
branch_strategy: monorepo

# Preset: conventional
# Generates: {type}/{slug}
# Example: feature/add-feature
branch_strategy: conventional

# Preset: simple
# Generates: {slug}
# Example: add-feature
branch_strategy: simple

# Preset: date_slug
# Generates: {date}/{slug}
# Example: 20260108/add-feature
branch_strategy: date_slug
```

Or use a custom pattern:

```yaml
branch_strategy:
  pattern: "{type}/{slug}"
  default_type: feature
```

**Available pattern variables:**

| Variable | Description |
|----------|-------------|
| `{project}` | Project name |
| `{task_id}` | Full task ID (YYYYMMDD-slug) |
| `{date}` | Date portion (YYYYMMDD) |
| `{slug}` | Slug portion |
| `{type}` | Inferred or default type |

**Branch types** are automatically inferred from task prompts:

| Type | Trigger Keywords |
|------|-----------------|
| `docs` | documentation, document, doc, docs, readme |
| `test` | tests, test, spec, coverage |
| `perf` | performance, optimize, speed |
| `refactor` | refactor, restructure, reorganize, clean |
| `fix` | fix, bug, error, crash, broken, issue |
| `chore` | chore, update, upgrade, bump, deps, dependencies |
| `feature` | feat, feature, add, implement, create, new |

### Docker Volume Mounts

Mount additional directories or files from the host into the Docker container using `docker_volumes`. This is useful for providing access to datasets, model files, or other resources.

```yaml
docker_volumes:
  - "~/datasets:/datasets:ro"          # Tilde expanded automatically
  - "/Users/x/models:/models"
  - "/tmp/cache:/cache"
```

**Volume format:** Each volume uses Docker's standard volume syntax:
- `source:destination` - Mount `source` from host to `destination` in container
- `source:destination:mode` - Add mode flags like `ro` (read-only) or `rw` (read-write)

**Common mount modes:**
- `ro` - Read-only mount (recommended for input data)
- `rw` - Read-write mount (default if omitted)
- `z` - SELinux label sharing (for container isolation)
- `Z` - SELinux exclusive label (for single container)

**Notes:**
- Volumes are only used when `use_docker: true`
- Tilde (`~`) in source paths is automatically expanded to your home directory
- The workspace is always mounted at `/workspace` automatically
- Config validation warns about common syntax errors but doesn't block invalid formats

### Provider-Scoped Configuration

Preferred approach for multi-provider setups:

```yaml
provider: claude
task_providers:
  review: claude
  implement: codex
providers:
  claude:
    model: claude-sonnet-4-5
    task_types:
      review:
        model: claude-haiku-4-5
        max_turns: 20
  codex:
    model: o4-mini
```

### Task Types Configuration (Legacy-Compatible)

Override settings per task type:

```yaml
task_types:
  explore:
    model: claude-sonnet-4-5
    max_turns: 20
  plan:
    model: claude-opus-4
    max_turns: 30
  review:
    max_turns: 15
```

Valid task types: `explore`, `plan`, `implement`, `review`, `improve`

Top-level `task_types` and `model` are still supported for backward compatibility. They are used as fallbacks when no provider-scoped value exists.

### Resolution Precedence

Provider selection:
1. `task.provider`
2. `task_providers.<task_type>`
3. `provider`

Model selection:
1. `task.model`
2. `providers.<effective_provider>.task_types.<task_type>.model`
3. `providers.<effective_provider>.model`
4. `task_types.<task_type>.model` (legacy fallback)
5. `model` / `defaults.model` (legacy fallback)
6. Provider runtime default (if no model resolved)

Max steps selection:
1. `providers.<effective_provider>.task_types.<task_type>.max_steps`
2. `providers.<effective_provider>.task_types.<task_type>.max_turns` (legacy)
3. `task_types.<task_type>.max_steps` (legacy fallback)
4. `task_types.<task_type>.max_turns` (legacy fallback)
5. `max_steps` / `defaults.max_steps`
6. `max_turns` / `defaults.max_turns` (legacy fallback)

---

### Providers and Models

Gza supports multiple AI providers for task execution:

| Provider | Status | Description |
|----------|--------|-------------|
| `claude` | **Supported** | Claude Code CLI (default) |
| `codex` | **Supported** | OpenAI Codex CLI |
| `gemini` | *Experimental* | Gemini CLI - partially implemented |

Set your provider in `gza.yaml`:

```yaml
provider: claude
model: claude-sonnet-4-5  # optional: override the default model
```

### Provider Credentials

**Claude:**

| Variable | Description |
|----------|-------------|
| `ANTHROPIC_API_KEY` | API key for Claude (alternative to OAuth) |

Claude supports two authentication methods:

1. **OAuth** (subscription): Run `claude login` on host. Credentials stored in `~/.claude/` are mounted into Docker. Uses your Claude Max subscription.
2. **API Key**: Set `ANTHROPIC_API_KEY` in `~/.gza/.env`. Uses pay-per-token API pricing.

**Important:** `ANTHROPIC_API_KEY` takes precedence over OAuth. If you have both configured and want to use your subscription, comment out or remove `ANTHROPIC_API_KEY` from your `.env` files.

**Codex:**

| Variable | Description |
|----------|-------------|
| `CODEX_API_KEY` | API key for OpenAI Codex (alternative to OAuth) |

Codex authentication priority:
1. OAuth (`~/.codex/auth.json`) - preferred, uses ChatGPT pricing
2. `CODEX_API_KEY` - fallback, uses standard OpenAI API pricing

**Gemini:**

| Variable | Description |
|----------|-------------|
| `GEMINI_API_KEY` | Primary API key for Gemini |
| `GOOGLE_API_KEY` | Alternative API key (Vertex AI) |
| `GOOGLE_APPLICATION_CREDENTIALS` | Path to service account JSON file |
| `GEMINI_SHELL_ENABLED` | Enable shell commands (`true`) |

---

## Dotenv Files (.env)

Environment variables can be set in `.env` files:

| Location | Scope |
|----------|-------|
| `~/.gza/.env` | User-level (applies to all projects) |
| `.env` | Project-level (overrides everything) |

These files are for **provider credentials only** (API keys, tokens). Gza configuration should go in `gza.yaml` or `gza.local.yaml`, not in `.env` files.

**Credential precedence** (highest to lowest):

1. **Project `.env`** - Overrides all other sources
2. **Shell environment** - Variables exported in your shell
3. **`~/.gza/.env`** - Only sets values not already defined

This means if you have `ANTHROPIC_API_KEY` set in your shell, you don't need `~/.gza/.env` at all. The home `.env` file uses `setdefault` behavior, so it won't override existing environment variables.

**Format:**

```
ANTHROPIC_API_KEY=sk-ant-...
```

---

## Command-Line Arguments

### Global Options

All commands support these options:

| Option | Description |
|--------|-------------|
| `--project`, `-C` | Target project directory (default: current directory) |
| `--help`, `-h` | Show help for command |

```bash
gza <command> [options]
gza -C /path/to/project <command>
```

### work

Run tasks from the queue.

```bash
gza work [task_id...] [options]
```

| Option | Description |
|--------|-------------|
| `task_id` | Specific task ID(s) to run (can specify multiple) |
| `--no-docker` | Run Claude directly instead of in Docker |
| `--count N`, `-c N` | Number of tasks to run before stopping |
| `--background`, `-b` | Run worker in background |
| `--max-turns N` | Override max_turns setting for this run |

### add

Add a new task.

```bash
gza add [prompt] [options]
```

| Option | Description |
|--------|-------------|
| `prompt` | Task prompt (opens $EDITOR if not provided) |
| `--edit`, `-e` | Open $EDITOR to write the prompt |
| `--type TYPE` | Set task type: `explore`\|`plan`\|`implement`\|`review`\|`improve` (default: `implement`) |
| `--branch-type TYPE` | Set branch type hint for naming |
| `--explore` | Create explore task (shorthand) |
| `--group NAME` | Set task group |
| `--based-on ID` | Base on previous task |
| `--depends-on ID` | Set dependency on another task |
| `--review` | Auto-create review task on completion |
| `--same-branch` | Continue on depends_on task's branch |
| `--spec FILE` | Path to spec file for context |
| `--prompt-file FILE` | Read prompt from file (for non-interactive use) |
| `--model MODEL` | Override model for this task (e.g., `claude-3-5-haiku-latest`) |
| `--provider PROVIDER` | Override provider for this task (`claude`, `codex`, or `gemini`) |
| `--no-learnings` | Skip injecting `.gza/learnings.md` context into this task's prompt |

### edit

Edit an existing task.

```bash
gza edit <task_id> [options]
```

| Option | Description |
|--------|-------------|
| `--group NAME` | Move task to group (empty `""` removes) |
| `--based-on ID` | Set dependency |
| `--explore` | Convert to explore task |
| `--task` | Convert to regular task |
| `--review` | Enable automatic review task creation on completion |
| `--prompt TEXT` | Set new prompt directly (use `-` for stdin) |
| `--prompt-file FILE` | Read new prompt from file |

### log

View task or worker logs.

```bash
gza log <identifier> [options]
```

| Option | Description |
|--------|-------------|
| `identifier` | Task ID (numeric), slug, or worker ID |
| `--slug`, `-s` | Interpret identifier as task slug (supports partial match) |
| `--worker`, `-w` | Interpret identifier as worker ID |
| `--steps` | Show compact step timeline |
| `--steps-verbose` | Show verbose step timeline with substeps |
| `--turns` | Deprecated alias for `--steps-verbose` |
| `--follow`, `-f` | Follow log in real-time |
| `--tail N` | Show last N lines |
| `--raw` | Show raw JSON lines |

By default, the identifier is treated as a task ID (numeric).

### stats

Show task statistics.

```bash
gza stats [options]
```

| Option | Description |
|--------|-------------|
| `--last N`, `-n N` | Show last N tasks (default: 5) |
| `--all` | Show all tasks (no limit) |
| `--type TYPE` | Filter by task type |
| `--days N` | Show only tasks from the last N days |
| `--start-date YYYY-MM-DD` | Show only tasks on or after this date |
| `--end-date YYYY-MM-DD` | Show only tasks on or before this date |
| `--cycles` | Show cycle analytics (review/improve iteration statistics) |
| `--task ID` | Show cycle analytics for a specific task (use with `--cycles`) |
| `--json` | Output as machine-readable JSON |

### pr

Create a pull request for a completed task.

```bash
gza pr <task_id> [options]
```

| Option | Description |
|--------|-------------|
| `--title TITLE` | Override auto-generated PR title |
| `--draft` | Create as draft PR |

### delete

Delete a task.

```bash
gza delete <task_id> [options]
```

| Option | Description |
|--------|-------------|
| `--yes`, `-y` | Skip confirmation prompt |
| `--force`, `-f` | Deprecated alias for `--yes` |

### clean

Archive old log and worker files to free up disk space. By default, files are moved to `.gza/archive/` rather than deleted.

```bash
gza clean [options]
```

| Option | Description |
|--------|-------------|
| `--days N` | Archive files older than N days (default: 30) |
| `--purge` | Delete archived files instead of archiving (default threshold: 365 days) |
| `--dry-run` | Show what would be archived/deleted without doing it |

**Example usage:**

```bash
# Preview what would be archived (default: 30 days)
gza clean --dry-run

# Archive files older than 30 days
gza clean

# Archive files older than 7 days
gza clean --days 7

# Delete files from archive older than 365 days
gza clean --purge

# Delete archived files older than 60 days
gza clean --purge --days 60
```

The clean command archives files from:
- `.gza/logs/` - Task execution logs
- `.gza/workers/` - Worker metadata files

Files are moved to `.gza/archive/` based on their modification time. Use `--purge` to permanently delete archived files.

### import

Import tasks from a YAML file.

```bash
gza import [file] [options]
```

| Option | Description |
|--------|-------------|
| `file` | YAML file to import from |
| `--dry-run` | Preview without creating tasks |
| `--force`, `-f` | Skip duplicate detection |

### group

Show tasks in a specific group.

```bash
gza group <group>
```

### status

List running workers (alias for `ps`).

```bash
gza status
```

### ps

Show running workers.

```bash
gza ps [options]
```

| Option | Description |
|--------|-------------|
| `--all`, `-a` | Include completed/failed workers |
| `--quiet`, `-q` | Only show worker IDs |
| `--json` | Output as JSON |

### stop

Stop workers.

```bash
gza stop [worker_id] [options]
```

| Option | Description |
|--------|-------------|
| `worker_id` | Worker ID to stop |
| `--all` | Stop all running workers |
| `--force` | Force kill (SIGKILL) |

### validate

Validate configuration.

```bash
gza validate
```

### config

Show effective configuration and source attribution (`base`, `local`, `env`, `default`).

```bash
gza config
gza config --json
```

### show

Show details of a specific task.

```bash
gza show <task_id> [options]
```

| Option | Description |
|--------|-------------|
| `--full` | Show full output without truncation |

### resume

Resume a failed task from where it left off. The AI continues with the existing conversation context.

```bash
gza resume <task_id> [options]
```

| Option | Description |
|--------|-------------|
| `--no-docker` | Run Claude directly instead of in Docker |
| `--background`, `-b` | Run worker in background |
| `--queue`, `-q` | Add task to queue without executing immediately |
| `--max-turns N` | Override max_turns setting for this run |

### retry

Retry a failed or completed task from scratch. Starts a fresh conversation.

```bash
gza retry <task_id> [options]
```

| Option | Description |
|--------|-------------|
| `--no-docker` | Run Claude directly instead of in Docker (only with --background) |
| `--background`, `-b` | Run worker in background |
| `--queue`, `-q` | Add task to queue without executing immediately |
| `--max-turns N` | Override max_turns setting for this run |

### mark-completed

Manually complete a task when automation failed. Defaults are task-type aware:
- `task`, `implement`, `improve` default to git-verified completion
- `explore`, `plan`, `review` default to status-only completion

```bash
gza mark-completed <task_id> [--verify-git | --force]
```

| Option | Description |
|--------|-------------|
| `task_id` | Task ID to mark as completed |
| `--verify-git` | Validate branch and commits before completion |
| `--force` | Status-only completion (for non-code tasks or stale in_progress recovery) |

`force-complete` is deprecated. Use `mark-completed <task_id> --force`.

### merge

Merge a completed task's branch into the current branch.

```bash
gza merge <task_id> [task_id...] [options]
```

| Option | Description |
|--------|-------------|
| `task_id` | Task ID(s) to merge (can specify multiple) |
| `--all` | Merge all unmerged done tasks (task_ids optional when used) |
| `--squash` | Squash commits into a single commit |
| `--rebase` | Rebase onto current branch instead of merging |
| `--delete` | Delete the branch after successful merge |
| `--remote` | Fetch from origin and rebase against remote (requires --rebase) |
| `--mark-only` | Mark branch as merged without performing actual merge (deletes branch) |
| `--resolve` | Auto-resolve conflicts using AI when rebasing (requires --rebase) |

### unmerged

List tasks with branches that haven't been merged to main.

```bash
gza unmerged [options]
```

| Option | Description |
|--------|-------------|
| `--commits-only` | Use commit-based detection (git cherry) instead of diff-based |
| `--all` | Include failed tasks and check git directly for commits |

For each unmerged implementation, output includes:
- Branch diff/commit summary.
- A `lineage:` chain showing related task IDs and types (implementation, review, improve).
- A `review:` freshness classification:
  - `no review` when no completed review exists.
  - `reviewed` when the latest completed review still reflects current code.
  - `review stale` when code-changing work (for example an improve task) happened after the latest review.

### groups

List all task groups with their task counts.

```bash
gza groups
```

### history

List recent completed or failed tasks.

```bash
gza history [options]
```

| Option | Description |
|--------|-------------|
| `--last N`, `-n N` | Show last N tasks (default: 10) |
| `--all` | Show all tasks (no limit) |
| `--type TYPE` | Filter by task type: `explore`, `plan`, `implement`, `review`, `improve`, `learn` |
| `--days N` | Show only tasks from the last N days |
| `--start-date YYYY-MM-DD` | Show only tasks on or after this date |
| `--end-date YYYY-MM-DD` | Show only tasks on or before this date |
| `--status STATUS` | Filter by status: `completed`, `failed`, or `unmerged` |
| `--incomplete` | Show only unresolved tasks (failed or unmerged) |
| `--lineage-depth N` | Expand lineage N levels for each task |

### checkout

Checkout a task's branch, removing any stale worktree if needed.

```bash
gza checkout <task_id_or_branch> [options]
```

| Option | Description |
|--------|-------------|
| `task_id_or_branch` | Task ID or branch name to checkout |
| `--force`, `-f` | Force removal of worktree even if it has uncommitted changes |

### diff

Show git diff for a task's changes with colored output and pager support.

```bash
gza diff [task_id] [diff_args...]
```

| Option | Description |
|--------|-------------|
| `task_id` | Task ID to diff (optional, uses current branch if omitted) |
| `diff_args` | Arguments passed to git diff (use `--` before options like `--stat`) |

### rebase

Rebase a task's branch onto a target branch.

```bash
gza rebase <task_id> [options]
```

| Option | Description |
|--------|-------------|
| `--onto BRANCH` | Branch to rebase onto (defaults to current branch) |
| `--remote` | Fetch from origin and rebase against remote target branch |
| `--resolve` | Auto-resolve rebase conflicts using `/gza-rebase` in the active provider runtime |
| `--force`, `-f` | Force remove worktree even if it has uncommitted changes |
| `--background`, `-b` | Run rebase in background |

When `--resolve` is used, gza runs the active task provider (`claude`, `codex`, or `gemini`) and sends the `/gza-rebase --auto` prompt. If the `gza-rebase` skill is missing for that runtime, gza fails fast with an install command such as:

```bash
uv run gza skills-install --target codex gza-rebase --project /path/to/project
```

### cleanup

Clean up stale worktrees, old logs, and worker metadata.

```bash
gza cleanup [options]
```

| Option | Description |
|--------|-------------|
| `--worktrees` | Only clean up stale worktrees |
| `--logs` | Only clean up old log files |
| `--workers` | Only clean up stale worker metadata |
| `--days N` | Remove items older than N days (default: 30) |
| `--keep-unmerged` | Keep logs for tasks that are still unmerged |
| `--dry-run` | Show what would be cleaned without doing it |
| `--force` | Skip confirmation prompt before removing worktrees |

### improve

Create an improve task to address review feedback on an implementation.

```bash
gza improve <impl_task_id> [options]
```

| Option | Description |
|--------|-------------|
| `impl_task_id` | Implementation task ID to improve |
| `--review` | Auto-create review task on completion |
| `--queue`, `-q` | Add task to queue without executing immediately |
| `--background`, `-b` | Run worker in background |
| `--no-docker` | Run Claude directly instead of in Docker |
| `--max-turns N` | Override max_turns setting for this run |
| `--model MODEL` | Override model for this task |
| `--provider PROVIDER` | Override provider for this task |

The improve command finds the most recent review for the implementation task and creates a new task that continues on the same branch to address the review feedback.

### review

Create and run a review task for an implementation. Runs immediately by default.

```bash
gza review <task_id> [options]
```

| Option | Description |
|--------|-------------|
| `task_id` | Implementation task ID to review |
| `--queue`, `-q` | Add task to queue without executing immediately |
| `--background`, `-b` | Run worker in background |
| `--no-docker` | Run Claude directly instead of in Docker |
| `--no-pr` | Do not post review to PR even if one exists |
| `--pr` | Require PR to exist (error if not found) |
| `--open` | Open the review file in $EDITOR after completion |
| `--model MODEL` | Override model for this task |
| `--provider PROVIDER` | Override provider for this task |

When a PR exists for the implementation task, the review is automatically posted as a PR comment.

### next

List upcoming pending tasks.

```bash
gza next [options]
```

Shows pending tasks that are ready to run (dependencies satisfied). Tasks blocked by dependencies are listed separately.

### implement

Create an implementation task from a completed plan task.

```bash
gza implement <plan_task_id> [prompt] [options]
```

| Option | Description |
|--------|-------------|
| `plan_task_id` | Completed plan task ID to implement |
| `prompt` | Implementation prompt (defaults to plan-derived prompt) |
| `--review` | Auto-create review task on completion |
| `--group NAME` | Set task group |
| `--depends-on ID` | Set dependency on another task |
| `--same-branch` | Continue on depends_on task's branch instead of creating new |
| `--branch-type TYPE` | Set branch type hint for branch naming |
| `--model MODEL` | Override model for this task |
| `--provider PROVIDER` | Override provider for this task |
| `--no-learnings` | Skip injecting learnings context |
| `--queue`, `-q` | Add task to queue without executing immediately |
| `--background`, `-b` | Run worker in background |
| `--no-docker` | Run Claude directly instead of in Docker |
| `--max-turns N` | Override max_turns setting for this run |

### advance

Intelligently progress unmerged tasks through their lifecycle. Handles review creation, improve tasks, merging, and resuming failed tasks.

```bash
gza advance [task_id] [options]
```

| Option | Description |
|--------|-------------|
| `task_id` | Specific task ID to advance (omit to advance all eligible) |
| `--dry-run` | Preview actions without executing them |
| `--max N` | Limit the number of tasks to advance |
| `--no-docker` | Run workers directly instead of in Docker |
| `--plans` | List completed plans with no implementation task yet |
| `--create` | With `--plans`: create queued implement tasks for listed plans |
| `--auto`, `-y` | Skip confirmation and execute immediately |
| `--batch B` | Stop after spawning B background workers |
| `--no-resume-failed` | Skip auto-resume of failed tasks |
| `--max-resume-attempts N` | Override max_resume_attempts config value |
| `--max-review-cycles N` | Override max_review_cycles config value |
| `--new` | Start new pending tasks to fill remaining `--batch` slots (requires `--batch`) |
| `--type TYPE` | Only advance tasks of this type (`plan` or `implement`) |
| `--squash-threshold N` | Squash-merge branches with N or more commits (0 disables) |

### iterate

Run an automated review/improve cycle for an implementation task. Alias: `cycle`.

```bash
gza iterate <impl_task_id> [options]
```

| Option | Description |
|--------|-------------|
| `impl_task_id` | Implementation task ID to cycle |
| `--max-iterations N` | Maximum review/improve iterations (default: 3) |
| `--dry-run` | Preview what would happen without executing |
| `--continue` | Resume an existing active cycle |
| `--no-docker` | Run Claude directly instead of in Docker |

### learnings

Manage project learnings accumulated from completed tasks.

```bash
gza learnings show
gza learnings update
```

| Subcommand | Description |
|------------|-------------|
| `show` | Display the current learnings file |
| `update` | Regenerate learnings from recent completed tasks |

### refresh

Refresh cached diff stats for unmerged tasks.

```bash
gza refresh [task_id] [options]
```

| Option | Description |
|--------|-------------|
| `task_id` | Task ID to refresh (omit to refresh all unmerged tasks) |
| `--include-failed` | Also refresh failed tasks that have branches |

### set-status

Manually force a task's status.

```bash
gza set-status <task_id> <status>
```

Valid statuses: `pending`, `in_progress`, `completed`, `failed`, `dropped`.

### sync-report

Sync report file content from disk into the database `output_content` field. Useful when report files have been edited manually.

```bash
gza sync-report <task_id>
```

---

## Task Types

Gza supports several task types, each with distinct behavior:

| Type | Purpose | Output Location |
|------|---------|-----------------|
| `explore` | Research and investigation | `.gza/explorations/{task_id}.md` |
| `plan` | Design and architecture | `.gza/plans/{task_id}.md` |
| `implement` | Build per a plan (default) | Code changes on branch |
| `review` | Evaluate implementation | `.gza/reviews/{task_id}.md` |
| `improve` | Address review feedback | Code changes on same branch |

**Typical workflow:**

1. `plan` - Design the approach, saved to `.gza/plans/`
2. `implement --based-on <plan_id> --review` - Build per plan, auto-create review
3. `review` runs automatically, saved to `.gza/reviews/`
4. If changes requested: `improve <impl_id>` addresses feedback on same branch

**Per-type configuration:**

Override settings for specific task types in `gza.yaml`:

```yaml
task_types:
  explore:
    model: claude-sonnet-4-5
    max_turns: 20
  plan:
    model: claude-opus-4
    max_turns: 30
  review:
    max_turns: 15
```

---

## Task Lifecycle

Tasks move through these states:

```
pending → in_progress → completed
                     ↘ failed

Any state can be manually set to `dropped` via `gza set-status`.
```

| State | Description |
|-------|-------------|
| `pending` | Task is queued and waiting to run |
| `in_progress` | A worker is currently executing the task |
| `completed` | Task finished successfully |
| `failed` | Task encountered an error or timed out |
| `dropped` | Task was manually dropped (via `gza set-status`) |

**Recovering from failures:**

- Use `gza resume <task_id>` to continue from where the task left off (preserves conversation context)
- Use `gza retry <task_id>` to start completely fresh

**Dependencies:**

Tasks with `depends_on` set will remain pending until their dependency completes. Use `gza group <group>` to see dependency chains.

---

## Configuration Precedence

Configuration is resolved in the following order (highest to lowest priority):

1. **Command-line arguments**
2. **`gza.local.yaml` file** (if present)
3. **`gza.yaml` file**
4. **Hardcoded defaults**

Provider credentials (API keys) have their own precedence — see [Dotenv Files](#dotenv-files-env) above.

---

## File Locations

### Project Files

| Path | Purpose |
|------|---------|
| `gza.yaml` | Main configuration file |
| `gza.local.yaml` | Local machine overrides (gitignored) |
| `.env` | Project-specific environment variables |
| `.gza/` | Local state directory (add to `.gitignore`) |
| `.gza/gza.db` | SQLite task database |
| `.gza/logs/` | Task execution logs |
| `.gza/workers/` | Worker metadata |
| `etc/Dockerfile.claude` | Generated Docker image for Claude |
| `etc/Dockerfile.codex` | Generated Docker image for Codex |
| `etc/Dockerfile.gemini` | Generated Docker image for Gemini |

> **Note:** `.gza/` and `gza.local.yaml` are machine-specific and should be gitignored.

### Home Directory

| Path | Purpose |
|------|---------|
| `~/.gza/.env` | User-level environment variables |
| `~/.claude/` | Claude OAuth credentials |
| `~/.codex/` | Codex OAuth credentials |
| `~/.gemini/` | Gemini OAuth credentials |

---

## Example Configuration

```yaml
# gza.yaml
project_name: my-app

# Execution settings
use_docker: true
timeout_minutes: 15
max_turns: 80
work_count: 3

# Custom volume mounts (optional)
docker_volumes:
  - "/Users/x/datasets:/datasets:ro"
  - "/Users/x/models:/models"

# AI provider
provider: claude
model: claude-sonnet-4-5

# Branch settings
branch_mode: multi
branch_strategy: conventional

# Task type overrides
task_types:
  explore:
    max_turns: 20
  review:
    max_turns: 15
```

---

## Troubleshooting

### Task stuck in "in_progress"

If a worker crashed or was killed, tasks may be stuck in `in_progress` state:

```bash
# Check for running workers
gza ps

# If no workers are running but task shows in_progress, the worker crashed
# Resume or retry the task:
gza resume <task_id>
# or
gza retry <task_id>
```

### "No pending tasks" but tasks exist

Tasks with unmet dependencies won't be picked up. Check:

```bash
gza next          # Shows pending tasks and their dependencies
gza group <group>  # Shows tasks in a group
```

### Claude Code not found

Gza requires Claude Code CLI to be installed:

```bash
# Install Claude Code
npm install -g @anthropic-ai/claude-code

# Verify installation
claude --version

# Authenticate
claude login
```

### API key not working

Check credential precedence:

```bash
# See what's set
echo $ANTHROPIC_API_KEY

# Check .env files
cat .env
cat ~/.gza/.env
```

Project `.env` overrides shell variables, which override `~/.gza/.env`.

### Docker permission errors

On Linux, your user may need to be in the docker group:

```bash
sudo usermod -aG docker $USER
# Log out and back in
```

### Task times out before completion

Increase the timeout in `gza.yaml`:

```yaml
timeout_minutes: 30  # default is 10
```

Or per-task-type:

```yaml
task_types:
  implement:
    timeout_minutes: 45
```

### Worker won't stop

If `gza stop` doesn't work, force kill:

```bash
gza stop <worker_id> --force
```

Or stop all workers:

```bash
gza stop --all --force
```
