# AlpacaLoop

Turn issue-tracker goals into visible, controlled AI coding workflows.

[English](README.md) | [日本語](README.ja.md) | [简体中文](README.zh.md)

![AlpacaLoop workflow banner](https://unpkg.com/alpacaloop/assets/alpacaloop-readme-workflow.png)

[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![Status: early release](https://img.shields.io/badge/status-early_release-blue.svg)](package.json)
[![GitHub](https://img.shields.io/badge/github-alpacaloop%2Falpacaloop-24292e.svg?logo=github)](https://github.com/alpacaloop/alpacaloop)

AlpacaLoop is a provider-neutral issue and pull request control plane for AI coding workers. It lets engineering teams describe work in GitHub, Gitea, or GitLab issues, then keeps the worker's plan, progress, blockers, handoffs, and follow-up attached to the tracker instead of trapped in a one-off chat.

Use it when you want Codex, Claude, or an OpenAI-compatible custom worker to work inside a repository process your team can inspect, pause, resume, and review.

**Start here:** install the CLI, connect one repository, and create a first managed issue from the [Quick Start](#quick-start).

AlpacaLoop is an early release. It is usable today, but APIs and behavior may change before 1.0.

## Why Teams Use AlpacaLoop

AI coding works better when the worker has durable context, visible state, and a clear stopping point. AlpacaLoop focuses on that operating loop:

- **Keep work in the tracker.** Issues remain the source of truth for goals, constraints, status, and follow-up.
- **Make progress reviewable.** Managed comments, labels, logs, blockers, dependencies, and handoffs show what the worker is doing and why.
- **Reuse repository process.** Workflow templates in `.alpaca/workflows/*.md` can guide planning, execution, review, unplanned work, follow-up, and improvement.
- **Choose foreground or service runs.** Run one issue manually from the CLI, then enable the background service when continuous polling is the right fit.
- **Preserve human control.** AlpacaLoop stops for required input, approvals, unclear decisions, setup problems, secrets, and OAuth browser sign-ins.

## What It Does

AlpacaLoop connects a repository and tracker, runs a configured AI coding worker, and projects the workflow state back into the issue.

1. `alpaca init` creates or updates `alpaca.config.json`, registers the repository for service management, installs repo-local Alpaca skill assets, and resolves initial worker sign-in readiness.
2. A tracker issue supplies the goal, context, constraints, and done criteria.
3. Workflow templates guide the worker through the next step.
4. AlpacaLoop runs the selected configured worker and validates the returned workflow contract.
5. Labels and managed comments make status, blockers, dependencies, and next actions visible in the tracker.

AlpacaLoop does not replace code review, CI, release management, or human product judgment.

## Install

macOS and Linux:

```bash
curl -fsSL https://raw.githubusercontent.com/alpacaloop/alpacaloop/main/install.sh | bash
```

The installer checks Node.js, installs the AlpacaLoop CLI, and prints the next setup step. AlpacaLoop uses native Git; default installs require `git`, `npm`, and Node.js `>=22.19.0`.

To let the installer add missing Node.js tooling through `fnm`:

```bash
curl -fsSL https://raw.githubusercontent.com/alpacaloop/alpacaloop/main/install.sh | bash -s -- --install-deps
```

On Linux and WSL2, prefer a user-writable npm prefix such as fnm/nvm-managed Node.js. Some distro Node.js packages install `node` without `npm`; install `npm` too, or run the installer with `--install-deps`. If global `npm install -g` fails with EACCES, fix the npm prefix rather than running AlpacaLoop setup with sudo.

The current npm registry beta channel is available as:

```bash
npm install -g alpacaloop@beta
```

The default npm install uses the `latest` dist-tag, which may lag the beta channel until a stable promotion:

```bash
npm install -g alpacaloop
```

For an unreleased source install from `main`, use the Git URL:

```bash
npm install -g 'git+https://github.com/alpacaloop/alpacaloop.git#main'
```

The primary installed command is `alpaca`. The package also exposes `alpacaloop`, and tracker comments use `/alpaca`.

For CLI help:

```bash
alpaca --help
alpaca <command> --help
alpaca docs list --with-description
alpaca docs show quick-start
```

## Quick Start

Use this path for the first safe evaluation: install the CLI, connect one repository, create one managed issue, run one foreground cycle, inspect the result, and then decide whether to enable the background service.

Before you start, make sure you have:

- a Git repository connected to GitHub, Gitea, or GitLab
- tracker credentials for that provider
- at least one Codex or Claude worker sign-in, or an OpenAI-compatible custom worker endpoint configured in `customWorkers`
- a first goal that can be expressed as an issue

### 1. Sign in a worker

`alpaca init` may prompt for worker sign-in. You can also do it first:

```bash
alpaca auth setup
```

For supported worker sign-in methods, including API key environment variable fallbacks, run:

```bash
alpaca docs show setup
```

Custom workers do not use `alpaca auth setup`; configure their OpenAI-compatible endpoint and any `${ENV}` secrets in `alpaca.config.json`.

Example custom worker configuration:

```json
{
  "customWorkers": {
    "kimi-k2": {
      "baseUrl": "https://api.moonshot.ai/v1",
      "model": "kimi-k2.6",
      "apiKey": "${MOONSHOT_API_KEY}",
      "requestParams": {
        "thinking": { "type": "disabled" }
      }
    }
  },
  "workers": {
    "default": ["kimi-k2"],
    "thinking": ["kimi-k2", "codex"]
  }
}
```

`apiKey` is a Bearer auth shorthand. Use `headers.Authorization` only when you need to provide the full header value; setting both is invalid. `requestParams` is shallow-merged into the OpenAI-compatible POST body after AlpacaLoop builds the request; it is not used for URL query parameters or headers. Provider-specific fields follow that provider's API contract and are not semantically validated by AlpacaLoop. Custom workers use OpenAI-compatible endpoints only. AlpacaLoop does not start, download, or manage local models. Repo skills are loaded from `.agents/skills` and `skills`, and custom worker MCP servers are read from `.mcp.json` or `.pi/mcp.json` through the Pi MCP adapter.

### 2. Connect the repository

GitHub:

```bash
export ALPACA_GITHUB_TOKEN=...
# Or use gh auth login for local CLI credentials.

alpaca init
alpaca doctor
```

Gitea:

```bash
export ALPACA_GITEA_USERNAME=...
export ALPACA_GITEA_PASSWORD=...

alpaca init --repo-provider gitea
alpaca doctor
```

GitLab:

```bash
export ALPACA_GITLAB_TOKEN=...
# Use a token with project access.

alpaca init
alpaca doctor
```

`alpaca doctor` is the first setup health check. It validates config, worker availability, sign-in state, cooldowns, managed labels, repo registration, remote base branch availability, and workflow template health.
The configured remote base branch must exist before the first managed issue or service run. If `doctor` reports it missing, push the branch with `git push <remote> HEAD:<base-branch>` or rerun `alpaca init --base-branch <existing-branch>`.

Do not put Git usernames, emails, tokens, or passwords in `alpaca.config.json`; it is tracked in the repository. For background service Bot commits, set machine-local env 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 you change them after the service already exists, run `alpaca service enable --refresh-env` or `alpaca service restart --refresh-env`.

Worker dependency setup can be configured with `workspaces.setupCommand`; see `alpaca docs show config`.

### 3. Create the first managed issue

For review before anything is posted to the tracker, save a local draft first and then apply that reviewed draft:

```bash
alpaca issue create --prompt "Fix flaky login tests." --save-draft
alpaca issue create --apply-draft ~/.alpaca/drafts/.../issue-create-....json
```

For immediate creation:

```bash
alpaca issue create --prompt "Fix flaky login tests."
```

Normal unscheduled issues receive the `AI: Ready` queue label. Scheduled, recurring, or disabled issue options use different queue states. For schedule and recurring behavior, run `alpaca docs show scheduling`. For label details, run:

```bash
alpaca docs show workflow-state
```

### 4. Run one foreground cycle

Process the new issue manually before enabling continuous polling:

```bash
alpaca run --issue 123
```

Do not run `alpaca run` while the background service is enabled. If you need a general one-cycle run, inspect the options first:

```bash
alpaca run --help
```

### 5. Inspect the result

Use these commands as the first-run success check:

```bash
alpaca issue list --days 7 --limit 10
alpaca issue show --issue 123 --children 1 --limit 5
alpaca issue log show --issue 123 --tail 50
```

Add `--me` to `issue list` when you only want issues assigned to the authenticated tracker user. Repeat `--assignee <login>` to inspect specific assignees.

If the issue is no longer `AI: Ready`, read the visible status first. `AI: Running` means a run or accepted continuation is in progress, `AI: Needs Human` means human input is required, and `AI: Working in PR` means work moved to a pull request. The PR handoff comment on the source issue links to the pull request so review can continue there.

### 6. Enable background polling

After foreground runs are understood, enable the service and confirm that it is registered and polling:

Linux and WSL2 service mode requires a working systemd user session (`systemctl --user`). WSL2 support assumes systemd is enabled; without it, keep using foreground `alpaca run`.

```bash
alpaca service enable
alpaca service status
alpaca service log show --tail 50
```

Run `alpaca service enable` again after changing Node/npm managers or the global install path. It refreshes the service definition to the `alpaca` command you are using while preserving the stored service environment. Use `alpaca service enable --refresh-env` or `alpaca service restart --refresh-env` only when you want the current shell environment to replace the stored service environment.

The background service detects installed AlpacaLoop package version changes and restarts after current service work finishes.

Disable the service before returning to manual `alpaca run`:

```bash
alpaca service disable
```

## Workflow Templates

Workflow templates let a repository describe how AlpacaLoop should handle repeatable classes of work. They live under `.alpaca/workflows/*.md`, and packaged system workflows are available under `__system/`.

Inside a template, use `@workflow <template-path>` only when the referenced template should become a separate nested workflow step during planning. If the current workflow only needs reference guidance from another workflow document, mention the `.alpaca/workflows/...md` path in prose instead.

Before deleting or moving a template, inspect inbound references with `alpaca workflow list --references-to <template.md>`. `alpaca workflow delete --path <template.md>` deletes repo-local templates only and blocks while references remain; `--cleanup-references --save-draft` prepares reviewed cleanup updates for editable referring templates without cascade-deleting other templates.

Workflow selection accepts `auto`, `auto_select`, `no_template`, or a template path. `auto` asks the worker to choose whether to use an auto-selectable template candidate, use the built-in default workflow through `no_template`, or request that a missing reusable template be prepared. `auto_select` only chooses an existing candidate or `no_template`; when no candidates exist, AlpacaLoop falls back to `no_template` without a `workflow_select` worker run and uses the target's built-in default workflow. When a candidate template is used, AlpacaLoop runs a fit review before planning; if the selected template narrows or conflicts with the parent request, it creates a blocking `workflow-template-fit` setup issue to prepare a better reusable template. Template requests create or reuse blocking setup issues during normal runs, including issues created from prompt-mode drafts with unresolved auto/auto_select workflow selection.

Use `alpaca eject workflows` to copy packaged system workflows, including the `no_template` defaults, to `.alpaca/workflows/__system/` for repository-local override.

Follow-up workflows create or reuse separate issues after the source issue or PR finishes. The repo defaults are `followup.proposalPolicy` (`off`, `if_needed`, or `always`), `followup.proposalApproval` (`auto`, `confirm`, or `confirm_if_needed`), `followup.childIssuePolicy` (`inherit` or `off`, default `inherit` for planned child issues), `followup.maxIssuesPerSource` (`{ mainWork: 2, maintenance: 2 }` by default), `followup.preferredWorkflowTemplates`, and `followup.autoMaintainTemplates`. Automatic recommendations classify items as `mainWork` for the source issue's main requested work that should continue after close, or `maintenance` for workflow, prompt, skill, MCP, Codex/Claude, or worker-environment improvements. Auto follow-up publication requires a fresh `workflow_closing` audit; during PR merge finalization, AlpacaLoop synchronizes a source or base workspace and verifies the PR head or merge commit before publishing recommendations, otherwise it stops automatic follow-up creation and asks for human review. Use `/alpaca --followup-proposal if_needed` to enable completion-time judgment, `--followup-proposal always` to always propose follow-up work, `--followup-proposal off` to disable it, and `--followup-proposal-approval <auto|confirm|confirm_if_needed|default>` to control whether proposed items become issues immediately or wait for a confirmation comment. When a pending proposal is approved, human comments added after the proposal are applied by a review worker first, so users can ask to add, revise, or remove candidates before adding the `AI: Follow-up` label. `alpaca issue followup --issue <id> --prompt <text>` creates an independent follow-up issue immediately and stores the request in that issue body; timing or cadence in the prompt can be picked up by normal setup/autofill. `--followup-preferred-workflow-template <path|no_template[,path...]|default>` adds priority candidates to the recommendation prompt only; it is repeatable, accepts comma-separated values, is not an allowlist, and does not force issue creation. `--followup-max-main-work-issues <0..5|default>` and `--followup-max-maintenance-issues <0..5|default>` override the automatic follow-up category caps for one source item. `autoMaintainTemplates: true` lets created follow-up issues use the `auto` selector path that can request missing or improved templates; the default `false` uses `auto_select`. Adding the `ticketTracker.workflowLabels.aiFollowUp` label, default `AI: Follow-up`, approves a pending proposal when one exists, otherwise it is treated as an explicit follow-up request.

Use them after the basic issue path is working. To ask AlpacaLoop to create or refresh reusable templates for the repository, create a managed issue bound to the packaged workflow maintenance system workflow:

```bash
alpaca issue create --prompt "This repository is a TypeScript CLI for task automation. Create reusable workflows for bug fixes, PR reviews, unplanned maintenance, and follow-up work." --workflow __system/workflow-maintenance.md --pr-workflow no_template --unplanned-workflow no_template --followup-proposal off
```

Use the normal `issue create` scheduling and worker options, including `--default-worker` and `--thinking-worker`, when workflow maintenance should recur or use a specific worker route.

Before writing or editing templates directly, read:

```bash
alpaca docs show workflow-template-authoring
```

Service automation reads workflow templates and system prompt files from the configured base branch. After local workflow edits need to become visible to automation, publish the workflow path:

```bash
alpaca publish --path .alpaca/workflows
```

For local system prompt edits, publish the system prompt path:

```bash
alpaca publish --path .alpaca/system-prompts
```

Repository system prompts can tune worker conventions, workflow planning/review, current-step execution, final `workflow_closing` completion reports and close audits, issue/template/event-hook authoring, human handoff style, follow-up recommendation guidance, and merge integration preferences without changing control-plane schemas or safety rules.

## Useful Docs

AlpacaLoop ships CLI-readable reference docs:

```bash
alpaca docs list --with-description
alpaca docs search <query>
alpaca docs search <query> --view headings
```

`skill search` and `skill install --search` use installed inventory, repo/system catalog files, and provider marketplaces. `mcp search` and `mcp install --search` use installed inventory and MCP catalog files. They do not query GitHub registry metadata at runtime. MCP catalog entries without `servers` are discovery-only search leads; add a reviewed server spec and `setup.safeAutoInstall: true` before using `mcp install`.

Use `alpaca capability list/search` for cross-type skill and MCP discovery before choosing workflow requirements. Compare candidates by purpose fit, target narrowness, source trust, and quality signals such as stars, updatedAt, and createdAt. Prefer a usable skill only when skill and MCP options satisfy the same need equally well; choose MCP when it is the better fit or live service/API/resource/server/tool access is required. Candidates excluded from workflow requires are hidden by default; use `--include-excluded` only when investigating the reason.

Useful starting topics:

| Topic | Use it for |
| --- | --- |
| `quick-start` | Shortest path from install to a first managed issue |
| `install` | CLI installation, requirements, and local checkout details |
| `setup` | Repository initialization, worker sign-in, and health checks |
| `issues` | Issue creation, search, inspection, approvals, follow-ups, logs, disable/enable, and unlocks |
| `scheduling` | One-shot schedules, recurring parent issues, first-run controls, and auto-stop behavior |
| `follow-up` | Independent post-completion follow-up issues |
| `service-runtime` | Background service behavior and foreground run boundaries |
| `workflow-state` | Labels, managed comments, workflow updates, and resume behavior |
| `workflow-template-authoring` | Rules for reusable workflow templates |
| `config` | Repository and service configuration |

For the full command reference:

```bash
alpaca help --all
man alpacaloop
```

## Development

Use this only when working on AlpacaLoop itself:

```bash
git clone https://github.com/alpacaloop/alpacaloop.git
cd alpacaloop
pnpm install
pnpm build
```

From a checkout, run the CLI with `pnpm alpaca ...`.

For contributor setup, checks, and documentation boundaries, see [CONTRIBUTING.md](CONTRIBUTING.md).

## License

MIT. See [LICENSE](LICENSE).
