---
title: Configuration
description: alpaca.config.json keys, defaults, validation rules, and runtime behavior.
relatedCommands:
  - alpaca init --help
  - alpaca doctor --help
  - alpaca labels sync --help
  - alpaca event-hook --help
relatedDocs:
  - quick-start
  - install
  - setup
  - service-runtime
  - scheduling
  - workflow-options
  - follow-up
  - publishing
  - event-hooks
  - workflow-state
---

# Configuration

`alpaca.config.json` is the repository-local control-plane configuration for AlpacaLoop. `alpaca init` creates or updates it. `alpaca doctor` is the safest command for checking whether the current file is valid.

The schema is strict: unknown keys are rejected. `repositoryHost`, `ticketTracker`, `ticketTracker.workflowLabels`, `ticketTracker.showStepProgressInTitles`, `workers`, `workers.default`, `pollIntervalSec`, `workerTimeoutSec`, `parallelism`, and `aiRunLimits` must be present in hand-written config files. Several nested objects and `workerNoOutputTimeoutSec` have defaults when omitted, and `alpaca init` writes the normal defaults.

## Key Commands

```bash
alpaca init -h
alpaca doctor -h
alpaca labels sync -h
alpaca event-hook -h
```

## Settings and Issue Overrides

Some repository defaults can be overridden per issue or pull request with `/alpaca ...` comments or `alpaca issue create` workflow options. Use `-` when no issue-level option exists.

| Goal | `alpaca.config.json` key | Issue/PR option | Meaning and values |
| --- | --- | --- | --- |
| Change worker branch prefix | `branchPrefix` | `-` | Prefix for AI workspace branches. |
| Change new-plan start approval | `approvals.workflowStart.newPlan` | `--workflow-start-new-plan` | `auto`, `confirm`, `conservative`, or `aggressive`. |
| Change replan start approval | `approvals.workflowStart.replan` | `--workflow-start-replan` | `auto`, `confirm`, `conservative`, or `aggressive`. |
| Change where start approval applies | `approvals.workflowStart.scope` | `--workflow-start-scope` | `issue_only` or `issue_and_pr`. |
| Change missing skill setup approval | `approvals.requirementsSetup.skills` | `--requirements-setup-skills` | `auto` or `confirm`. |
| Change missing MCP setup approval | `approvals.requirementsSetup.mcp` | `--requirements-setup-mcp` | `auto` or `confirm`. |
| Change dependency automation | `dependencies.strategy` | `-` | `none`, `auto`, `block`, or `parallel_comment`. |
| Change Git hook execution | `git.hooks` | `-` | `publish`, `publish_and_worker`, or `off`. Controls whether AlpacaLoop runs repository Git hooks for publish and worker Git operations. |
| Change worker workspace setup command | `workspaces.setupCommand` | `-` | Shell command run in an issue workspace before worker execution. Use `null` to disable. |
| Change worker workspace setup frequency | `workspaces.setupFrequency` | `-` | `when_changed`, `once`, or `always`. |
| Change workspace setup fingerprint inputs | `workspaces.setupWatchPaths` | `-` | `auto` or a list of repo-relative files/directories. `auto` watches common Node, Python, PHP, Ruby, Go, Rust, and Deno dependency files. |
| Change workspace setup timeout | `workspaces.setupTimeoutSec` | `-` | Positive integer timeout in seconds. |
| Change automatic plan review revisions | `autoReviews.plan.maxRevisions` | `-` | Maximum internal planner revision passes after automated plan review asks for changes. |
| Change AI workflow option autofill | `aiWorkflowOptionAutofill` | `-` | `on` or `off`. |
| Change default workflow selectors | `workflowTemplateDefaults` | `--workflow`, `--pr-workflow`, `--unplanned-workflow` | Per-target template selectors for issue, pull request, and unplanned workflows: `auto`, `auto_select`, `no_template`, or a workflow template path. Follow-up uses `followup.autoMaintainTemplates` instead of a workflow-template-default entry. |
| Change follow-up issue creation default | `followup.proposalPolicy`, `followup.proposalApproval`, `followup.childIssuePolicy`, `followup.maxIssuesPerSource`, `followup.preferredWorkflowTemplates`, `followup.autoMaintainTemplates` | No repo-default CLI option; item-level follow-up commands can override source item proposal policy, proposal approval, category caps, template preferences, and template-maintenance mode, but not `childIssuePolicy` | Default proposal policy, approval behavior, planned child issue inheritance policy, category-specific maximum automatic follow-up issues per source, priority template hints, and whether missing/updated templates may be requested. Preferred templates are not an allowlist. |
| Change foreign input approval | `foreignIssueApprovalScope` | `--foreign-approval-scope` | `external_only` or `all_foreign`. |
| Change issue notes directory | `paths.issueNotes` | `-` | Repository-relative directory for temporary issue-scoped report or note artifacts. Default: `.alpaca/issue-notes`. |
| Change system prompt file paths | `paths.systemPrompts` | `-` | Repository-relative Markdown paths for optional system prompt overrides. |
| Change output language | `i18n.defaultLanguage` | `-` | `en`, `ja`, or `zh`. |
| Change display and schedule time zone | `i18n.displayTimeZone` | `-` | IANA time zone for displayed times and schedule inputs without explicit offsets. See `alpaca docs show scheduling`. |
| Change repository provider | `repositoryHost.kind` | `-` | `github`, `gitea`, or `gitlab`. |
| Change repository project | `repositoryHost.projectRef` | `-` | Repository project reference. |
| Change Git remote | `repositoryHost.remoteName` | `-` | Git remote used for clone, fetch, checkout, and push. |
| Change base branch | `repositoryHost.baseBranch` | `--base-branch` | Default base branch for top-level workflow state and pull-request merge targets. Some child issues branch from the parent issue branch. |
| Change issue completion target | `issueCompletion.target` | `--issue-completion-target` or `/alpaca pr` | `pause_on_issue` or `pull_request`. CLI values use kebab-case plus `default`; `/alpaca pr` sets the target to `pull_request` and leaves PR policies at their effective defaults. |
| Change PR review policy | `issueCompletion.pullRequest.reviewPolicy` | `--pr-review` | `never`, `if_needed`, or `always`; CLI values use kebab-case plus `default`. |
| Change PR merge policy | `issueCompletion.pullRequest.mergePolicy` | `--pr-merge` | `manual` or `auto`; CLI values use kebab-case plus `default`. |
| Change default PR reviewers | `repositoryHost.pullRequest.defaultReviewers` | `--default-reviewers` | Default pull request reviewers. The CLI option can be repeated or comma-separated. |
| Change tracker provider | `ticketTracker.kind` | `-` | `github`, `gitea`, or `gitlab`. |
| Change tracker project | `ticketTracker.projectRef` | `-` | Issue and pull request tracker project reference. |
| Change comment reactions | `ticketTracker.commentReactions` | `-` | Tracker reaction names used when AlpacaLoop acknowledges actionable comments. Use `[]` to disable automatic reactions. |
| Change managed labels | `ticketTracker.workflowLabels` | `-` | Managed label names for queue state, needs-human reasons, cooldown, recurrence, scheduling, and follow-up requests. |
| Show or hide progress in titles | `ticketTracker.showStepProgressInTitles` | `-` | Whether active issue and pull request titles include progress markers. |
| Change default worker priority | `workers.default` | `--default-worker` | Config is the enabled default worker list in priority order; issue override selects one default worker. |
| Change thinking worker priority | `workers.thinking` | `--thinking-worker` | Optional thinking worker list in priority order; issue override selects one thinking worker. |
| Change polling interval | `pollIntervalSec` | `-` | Background service polling interval in seconds. |
| Change worker total timeout | `workerTimeoutSec` | `-` | Worker process total runtime timeout in seconds. |
| Change worker no-output timeout | `workerNoOutputTimeoutSec` | `-` | Worker process no-output timeout in seconds. Use `null` to disable the idle watchdog. |
| Change repo-wide worker slots | `parallelism.maxWorkers` | `-` | Repo-wide AI worker slot limit. |
| Change active issue limit | `parallelism.maxIssues` | `-` | Maximum active worker issues. Must be less than or equal to `parallelism.maxWorkers`. |
| Change worker slot allocation | `parallelism.mode` | `-` | `balance` or `greedy`. |
| Change AI run count limit | `aiRunLimits.maxRuns` | `--max-ai-runs` | Consecutive AI run count limit. `0` is allowed. |
| Change AI run hours limit | `aiRunLimits.maxHours` | `--max-ai-hours` | Total AI worker runtime hour limit. Use `null` in config or `off` in CLI options to disable it. |
| Change recurring overlap | `recurring.maxActiveChildren` | `--recurring-max-active-children` | Maximum open recurring child issues per recurring parent. Values are integers `>= 1`; use `default` in CLI options to inherit repo config. |
| Update recurring child titles after planning | `recurring.updateChildTitleAfterPlan` | `--recurring-update-child-title-after-plan` | Whether a recurring child issue title may be replaced with the planned work title after `workflow_plan`. Values are `true` or `false`; use `default` in CLI options to inherit repo config. |
| Change capacity cooldown fallback | `cooldownDefaultSecs.capacity` | `-` | Fallback cooldown seconds for temporary capacity or worker unavailability. |
| Change quota cooldown fallback | `cooldownDefaultSecs.quotaExhausted` | `-` | Fallback cooldown seconds for quota or rate-limit exhaustion. |
| Add repo-scoped publish hooks | `eventHooks` | `-` | Publish hooks that run after tracker changes are published. |
| Change nested workflow depth | `maxNestedWorkflowDepth` | `-` | Nested workflow template depth limit. `0` disables nested workflows. |

## Repository and Tracker

- `branchPrefix`: prefix for AI workspace branches. Default: `alpaca`. Empty segments and leading or trailing `/` are invalid.
- `repositoryHost.kind`: repository provider. Values: `github`, `gitea`, `gitlab`.
- `repositoryHost.projectRef`: repository project reference. Provider-specific URL and shorthand forms are normalized by provider resolution.
- `repositoryHost.remoteName`: Git remote used for clone, fetch, checkout, and push. Default from init is usually `origin`.
- `repositoryHost.baseBranch`: default base branch used when top-level issue workflow state is created. The stored base branch becomes that issue's pull-request merge target. Default from init is usually `main`. Controller children and ordinary unplanned children use the parent issue branch instead.
- `ticketTracker.kind`: tracker provider. Values: `github`, `gitea`, `gitlab`.
- `ticketTracker.projectRef`: tracker project reference. It can point at the same project as the repository or a separate tracker project.
- `customWorkers`: optional OpenAI-compatible custom worker definitions keyed by worker id.
- `workers`: object containing required `default` worker priority and optional `thinking` worker priority.
- `workers.default`: required enabled AI worker providers for ordinary work, in priority order. Values are built-ins (`codex`, `claude`) or ids from `customWorkers`. Default: `["codex"]`. Duplicates are rejected.
- `workers.thinking`: optional enabled AI worker providers for thinking-capable work, in priority order. Values are built-ins (`codex`, `claude`) or ids from `customWorkers`. Duplicates are rejected.

Ordinary execution, including workflow execution and worker event-hook runs, uses `workers.default`. Planning, workflow selection, workflow reconciliation, plan review, autofill, draft generation, template authoring, fit review, catalog worker selection, and event-hook drafts try `workers.thinking` first; when `workers.thinking` is omitted or unavailable, AlpacaLoop falls back to `workers.default` without duplicate worker attempts.

Custom worker ids must use lowercase kebab-case, for example `lmstudio-coder`. Reserved ids such as `codex`, `claude`, `default`, and `all` cannot be used. A custom worker entry has:

- `baseUrl`: required OpenAI-compatible API base URL.
- `model`: optional model id. Default: `default`.
- `apiKey`: optional Bearer-token shorthand.
- `headers`: optional string headers. Use `headers.Authorization` when the full auth header should be explicit.
- `requestParams`: optional JSON object shallow-merged into the OpenAI-compatible POST body after AlpacaLoop builds the request. It is not used for URL query parameters or headers.

`apiKey` and `headers.Authorization` cannot be set together. AlpacaLoop expands `${ENV_NAME}` only in `customWorkers.*.baseUrl`, `customWorkers.*.model`, `customWorkers.*.apiKey`, `customWorkers.*.headers.*`, and string values under `customWorkers.*.requestParams`. Missing env values make that custom worker unavailable so failover can try the next configured worker. Provider-specific `requestParams` must follow that provider's API contract; AlpacaLoop does not semantically validate them or convert them into query parameters.

## Git and Workspace Setup

AlpacaLoop uses native Git. Do not store Git usernames, emails, tokens, or passwords in `alpaca.config.json`; it is repository-tracked and shared by every contributor.

For Bot commits from the background service, set machine-local environment variables instead:

```bash
export ALPACA_GIT_USER_NAME="AlpacaLoop Bot"
export ALPACA_GIT_USER_EMAIL="bot@example.com"
```

These values are captured by the first `alpaca service enable`. If they change after the service exists, run `alpaca service enable --refresh-env` or `alpaca service restart --refresh-env`.

Repository credentials stay outside config. GitHub uses `ALPACA_GITHUB_TOKEN` or `gh auth token`; GitLab uses `ALPACA_GITLAB_TOKEN` or Git credentials; Gitea uses `ALPACA_GITEA_USERNAME` and `ALPACA_GITEA_PASSWORD` or Git credentials.

`git.hooks` defaults to `publish`. Use `publish_and_worker` when worker commits and pushes should run repository hooks such as Lefthook-managed pre-commit or pre-push hooks. Use `off` when AlpacaLoop should suppress repository hooks for publish and worker Git operations.

`workspaces.setupCommand` is for installing or syncing dependencies inside issue workspaces before worker execution. AlpacaLoop does not symlink `node_modules`, `vendor`, virtualenvs, or other dependency directories. Use `setupFrequency: "when_changed"` with `setupWatchPaths: "auto"` for most repositories. `once` runs after the first successful setup, and `always` runs before every worker attempt. Explicit `setupWatchPaths` values must be repo-relative files or directories without `.` or `..` path segments; missing explicit paths create issue-log warnings but do not fail setup. A failed setup redacts likely secrets from stdout/stderr logs, does not update the last-successful setup metadata, stops before worker launch, and hands the issue back for human repair without counting an AI run.

Example:

```json
{
  "customWorkers": {
    "lmstudio-coder": {
      "baseUrl": "http://localhost:1234/v1",
      "model": "qwen2.5-coder:14b"
    },
    "openrouter-sonnet": {
      "baseUrl": "https://openrouter.ai/api/v1",
      "model": "anthropic/claude-sonnet-4.5",
      "headers": {
        "Authorization": "Bearer ${OPENROUTER_API_KEY}"
      },
      "requestParams": {
        "provider": {
          "allow_fallbacks": false
        }
      }
    }
  },
  "workers": {
    "default": ["lmstudio-coder"],
    "thinking": ["openrouter-sonnet", "codex"]
  }
}
```

AlpacaLoop does not start, pull, or manage local models. Ollama, LM Studio, and remote routers must expose an OpenAI-compatible endpoint before AlpacaLoop can use them. Custom workers run through the Pi SDK and require Node.js `>=22.19.0` at runtime. Do not add `customWorkers.*.mcp`; MCP for custom workers is handled internally through `pi-mcp-adapter` using `.mcp.json` and `.pi/mcp.json` project config. Worker-specific Pi files, `alpaca skill install --for <custom-worker>` installs, and MCP metadata cache live under `~/.alpaca/pi-workers/<worker-id>/`.

## Language and Paths

- `i18n.defaultLanguage`: default language for CLI text, managed comments, and worker-generated human-facing text. Values: `en`, `ja`, `zh`. When the whole `i18n` object is omitted, the default is `en`; when `i18n` is present, `defaultLanguage` is required.
- `i18n.displayTimeZone`: IANA time zone used for displayed times and schedule inputs without explicit offsets. Default: `UTC`. Run `alpaca docs show scheduling` for schedule input behavior.
- `paths.issueNotes`: repository-relative directory for temporary issue-scoped report and note artifacts. Default: `.alpaca/issue-notes`. Workers should use concise issue comments for short one-off reports, use this directory for longer temporary issue-scoped reports with `issue-<issue-number>-<slug>.md` names, and create durable project documentation only when the issue asks for it or the result should become project knowledge.
- `paths.systemPrompts`: optional map from known system prompt names to repo-relative Markdown paths. Configured paths override `.alpaca/system-prompts/<name>.md`, then packaged defaults.

Known system prompt names are `worker-common`, `issue-create`, `workflow-create`, `event-hook-create`, `workflow-common`, `workflow-planning`, `workflow-plan-review`, `workflow-execution`, `workflow-closing`, `pull-request-review-necessity`, `followup-recommendation-guidance`, `human-handoff`, and `merge-guidance`. Use configured paths when prompt guidance should live somewhere other than `.alpaca/system-prompts/`; otherwise prefer `alpaca eject system-prompts` so the default override location stays predictable.

Changing language or label names does not migrate existing tracker comments, issues, or labels.

## Approvals and Autofill

- `approvals.workflowStart.newPlan`: start approval mode for a new workflow plan. Values: `auto`, `confirm`, `conservative`, `aggressive`. Default: `auto`.
- `approvals.workflowStart.replan`: start approval mode for replans. Values are the same as `newPlan`. Default: `auto`.
- `approvals.workflowStart.scope`: where start approval applies. `issue_only` excludes pull request threads; `issue_and_pr` applies to issues and pull requests. Default: `issue_and_pr`.
- `approvals.requirementsSetup.skills`: missing required skill behavior. `auto` creates or reuses setup work automatically; `confirm` hands off for human approval. Default: `auto`.
- `approvals.requirementsSetup.mcp`: missing required MCP behavior. Values: `auto`, `confirm`. Default: `auto`.
- `foreignIssueApprovalScope`: approval scope for non-assignee input. `external_only` gates outside collaborators; `all_foreign` gates all non-assignee input. Default: `all_foreign`.
- `aiWorkflowOptionAutofill`: AI autofill for workflow options from issue bodies and fresh comments. Values: `off`, `on`. Default: `on`.

`confirm` start approval publishes the plan and waits for `/alpaca start` or `alpaca issue start --issue <id>`. `conservative` and `aggressive` let the worker decide whether the plan can start automatically based on the requested policy.

Internal `revise_plan` passes keep the original pending start-approval intent. A pending new-plan approval continues to use `newPlan`; a pending replan approval continues to use `replan`.

`aiWorkflowOptionAutofill: on` can infer workflow options from finalized issue text and fresh actionable comments. Explicit `/alpaca ...` comments and explicit `issue create` options remain higher priority and clearer for humans.

## Automatic Reviews

- `autoReviews.plan.maxRevisions`: maximum number of internal planner revision passes after automated workflow plan review returns `request_revision`. Default: `1`; values must be integers `>= 1`.

Workflow plan review runs after top-level `workflow_plan` drafts and before execution or start approval. When review returns `use_plan`, AlpacaLoop continues with the candidate plan. When review returns `request_revision`, AlpacaLoop feeds the structured review findings back into the existing planner as a `revise_plan` or `replan` pass, up to `autoReviews.plan.maxRevisions`. The review revision itself does not force start approval; `auto`, `confirm`, `conservative`, and `aggressive` keep using the configured start-approval behavior for the resulting plan. A blocking review, or an exhausted revision budget with blocker findings, hands off to a human.

During plan review, AlpacaLoop may use bounded read-only capability catalog commands to check capability-sensitive steps and request a plan revision when work should use an available skill/MCP, route through skill/MCP resolution, or explain why no specialized capability is needed.

## Workflow Template Defaults

- `workflowTemplateDefaults.issue`: default selector for issue workflows. Default: `auto_select`.
- `workflowTemplateDefaults.pull_request`: default selector for pull request workflows. Default: `auto_select`.
- `workflowTemplateDefaults.unplanned`: default selector for unplanned child workflows. Default: `auto_select`.

Values are `auto`, `auto_select`, `no_template`, or a workflow template path. `auto` may request a missing reusable template during workflow selection. `auto_select` only chooses an existing auto-selectable candidate or `no_template`; when no candidates exist, AlpacaLoop stores `no_template` without a `workflow_select` worker run. `no_template` resolves to the target's built-in system default workflow. These defaults choose templates only; follow-up issue creation is controlled by follow-up proposal policy, approval behavior, and labels.

## Follow-up Defaults

- `followup.proposalPolicy`: default follow-up proposal generation policy for newly created or newly materialized workflow state. Values: `off`, `if_needed`, or `always`. Default: `if_needed`.
- `followup.proposalApproval`: default follow-up proposal approval behavior. Values: `auto`, `confirm`, or `confirm_if_needed`. Default: `auto`.
- `followup.childIssuePolicy`: follow-up proposal inheritance for planned `child_issue` issues created from a parent plan. Default: `inherit`.
- `followup.maxIssuesPerSource`: maximum automatic follow-up issues AlpacaLoop can create from one completed source item by category. Default: `{ mainWork: 2, maintenance: 2 }`.
- `followup.preferredWorkflowTemplates`: priority follow-up template candidates shown first in the automatic recommendation prompt. Values are workflow template paths or `no_template`; this is not an allowlist.
- `followup.autoMaintainTemplates`: when `true`, follow-up issue workflow selection may request missing or improved templates through the normal `auto` selector. When `false`, follow-up issue workflow selection uses `auto_select`. Default: `false`.

`followup.proposalPolicy` controls whether `workflow_closing` should produce follow-up recommendations. `off` disables recommendation generation by default, `if_needed` asks the worker to recommend only independently useful post-completion work, and `always` always requests follow-up proposal generation after completion. `followup.proposalApproval` controls publication: `auto` publishes recommended items immediately, `confirm` always posts a proposal comment first, and `confirm_if_needed` lets the worker mark individual recommendation items for confirmation. Existing canonical workflow state keeps its stored follow-up state; changing this config does not migrate existing issues.

`followup.childIssuePolicy` values are `inherit` or `off`. `inherit` copies only the parent issue's `proposalPolicy` and `proposalApproval` into newly created planned `child_issue` workflow state, not previous follow-up publications, proposals, or recommendations. `off` disables follow-up on those newly created planned child issues. Existing child issues keep their stored follow-up state.

`followup.maxIssuesPerSource.mainWork` and `followup.maxIssuesPerSource.maintenance` are integers from `0` to `5`. `mainWork` limits follow-up items that continue the source issue's main requested work after close. `maintenance` limits follow-up items that improve reusable workflow, prompt, skill, MCP, Codex/Claude, or worker-environment behavior. These caps only limit automatic worker recommendations that are being published immediately; explicit label approval of a pending proposal and `alpaca issue followup` requests still publish one follow-up issue per request. Set both values to `0` to record automatic recommendations as skipped without creating issues. Use `/alpaca --followup-max-main-work-issues <0..5|default>` and `/alpaca --followup-max-maintenance-issues <0..5|default>` to override these caps for one source item.

## Runtime Limits

- `pollIntervalSec`: background service polling interval in seconds. Default: `60`. Execution ownership expiry is also derived from this interval.
- `workerTimeoutSec`: worker process total runtime timeout in seconds. Default: `3600`. This is a repository-level runtime setting, not an issue-level workflow option; use `alpaca docs show service-runtime` for timeout diagnosis.
- `workerNoOutputTimeoutSec`: worker process no-output timeout in seconds. Default: `600`. Use `null` to disable the idle watchdog for workers that can legitimately run without stdout or stderr for a long time.
- `parallelism.maxWorkers`: repo-wide AI worker slot limit. Default: `4`.
- `parallelism.maxIssues`: maximum active worker issues. Default: `4`. It must be less than or equal to `parallelism.maxWorkers`.
- `parallelism.mode`: worker slot allocation mode. `balance` spreads slots across runnable issues; `greedy` gives earlier issues more slots when they have ready work. Default: `balance`.
- `aiRunLimits.maxRuns`: consecutive AI run count limit. Default: `30`. `0` is allowed and causes immediate human handoff when the limit check applies.
- `aiRunLimits.maxHours`: total AI worker runtime hour limit. Default: `5`. Decimal hours are allowed. `null` disables the hour limit.
- `recurring.maxActiveChildren`: maximum open recurring child issues per recurring parent. Default: `1`. Increase this to let recurring parents create overlapping child issues before previous children close.
- `recurring.updateChildTitleAfterPlan`: whether a recurring child issue can update its tracker title from the worker's planned issue title after `workflow_plan`. Default: `false`. Recurring child creation forces this override to `true` on the child workflow state only, preserving the recurring prefix, run timestamp, and parent suffix.
- `cooldownDefaultSecs.capacity`: fallback cooldown seconds for temporary capacity or worker unavailability without a retry time. Default: `900`.
- `cooldownDefaultSecs.quotaExhausted`: fallback cooldown seconds for quota or rate-limit exhaustion without a retry time. Default: `3600`.
- `maxNestedWorkflowDepth`: nested workflow template depth limit. Default: `5`. `0` disables nested workflows.

When `aiRunLimits.maxRuns` or `aiRunLimits.maxHours` is reached, automatic execution stops and the issue is handed off for human input.

Recurring settings are defaults for recurring parents. Run `alpaca docs show scheduling` for one-shot schedules, recurring cadences, first-run controls, and auto-stop behavior.

## Pull Requests

- `issueCompletion.target`: where work goes after `workflow_closing` confirms source issue completion. Values: `pause_on_issue` or `pull_request`. Default: `pull_request`.
- `issueCompletion.pullRequest.reviewPolicy`: whether AlpacaLoop runs a PR-local review workflow after creating or reusing the pull request. Values: `never`, `if_needed`, or `always`. Default: `if_needed`.
- `issueCompletion.pullRequest.mergePolicy`: whether AlpacaLoop attempts automatic merge after PR completion gates pass. Values: `manual` or `auto`. Default: `auto`.
- `repositoryHost.pullRequest.defaultReviewers`: default pull request reviewers. Default: `[]`.

`pause_on_issue` stops on the issue for human review before service cycles move to the pull request; fresh issue comments replan on the issue. Users can later comment `/alpaca pr` to move the item to pull request handling. `pull_request` creates or reuses a pull request and continues there. `reviewPolicy=always` always creates the PR review workflow. `reviewPolicy=if_needed` asks the worker to skip only low-risk, narrow, sufficiently proven changes and to review changes with security, data, dependency, workflow, production, broad-scope, unresolved-comment, or test-risk signals. `reviewPolicy=never` skips PR review. `mergePolicy=manual` stops for human review after PR work is ready. `mergePolicy=auto` attempts automatic merge when all AlpacaLoop and host merge conditions pass.

These settings do not bypass branch protection or required host reviews; if the host rejects a merge, AlpacaLoop follows the existing merge failure and human handoff path.

Issue-level workflow options can override PR automation for a specific issue or pull request.

In `/alpaca` comments and `alpaca issue create` options, issue completion target values use kebab-case, for example `pull-request`. In `alpaca.config.json`, target values use snake_case, for example `pull_request`.

## Dependencies

- `dependencies.strategy`: dependency automation strategy. Values: `none`, `auto`, `block`, `parallel_comment`. Default: `auto`.

`none` skips dependency synchronization. `block` uses tracker blockers. `parallel_comment` records dependency metadata and comments without tracker blockers. `auto` lets AlpacaLoop manage dependencies and requeue work after dependency completion.

## Labels

- `ticketTracker.commentReactions`: tracker reaction names, not literal emoji characters, used when AlpacaLoop acknowledges actionable comments. Default: `["eyes", "+1", "heart"]`. Supported values: `eyes`, `+1`, `heart`, `hooray`. Use `[]` to disable automatic reactions.
- `ticketTracker.workflowLabels`: managed tracker label names for queue state, needs-human reasons, cooldown, recurrence, scheduling, and follow-up requests. This object is required in hand-written config files.
- `ticketTracker.showStepProgressInTitles`: whether active issue and pull request titles include progress markers. Default: `true`.

Within `ticketTracker.workflowLabels`, `aiReady`, `aiRunning`, `aiNeedsHuman`, and `aiDisabled` are required. Other label keys default when omitted.

| Key | Default |
| --- | --- |
| `aiReady` | `AI: Ready` |
| `aiRunning` | `AI: Running` |
| `aiNeedsHuman` | `AI: Needs Human` |
| `aiWorkingInPr` | `AI: Working in PR` |
| `aiDisabled` | `AI: Disabled` |
| `aiRecurring` | `AI: Recurring` |
| `aiScheduled` | `AI: Scheduled` |
| `aiQuestion` | `AI: Question` |
| `aiRunLimit` | `AI: Run Limit` |
| `aiCoolingDown` | `AI: Cooling Down` |
| `aiFollowUp` | `AI: Follow-up` |

Blank label names and duplicate label names after trimming are rejected. Changing configured names does not rename existing tracker labels. Run `alpaca labels sync` after changing labels so missing configured labels are created.

## Event Hooks

- `eventHooks`: repo-scoped publish hooks. Default: `[]`.

Each repo-scoped hook has a repository-relative `path`, an `on` trigger list, and an optional `runner`. User-scoped personal hooks are configured outside `alpaca.config.json`.

Use `alpaca docs show event-hooks` for event hook setup and behavior.

## Related Docs

- `alpaca docs show quick-start`
- `alpaca docs show install`
- `alpaca docs show setup`
- `alpaca docs show service-runtime`
- `alpaca docs show scheduling`
- `alpaca docs show workflow-options`
- `alpaca docs show follow-up`
- `alpaca docs show publishing`
- `alpaca docs show event-hooks`
- `alpaca docs show workflow-state`
