### Install LoopTroop with Bun

Source: https://www.looptroop.ovh/docs

Install LoopTroop globally with Bun, then start it with `looptroop open`.

```bash
bun add -g looptroop
looptroop open
```

--------------------------------

### Install LoopTroop with pnpm

Source: https://www.looptroop.ovh/docs

Install LoopTroop globally with pnpm, then start it with `looptroop open`.

```bash
pnpm add -g looptroop
looptroop open
```

--------------------------------

### Install method check output

Source: https://www.looptroop.ovh/docs/diagnostics

Example output of the install-method check. It names the channel this copy was installed from and the exact command that upgrades it. The upgrade command is not interchangeable across installers.

```text
✓ install method  npm
  ↳ upgrade: npm install -g looptroop@latest
```

--------------------------------

### Install LoopTroop with curl

Source: https://www.looptroop.ovh/docs

Install LoopTroop on Unix-like systems using the official install script, then start it with `looptroop open`.

```bash
curl --proto "=https" --proto-redir "=https" --tlsv1.2 -fsSL https://www.looptroop.ovh/install | sh
looptroop open
```

--------------------------------

### Install LoopTroop with npm

Source: https://www.looptroop.ovh/docs

Install LoopTroop globally via npm, then start it with `looptroop open`. Recommended for Windows users.

```bash
npm install -g looptroop
looptroop open
```

--------------------------------

### Install LoopTroop with Homebrew

Source: https://www.looptroop.ovh/docs

Install LoopTroop via Homebrew tap, then start it with `looptroop open`.

```bash
brew install looptroop-ai/tap/looptroop
looptroop open
```

--------------------------------

### Install LoopTroop with Scoop

Source: https://www.looptroop.ovh/docs

Install LoopTroop via Scoop on Windows, then start it with `looptroop open`.

```powershell
scoop bucket add looptroop https://github.com/looptroop-ai/scoop-bucket
scoop install looptroop
looptroop open
```

--------------------------------

### Install LoopTroop with Yarn

Source: https://www.looptroop.ovh/docs

Install LoopTroop globally with Yarn (Bash/zsh syntax), then start it with `looptroop open`.

```bash
yarn global add looptroop
looptroop open
```

--------------------------------

### Installer script (Windows) - Install

Source: https://www.looptroop.ovh/docs/installation

One-line installer for Windows. The command is the PowerShell command above. Run it again to upgrade.

```powershell
PowerShell command above
```

--------------------------------

### Install LoopTroop with PowerShell

Source: https://www.looptroop.ovh/docs

Install LoopTroop on Windows using PowerShell and curl.exe, then start it with `looptroop open`. Requires curl.exe (included in current Windows 10/11).

```powershell
$script = curl.exe --proto "=https" --proto-redir "=https" --tlsv1.2 -fsSL https://www.looptroop.ovh/install.ps1; if ($LASTEXITCODE -ne 0 -or !$script) { throw "Installer download failed" }; & ([scriptblock]::Create(($script -join "`n")))
looptroop open
```

--------------------------------

### Scoop - Install and Upgrade

Source: https://www.looptroop.ovh/docs/installation

Install LoopTroop using Scoop on Windows. First add the bucket, then install. Upgrade with scoop update.

```shell
scoop bucket add looptroop https://github.com/looptroop-ai/scoop-bucket
```

```shell
scoop install looptroop
```

```shell
scoop update looptroop
```

--------------------------------

### PowerShell: Download and run the LoopTroop installer

Source: https://www.looptroop.ovh/docs/installation

Run in PowerShell to download and execute the official installer script from looptroop.ovh. The script throws if the download fails and then runs the installer with the -Binary flag to install the standalone executable.

```powershell
$script = curl.exe --proto "=https" --proto-redir "=https" --tlsv1.2 -fsSL https://www.looptroop.ovh/install.ps1; if ($LASTEXITCODE -ne 0 -or !$script) { throw "Installer download failed" }; & ([scriptblock]::Create(($script -join "`n"))) -Binary
```

--------------------------------

### Install LoopTroop standalone executable with installer script

Source: https://www.looptroop.ovh/docs/installation

Use this command to install the standalone executable into ~/.looptroop (unless you specify otherwise). The --binary flag selects the standalone executable, which carries its own Node runtime and does not need Node on the host to run.

```bash
curl --proto "=https" --proto-redir "=https" --tlsv1.2 -fsSL https://www.looptroop.ovh/install | sh -s -- --binary
```

--------------------------------

### Clone and run LoopTroop dev stack

Source: https://www.looptroop.ovh/docs/installation

Use this to develop LoopTroop from a source checkout. Starts the frontend, backend, and OpenCode watcher with hot reload; no need to start OpenCode manually. On first run it handles dependency installation and daily maintenance.

```bash
git clone https://github.com/looptroop-ai/LoopTroop.git
cd LoopTroop
npm run dev
```

--------------------------------

### npm - Install and Upgrade

Source: https://www.looptroop.ovh/docs/installation

Install or upgrade LoopTroop globally using npm.

```shell
npm install -g looptroop
```

```shell
npm install -g looptroop@latest
```

--------------------------------

### pnpm - Install and Upgrade

Source: https://www.looptroop.ovh/docs/installation

Install or upgrade LoopTroop globally using pnpm.

```shell
pnpm add -g looptroop
```

```shell
pnpm add -g looptroop@latest
```

--------------------------------

### Install Node 24 with nvm

Source: https://www.looptroop.ovh/docs/installation

Use this command to install the supported Node 24 line when using nvm, as pointed to by the current installer's help. It supplies the Node runtime required by the npm-based channels.

```bash
nvm install 24
```

--------------------------------

### Install LoopTroop with curl

Source: https://www.looptroop.ovh/docs/getting-started

One-line installer for curl. Requires Node 24.21.0+, npm 12.0.2+, git, and gh. Resolves the newest release, checks it against that release's checksum, and hands it to npm; never installs Node and never asks for sudo. Refuses insecure URLs or redirects.

```bash
curl --proto "=https" --proto-redir "=https" --tlsv1.2 -fsSL https://www.looptroop.ovh/install | sh
```

--------------------------------

### looptroop setup command with --yes flag

Source: https://www.looptroop.ovh/docs/cli

Attaches a project and opens the interface. Interactive mode offers folder-ignore modes; `--yes` accepts the configured choice, falling back to local if no saved profile. Requires a git repo with GitHub origin.

```bash
looptroop setup
looptroop setup --yes
```

--------------------------------

### Yarn Classic - Install and Upgrade

Source: https://www.looptroop.ovh/docs/installation

Install or upgrade LoopTroop globally using Yarn Classic (Bash/zsh commands).

```shell
yarn global add looptroop
```

```shell
yarn global upgrade looptroop@latest
```

--------------------------------

### Install LoopTroop with pnpm

Source: https://www.looptroop.ovh/docs/getting-started

Install LoopTroop globally via pnpm. Requires pnpm and Node 24.21.0+, git, and gh. pnpm will not resolve a tag to a version published in the last 24 hours.

```bash
pnpm add -g looptroop
```

--------------------------------

### AUR - Install and Upgrade

Source: https://www.looptroop.ovh/docs/installation

Install or upgrade LoopTroop from the AUR using yay or paru. Note that this command does not work yet because AUR registration is closed.

```shell
yay -S looptroop-bin
```

```shell
paru -S looptroop-bin
```

```shell
yay -Syu looptroop-bin
```

```shell
paru -Syu looptroop-bin
```

--------------------------------

### Homebrew - Install and Upgrade

Source: https://www.looptroop.ovh/docs/installation

Install or upgrade LoopTroop using Homebrew on macOS and Linux.

```shell
brew install looptroop-ai/tap/looptroop
```

```shell
brew upgrade looptroop
```

--------------------------------

### Open LoopTroop interface

Source: https://www.looptroop.ovh/docs/cli

Starts LoopTroop if it is not already running, then opens a signed-in link with a single-use code in the URL fragment. The fragment is never sent to a server, and sessions last 12 hours. Against a running daemon, it opens that one without starting a second.

```bash
looptroop open
```

--------------------------------

### Example bead JSON object

Source: https://www.looptroop.ovh/docs/beads

Shows the structure of a bead plan with fields like id, title, prdRefs, acceptanceCriteria, testCommands, dependencies, and targetFiles. Used as an example of a bead definition.

```json
{
  "id": "auth-refresh-token-rotation",
  "title": "Implement refresh-token rotation",
  "prdRefs": ["EPIC-AUTH", "STORY-SESSION-2"],
  "description": "Add refresh-token rotation and invalidation on reuse.",
  "contextGuidance": {
    "patterns": ["Reuse the existing session repository abstraction"],
    "anti_patterns": ["Do not introduce a second token storage format"]
  },
  "acceptanceCriteria": [
    "Refresh tokens rotate on successful refresh",
    "Reused refresh tokens invalidate the session family"
  ],
  "tests": [
    "Cover normal refresh flow",
    "Cover reused refresh token invalidation"
  ],
  "testCommands": [
    {
      "mode": "process",
      "program": "npm",
      "args": ["run", "test:server"],
      "cwd": ".",
      "env": {}
    }
  ],
  "priority": 3,
  "status": "pending",
  "issueType": "task",
  "externalRef": "AUTH-12",
  "labels": ["epic:auth", "story:sessions"],
  "dependencies": {
    "blocked_by": ["session-store-foundation"],
    "blocks": ["api-refresh-endpoint"]
  },
  "targetFiles": [
    "server/auth/sessionStore.ts",
    "server/routes/auth.ts"
  ],
  "failedIterationNotes": [],
  "userRetryNotes": [],
  "finalizationFailureNotes": [],
  "iteration": 1,
  "createdAt": "",
  "updatedAt": "2026-04-23T09:00:00.000Z",
  "completedAt": "",
  "startedAt": "",
  "beadStartCommit": null
}
```

--------------------------------

### Chocolatey - Install and Upgrade

Source: https://www.looptroop.ovh/docs/installation

Install or upgrade LoopTroop using Chocolatey on Windows. Note that Chocolatey reviews each submission, so releases may be delayed.

```shell
choco install looptroop
```

```shell
choco upgrade looptroop
```

--------------------------------

### WinGet - Install and Upgrade

Source: https://www.looptroop.ovh/docs/installation

Install or upgrade LoopTroop using WinGet on Windows. Upgrade requires stopping the service first. Note that WinGet manifests are reviewed via pull request, so releases may be delayed.

```shell
winget install LoopTroopAI.LoopTroop
```

```shell
looptroop stop
```

```shell
winget upgrade LoopTroopAI.LoopTroop
```

--------------------------------

### Verify build provenance attestation for release assets

Source: https://www.looptroop.ovh/docs/installation

Use these commands to verify the build provenance attestation for the release tarball and installer script. The attestation confirms the workflow, repository, and commit that produced the assets. Replace <version> with the actual version number.

```bash
gh attestation verify looptroop-<version>-linux-x64.tar.gz --repo looptroop-ai/LoopTroop
gh attestation verify install.sh --repo looptroop-ai/LoopTroop
```

--------------------------------

### Reserved indicator scalar repair example

Source: https://www.looptroop.ovh/docs/output-normalization

Shows a bad YAML snippet with plain scalars starting with backtick or @, and the fixed version where they are quoted. The repair wraps the scalars in double quotes.

```yaml
# Bad
question: `repo_git_mutex` behavior?
- @trace/span-id

# Fixed
question: "`repo_git_mutex` behavior?"
- "@trace/span-id"
```

--------------------------------

### Start LoopTroop as a service

Source: https://www.looptroop.ovh/docs/cli

Starts the LoopTroop daemon as a service, detaching from the terminal. The daemon keeps running after the shell closes and binds to 127.0.0.1:3000, serving both the interface and API from that address.

```bash
looptroop start
```

--------------------------------

### Check npm global binary directory on Windows

Source: https://www.looptroop.ovh/docs/installation

Run this command on Windows to find where npm places global binaries, which is typically %APPDATA%\npm. This is useful when a Node installation from an archive leaves npm's global directory off the PATH, causing 'looptroop' to not be recognized as a command even though the install succeeded.

```powershell
npm prefix -g                   # usually %APPDATA%\npm
```

--------------------------------

### Beads YAML example with testCommands

Source: https://www.looptroop.ovh/docs/prompts

Shows the required YAML structure for a bead item, including id, title, prdRefs, description, contextGuidance, acceptanceCriteria, tests, and testCommands. testCommands must be a list of CommandSpec objects with mode 'process' or 'shell'.

```yaml
beads:
  - id: "setup-db-schema"
    title: "Create database schema"
    prdRefs:
      - "EPIC-1"
      - "US-1-1"
    description: "Detailed technical implementation steps for this bead."
    contextGuidance:
      patterns:
        - "Use Drizzle ORM migrations."
      anti_patterns:
        - "Avoid raw SQL."
    acceptanceCriteria:
      - "Schema file exists and migrations run cleanly."
    tests:
      - "Unit test verifies table creation."
    testCommands:
      - mode: "process"
        program: "npm"
        args: ["run", "test", "--", "server/db"]
        cwd: "."
        env: {}

```

--------------------------------

### Remove LoopTroop install directory on Unix-like systems

Source: https://www.looptroop.ovh/docs/installation

Stop the daemon and remove the entire install directory. The standalone executable has no uninstall command; deleting only bin/ leaves other files behind.

```bash
looptroop stop
rm -rf ~/.looptroop
```

--------------------------------

### Session ownership tuple JSON

Source: https://www.looptroop.ovh/docs/opencode-integration

Example ownership tuple used to key session ownership in the project database. Includes ticketId, phaseAttempt, memberId, beadId, iteration, and step fields.

```json
{
  "ticketId": "AUTH-12",
  "phaseAttempt": 1,
  "memberId": null,
  "beadId": "api-refresh-endpoint",
  "iteration": 2,
  "step": null
}
```

--------------------------------

### looptroop doctor and which — identify running installation

Source: https://www.looptroop.ovh/docs/cli

Use `looptroop doctor` to name the channel and its upgrade command, and `which looptroop` to show which executable the shell runs. When two installations exist, PATH order decides which one answers.

```bash
looptroop doctor    # names the channel, and its upgrade command
which looptroop     # where the one your shell runs comes from
```

--------------------------------

### Linux/macOS: Verify checksum with grep and sha256sum

Source: https://www.looptroop.ovh/docs/installation

Verifies the downloaded Linux x64 tarball against the published checksums.sha256 by grepping for the specific file line. The example shows the command for linux-x64.

```bash
grep looptroop-<version>-linux-x64.tar.gz checksums.sha256 | sha256sum -c
```

--------------------------------

### Uninstall LoopTroop via npm

Source: https://www.looptroop.ovh/docs/installation

Use this command to uninstall LoopTroop when installed via npm (including the default installer script mode).

```bash
npm uninstall -g looptroop
```

--------------------------------

### Remove LoopTroop install directory on Windows PowerShell

Source: https://www.looptroop.ovh/docs/installation

Stop the daemon and remove the entire install directory. The standalone executable has no uninstall command; deleting only bin/ leaves other files behind.

```powershell
looptroop stop
Remove-Item -Recurse -Force "$env:USERPROFILE\.looptroop"
```

--------------------------------

### LoopTroop service commands

Source: https://www.looptroop.ovh/docs/operations

Commands to manage the installed LoopTroop background service: open, status, logs, restart, and stop. Use --json with status for scriptable output.

```bash
looptroop open       # starts it if it is not running, then opens a browser
looptroop status     # --json for a script
looptroop logs -f
looptroop restart
looptroop stop
```

--------------------------------

### Manage LoopTroop service: status, restart, stop

Source: https://www.looptroop.ovh/docs/cli

Commands to check the daemon status (including JSON output for scripts), restart the daemon (stop then start), and stop it. The `status --json` output includes an `update` object with version details and remains JSON-only even when an update is available.

```bash
looptroop status          # is it up?
looptroop status --json   # the same, for a script
looptroop restart         # stop, then start
looptroop stop
```

--------------------------------

### Uninstall LoopTroop via bun

Source: https://www.looptroop.ovh/docs/installation

Use this command to uninstall LoopTroop when installed via bun.

```bash
bun remove -g looptroop
```

--------------------------------

### Uninstall LoopTroop via WinGet

Source: https://www.looptroop.ovh/docs/installation

Use this command to uninstall LoopTroop when installed via WinGet.

```bash
winget uninstall LoopTroopAI.LoopTroop
```

--------------------------------

### YAML PRD output template with required keys

Source: https://www.looptroop.ovh/docs/prompts

Template for the expected PRD output. Use it to structure the YAML with the required top-level keys and nested fields. The example shows the required shape for epics, user stories, and verification commands.

```yaml
schema_version: 1
ticket_id: "PROJ-1"
artifact: "prd"
status: "draft"
source_interview:
  content_sha256: "<sha256>"
product:
  problem_statement: "..."
  target_users:
    - "..."
scope:
  in_scope:
    - "..."
  out_of_scope:
    - "..."
technical_requirements:
  architecture_constraints: []
  data_model: []
  api_contracts: []
  security_constraints: []
  performance_constraints: []
  reliability_constraints: []
  error_handling_rules: []
  tooling_assumptions: []
epics:
  - id: "EPIC-1"
    title: "..."
    objective: "..."
    implementation_steps:
      - "..."
    user_stories:
      - id: "US-1"
        title: "..."
        acceptance_criteria:
          - "..."
        implementation_steps:
          - "..."
        verification:
          required_commands:
            - "npm test"
risks:
  - "..."
approval:
  approved_by: ""
  approved_at: ""
```

--------------------------------

### Uninstall LoopTroop via AUR (yay or paru)

Source: https://www.looptroop.ovh/docs/installation

Use either command to uninstall LoopTroop when installed from the AUR.

```bash
yay -R looptroop-bin
```

```bash
paru -R looptroop-bin
```

--------------------------------

### Uninstall LoopTroop via pnpm

Source: https://www.looptroop.ovh/docs/installation

Use this command to uninstall LoopTroop when installed via pnpm.

```bash
pnpm remove -g looptroop
```

--------------------------------

### Uninstall LoopTroop via Scoop

Source: https://www.looptroop.ovh/docs/installation

Use this command to uninstall LoopTroop when installed via Scoop.

```bash
scoop uninstall looptroop
```

--------------------------------

### Uninstall LoopTroop via Homebrew

Source: https://www.looptroop.ovh/docs/installation

Use this command to uninstall LoopTroop when installed via Homebrew.

```bash
brew uninstall looptroop
```

--------------------------------

### Uninstall LoopTroop via Chocolatey

Source: https://www.looptroop.ovh/docs/installation

Use this command to uninstall LoopTroop when installed via Chocolatey.

```bash
choco uninstall looptroop
```

--------------------------------

### Uninstall LoopTroop via Yarn Classic

Source: https://www.looptroop.ovh/docs/installation

Use this command to uninstall LoopTroop when installed via Yarn Classic.

```bash
yarn global remove looptroop
```

--------------------------------

### GET /api/tickets/:id/beads/raw

Source: https://www.looptroop.ovh/docs/beads

Returns the exact stored JSONL text along with parsed rows and line diagnostics. This endpoint is intended for repair-oriented editors that need to preserve damaged or unrepresentable lines.

```APIDOC
## GET /api/tickets/:id/beads/raw

### Description
Returns the exact stored JSONL text as well as parsed rows and line diagnostics for repair-oriented editors. This allows clients to see the raw content and rebuild the file without losing damaged or unrepresentable lines.

### Method
GET

### Endpoint
/api/tickets/:id/beads/raw

### Parameters
#### Path Parameters
- **id** (string) - Required - The ticket identifier.

### Response
#### Success Response (200)
- **content** (string) - The exact JSONL as stored.
- **items** (array) - Contains only the rows that parsed successfully.
- **malformedLines** (array of integers) - Line numbers of malformed lines.
- **unrepresentableLines** (array of integers) - Line numbers of unrepresentable lines.

#### Response Example
```json
{
  "content": "{\"id\":\"B-1\"}\n{\"id\": \"B-2\", \n",
  "items": [{ "id": "B-1" }],
  "malformedLines": [2],
  "unrepresentableLines": []
}
```
```

--------------------------------

### GET /api/tickets/:id/beads

Source: https://www.looptroop.ovh/docs/beads

Retrieves all successfully parsed bead rows for the given ticket. Returns the exact on-disk hash in the X-Content-Sha256 header and reports malformed or unrepresentable lines via additional headers.

```APIDOC
## GET /api/tickets/:id/beads

### Description
Returns every row that parsed successfully from the bead plan storage. Exposes the exact on-disk hash in the `X-Content-Sha256` header and still succeeds when other lines are damaged.

### Method
GET

### Endpoint
/api/tickets/:id/beads

### Parameters
#### Path Parameters
- **id** (string) - Required - The ticket identifier.

### Response
#### Success Response (200)
- Returns a bead array containing the parsed rows.

#### Response Headers
- **X-Content-Sha256** (string) - Exact on-disk hash of the stored JSONL content.
- **X-Malformed-Line-Count** (integer) - Exact count of malformed lines.
- **X-Malformed-Lines** (string) - Comma-separated list of line numbers for malformed lines (capped to first 50 entries).
- **X-Unrepresentable-Line-Count** (integer) - Exact count of unrepresentable lines.
- **X-Unrepresentable-Lines** (string) - Comma-separated list of line numbers for unrepresentable lines (capped to first 50 entries).

#### Response Example
```json
[{"id":"B-1"},{"id":"B-2"}]
```
```

--------------------------------

### Run individual maintenance steps

Source: https://www.looptroop.ovh/docs/operations

Run these commands directly for tighter control over dependency sync, audit remediation, and OpenCode upgrade.

```bash
npm run deps:sync
npm run audit:remediate
npm run opencode:upgrade
```

--------------------------------

### Run LoopTroop with Docker on Linux using host network

Source: https://www.looptroop.ovh/docs/installation

Runs the LoopTroop container on Linux with host networking, mounting the project at its own path and using a named volume for configuration. Requires an OpenCode server reachable at the specified URL.

```bash
docker run --network host \
  -e LOOPTROOP_OPENCODE_BASE_URL=http://127.0.0.1:4096 \
  -v looptroop-config:/home/node/.looptroop \
  -v "$PROJECT":"$PROJECT" -w "$PROJECT" \
  looptroopai/looptroop:latest
```

--------------------------------

### Run LoopTroop container with host user and config volume

Source: https://www.looptroop.ovh/docs/installation

Run the LoopTroop container with host user mapping, HOME set to /tmp, and a named config volume. This avoids git dubious ownership and keeps the config writable by the host user.

```bash
docker run --network host --user "$(id -u):$(id -g)" \
  -e HOME=/tmp \
  -e LOOPTROOP_CONFIG_DIR=/workspace/.looptroop \
  -e LOOPTROOP_OPENCODE_BASE_URL=http://127.0.0.1:4096 \
  -v "$PROJECT":"$PROJECT" -w "$PROJECT" \
  -v "$HOME/.looptroop:/workspace/.looptroop" \
  looptroopai/looptroop:latest
```

--------------------------------

### Multi-line context_guidance string format

Source: https://www.looptroop.ovh/docs/output-normalization

Multi-line format for context_guidance string that is converted to an object with patterns and anti_patterns arrays.

```text
Patterns:
- Use X
Anti-patterns:
- Avoid Y

```

--------------------------------

### Run LoopTroop with Docker on Docker Desktop (Mac/Windows)

Source: https://www.looptroop.ovh/docs/installation

Runs the LoopTroop container on Docker Desktop for Mac/Windows, publishing port 3000 and setting environment variables to allow remote API access. Requires a generated API token and an OpenCode server reachable at host.docker.internal:4096.

```bash
docker run -p 127.0.0.1:3000:3000 \
  -e LOOPTROOP_ALLOW_REMOTE_API=1 \
  -e LOOPTROOP_BACKEND_HOST=0.0.0.0 \
  -e LOOPTROOP_API_TOKEN="$(openssl rand -hex 32)" \
  -e LOOPTROOP_OPENCODE_BASE_URL=http://host.docker.internal:4096 \
  -v looptroop-config:/home/node/.looptroop \
  -v "$PROJECT":"$PROJECT" -w "$PROJECT" \
  looptroopai/looptroop:latest
```

--------------------------------

### Inline context_guidance string format

Source: https://www.looptroop.ovh/docs/output-normalization

Inline format for context_guidance string that is converted to an object with patterns and anti_patterns arrays.

```text
Patterns: Use X Anti-patterns: Avoid Y

```

--------------------------------

### Print sign-in URL with looptroop open --print-url

Source: https://www.looptroop.ovh/docs/diagnostics

Prints a single-use sign-in link that ends in '#bootstrap=…'. Treat it as a password: it signs one browser in and then expires; do not paste it into a bug report. Available since 0.5.7 when no browser opens.

```bash
looptroop open --print-url
```

--------------------------------

### Show command help with --help or "?"

Source: https://www.looptroop.ovh/docs/cli

Every command documents itself. These invocations print a command's own options, what it does with them, and which commands to reach for instead. The double quotes keep the `?` literal in every shell.

```bash
looptroop open --help
looptroop doctor "?"
```

--------------------------------

### Run LoopTroop with Docker in PowerShell

Source: https://www.looptroop.ovh/docs/installation

PowerShell equivalent of the Docker Desktop command, setting the project path and generating a random API token. Uses backticks for line continuation and host.docker.internal for the OpenCode server.

```powershell
$Project = "C:\path\to\project"
$Token = -join ((1..32) | ForEach-Object { "{0:x2}" -f (Get-Random -Max 256) })
docker run -p 127.0.0.1:3000:3000 `
  -e LOOPTROOP_ALLOW_REMOTE_API=1 `
  -e LOOPTROOP_BACKEND_HOST=0.0.0.0 `
  -e LOOPTROOP_API_TOKEN=$Token `
  -e LOOPTROOP_OPENCODE_BASE_URL=http://host.docker.internal:4096 `
  -v "${Project}:${Project}" -w $Project `
  looptroopai/looptroop:latest
```

--------------------------------

### Run database schema generation and push commands

Source: https://www.looptroop.ovh/docs/database-schema

Commands for generating and pushing database schema changes. Use db:generate:app and db:generate:project for migration artifact review or external tooling, and db:push:project to explicitly push project schema changes when LOOPTROOP_PROJECT_DB_PATH is set. Verify generated output against server/db/schema.ts before committing.

```bash
npm run db:generate:app
npm run db:generate:project
npm run db:push:project
```

--------------------------------

### Stop the LoopTroop daemon before uninstalling

Source: https://www.looptroop.ovh/docs/installation

Run this command first to stop the daemon so no files are held open or database writes occur during uninstallation.

```bash
looptroop stop
```

--------------------------------

### Windows: Verify checksum with Get-FileHash

Source: https://www.looptroop.ovh/docs/installation

Computes the SHA-256 hash of the downloaded Windows zip file. Compare the output against the corresponding line in checksums.sha256.

```powershell
Get-FileHash looptroop-<version>-win-x64.zip -Algorithm SHA256
```

--------------------------------

### Bead storage path

Source: https://www.looptroop.ovh/docs/beads

Shows the file path where the editable bead plan is stored as JSONL.

```text
.ticket/beads/<flow>/.beads/issues.jsonl
```

--------------------------------

### Current Phase Allowlists (YAML)

Source: https://www.looptroop.ovh/docs/context-engineering

Mirrors the current phase mapping in server/opencode/contextBuilder.ts. Lists allowed context sections per phase. Some statuses append task-specific sections outside this reusable allowlist.

```yaml
interview_draft:
  - relevant_files
  - ticket_details
interview_vote:
  - relevant_files
  - ticket_details
  - drafts
interview_refine:
  - relevant_files
  - ticket_details
  - drafts
interview_qa:
  - ticket_details
interview_coverage:
  - ticket_details
  - user_answers
  - interview
prd_draft:
  - relevant_files
  - ticket_details
  - interview
  - full_answers
prd_vote:
  - relevant_files
  - ticket_details
  - interview
  - drafts
prd_refine:
  - relevant_files
  - ticket_details
  - full_answers
  - drafts
prd_coverage:
  - full_answers
  - prd
beads_draft:
  - relevant_files
  - ticket_details
  - prd
beads_vote:
  - relevant_files
  - ticket_details
  - prd
  - drafts
beads_refine:
  - relevant_files
  - ticket_details
  - prd
  - drafts
beads_expand:
  - relevant_files
  - ticket_details
  - prd
  - beads_draft
beads_coverage:
  - prd
  - beads
execution_setup_plan:
  - ticket_details
  - relevant_files
  - prd
  - beads
  - execution_setup_profile
  - execution_setup_plan_notes
execution_setup_plan_regenerate:
  - ticket_details
  - relevant_files
  - prd
  - beads
  - execution_setup_profile
  - execution_setup_plan
  - execution_setup_plan_notes
execution_setup:
  - ticket_details
  - beads
  - execution_setup_plan
  - execution_setup_notes
coding:
  - bead_data
  - bead_notes
context_wipe:
  - bead_data
  - error_context
final_test:
  - ticket_details
  - prd
  - beads
  - final_test_notes
pull_request:
  - ticket_details
  - prd
preflight:
  - ticket_details
```

--------------------------------

### looptroop clean — list and remove abandoned worktrees

Source: https://www.looptroop.ovh/docs/cli

Lists abandoned worktrees and removes them with --apply. Cleanup never touches configuration, database, logs, or tickets. With --apply, it rechecks containment, ownership, activity, registration, and Git before removal; changed worktrees or failed Git registration keep directories in place.

```bash
looptroop clean           # list what could be removed
looptroop clean --apply   # actually remove it
```

--------------------------------

### Pull LoopTroop container image with Podman

Source: https://www.looptroop.ovh/docs/installation

Podman requires the full registry in the image name. Use either Docker Hub or GHCR with the explicit registry prefix.

```bash
podman pull docker.io/looptroopai/looptroop:latest
# or
podman pull ghcr.io/looptroop-ai/looptroop:latest
```

--------------------------------

### Coverage gaps bead YAML format

Source: https://www.looptroop.ovh/docs/prompts

Shows the required YAML structure for a coverage-gaps bead. Each bead must include exactly the listed fields, with testCommands as a list of CommandSpec objects using mode "process" or "shell". When testCommands is empty, add testCommandReason as a non-empty string; otherwise omit it.

```yaml
beads:
  - id: "setup-db-schema"
    title: "Create database schema"
    prdRefs:
      - "EPIC-1"
      - "US-1-1"
    description: "Detailed technical implementation steps for this bead."
    contextGuidance:
      patterns:
        - "Use Drizzle ORM migrations."
      anti_patterns:
        - "Avoid raw SQL."
    acceptanceCriteria:
      - "Schema file exists and migrations run cleanly."
    tests:
      - "Unit test verifies table creation."
    testCommands:
      - mode: "process"
        program: "npm"
        args: ["run", "test", "--", "server/db"]
        cwd: "."
        env: {}
```

--------------------------------

### macOS (ARM): Verify checksum with grep and shasum

Source: https://www.looptroop.ovh/docs/installation

Verifies the downloaded macOS ARM (darwin-arm64) tarball using shasum -a 256 -c on the matching checksum line.

```bash
grep looptroop-<version>-darwin-arm64.tar.gz checksums.sha256 | shasum -a 256 -c
```

--------------------------------

### Ticket Flow At A Glance

Source: https://www.looptroop.ovh/docs/ticket-flow

Text diagram of the ticket lifecycle from DRAFT through COMPLETED, including recovery transitions for BLOCKED_ERROR, CANCELED, WAITING_PR_REVIEW, and WAITING_MANUAL_QA. Use it as a quick reference for the canonical status flow and error handling.

```text
DRAFT
  -> SCANNING_RELEVANT_FILES
  -> Interview loop
  -> PRD loop
  -> Beads loop
  -> PRE_FLIGHT_CHECK
  -> GENERATING_EXECUTION_SETUP_PLAN
  -> WAITING_EXECUTION_SETUP_APPROVAL
  -> PREPARING_EXECUTION_ENV
  -> CODING bead loop
  -> RUNNING_FINAL_TEST
  -> GENERATING_QA_CHECKLIST (when the start-time Manual QA lock is enabled)
  -> WAITING_MANUAL_QA
  -> INTEGRATING_CHANGES
  -> CREATING_PULL_REQUEST
  -> WAITING_PR_REVIEW
  -> CLEANING_ENV
  -> COMPLETED

Any active phase can fail into BLOCKED_ERROR.
BLOCKED_ERROR -> RETRY -> previousStatus
BLOCKED_ERROR -> CONTINUE -> previousStatus (eligible preserved OpenCode sessions only)
Any cancelable non-terminal phase -> CANCELED
WAITING_PR_REVIEW -> merge or close-unmerged -> CLEANING_ENV
WAITING_MANUAL_QA -> failed submission -> CODING -> fresh RUNNING_FINAL_TEST -> next QA version
```

--------------------------------

### Read daemon token with docker exec

Source: https://www.looptroop.ovh/docs/installation

Use this command to read the daemon token from the container's daemon.json. The token is minted at startup and recorded owner-only; this is the one that authorizes the wider bind.

```bash
docker exec <container> sh -c 'cat "$LOOPTROOP_CONFIG_DIR/daemon.json"'
```

--------------------------------

### diagnose:stall options

Source: https://www.looptroop.ovh/docs/operations

Useful options for the diagnose:stall command: --sample-ms sets the sampling interval, --timeout-ms sets the timeout, --trend-ms controls trend collection (0 disables), and --ticket-path specifies a ticket path for focused artifact sizing.

```bash
npm run diagnose:stall -- --sample-ms 5000
```

```bash
npm run diagnose:stall -- --timeout-ms 8000
```

```bash
npm run diagnose:stall -- --trend-ms 0
```

```bash
npm run diagnose:stall -- --trend-ms 120000 --trend-interval-ms 1000
```

```bash
npm run diagnose:stall -- --ticket-path /path/to/worktree/.ticket
```

--------------------------------

### Clean tracked .looptroop from Git index

Source: https://www.looptroop.ovh/docs/operations

Run from the attached project root when ticket startup is blocked with INIT_LOOPTROOP_TRACKED. Removes LoopTroop runtime paths from the Git index without deleting local runtime files.

```bash
git rm --cached -r .looptroop
git commit -m "Stop tracking LoopTroop runtime data"

```

--------------------------------

### looptroop CLI usage text

Source: https://www.looptroop.ovh/docs/cli

Generated from the CLI's own usage text, so it cannot drift from what the command prints. Lists all commands and options for the `looptroop` CLI.

```text
LoopTroop — local AI coding orchestration

Usage: looptroop <command> [options]

Commands:
  open           Open the interface, starting LoopTroop if it is not running
  start          Start the daemon in the background
  stop           Stop the running daemon
  restart        Stop and start again
  status         Show whether the daemon is running
  logs           Show the daemon log
  doctor         Check that this machine can run LoopTroop
  setup          Attach a project from the terminal, then open the interface
  clean          List, and optionally remove, abandoned worktrees

Options:
  --port <n>     Port to listen on (start, restart)
  --foreground   Run in this terminal instead of the background (start)
  --print-url    Print the sign-in link instead of opening a browser (open)
  --opencode-logs=all
                 Include managed OpenCode DEBUG output (open, start)
  --json         Machine-readable output (status, doctor)
  --follow, -f   Keep streaming (logs)
  --lines <n>    Number of log lines to show (logs)
  --apply        Actually remove what clean would delete
  --yes, -y      Accept every default without asking (setup)
  --version      Print the version
  --help         Print this message

Run `looptroop <command> --help`, `looptroop <command> help`, or
`looptroop <command> "?"` (double quotes keep `?` literal in every shell)
for what a single command does and takes.
```

--------------------------------

### Set project path for LoopTroop container

Source: https://www.looptroop.ovh/docs/installation

Defines the PROJECT environment variable to the absolute path of the project. This path is used for mounting the project into the container and must be identical on both host and container for OpenCode to access files.

```bash
PROJECT=/absolute/path/to/project
```

--------------------------------

### One-run startup flags for npm run dev

Source: https://www.looptroop.ovh/docs/operations

Use these environment variables and flags to change npm run dev behavior, enabling maintenance, skipping deps or OpenCode upgrade, forcing maintenance, or enabling LAN mode and OpenCode logs.

```bash
LOOPTROOP_DEV_MAINTENANCE=1 npm run dev
LOOPTROOP_DEV_MAINTENANCE=1 LOOPTROOP_DEV_SKIP_DEPS=1 npm run dev
LOOPTROOP_DEV_MAINTENANCE=1 LOOPTROOP_DEV_SKIP_OPENCODE_UPGRADE=1 npm run dev
LOOPTROOP_DEV_MAINTENANCE=1 LOOPTROOP_DEV_FORCE_MAINTENANCE=1 npm run dev
npm run dev --lan
npm run dev --opencode-logs=all
```

--------------------------------

### Check status, logs, and stop LoopTroop

Source: https://www.looptroop.ovh/docs/getting-started

Check status, follow logs, and stop LoopTroop. These are basic operational commands; every command and flag is in the CLI Reference.

```bash
looptroop status    # is it running?
looptroop logs -f   # what is it doing?
looptroop stop
```

--------------------------------

### Run LoopTroop doctor for upgrade checks

Source: https://www.looptroop.ovh/docs/installation

Run the doctor command to check for and apply upgrades to LoopTroop. This is the primary upgrade command.

```bash
looptroop doctor
```

--------------------------------

### Container (Docker, Podman) - Pull

Source: https://www.looptroop.ovh/docs/installation

Pull the LoopTroop container image from Docker Hub or GitHub Container Registry. Pull again to upgrade.

```shell
docker pull looptroopai/looptroop:latest
```

```shell
docker pull ghcr.io/looptroop-ai/looptroop:latest
```

--------------------------------

### Set LOOPTROOP_TRUSTED_EXECUTABLE_DIRS

Source: https://www.looptroop.ovh/docs/configuration

Sets the environment variable to trust specific absolute directories for tool lookup. Directories are searched before PATH and are trusted as-is; separate entries with ':' on macOS/Linux and ';' on Windows. Empty or relative entries are discarded.

```bash
export LOOPTROOP_TRUSTED_EXECUTABLE_DIRS=/opt/tools:/srv/toolchain
```

--------------------------------

### Continuation prompt text

Source: https://www.looptroop.ovh/docs/opencode-integration

Exact replacement prompt body used when a pending continuation exists for a preserved session. Instructs the model to continue.

```text
continue please
```

--------------------------------

### Read LoopTroop daemon logs

Source: https://www.looptroop.ovh/docs/cli

Displays recent daemon log entries. Use `-f` to keep streaming and `--lines 200` to control the number of lines shown. The log lives in the configuration directory and survives restarts.

```bash
looptroop logs             # the recent log
looptroop logs -f          # keep streaming
looptroop logs --lines 200
```

--------------------------------

### Pull LoopTroop Docker image

Source: https://www.looptroop.ovh/docs

Pull the latest LoopTroop Docker image.

```bash
docker pull looptroopai/looptroop:latest
```

--------------------------------

### Pull LoopTroop container image from GitHub Container Registry

Source: https://www.looptroop.ovh/docs/installation

Pull the latest LoopTroop image from GitHub Container Registry. The image is published for linux/amd64 and linux/arm64.

```bash
docker pull ghcr.io/looptroop-ai/looptroop:latest
```

--------------------------------

### Run looptroop doctor and doctor --json

Source: https://www.looptroop.ovh/docs/diagnostics

Run the doctor command to check the machine. The --json flag emits JSON on stdout and nothing else, suitable for piping into a parser. The command exits non-zero when any check fails.

```bash
looptroop doctor
```

```bash
looptroop doctor --json
```

--------------------------------

### Run runtime stall report with npm run diagnose:stall

Source: https://www.looptroop.ovh/docs/diagnostics

Run while 'npm run dev' is still running, ideally during the slowdown, to diagnose runtime stalls.

```bash
npm run diagnose:stall
```

--------------------------------

### Force polling for watchers with CHOKIDAR_USEPOLLING=1

Source: https://www.looptroop.ovh/docs/operations

Use this command to force polling for both frontend and backend watchers when file changes are missed. An explicit value overrides auto-detection; set CHOKIDAR_USEPOLLING=0 to force native watching.

```bash
CHOKIDAR_USEPOLLING=1 npm run dev
```

--------------------------------

### Add Yarn global bin to PATH in Bash or zsh

Source: https://www.looptroop.ovh/docs/installation

Use this snippet to add Yarn's global binary directory to your PATH in Bash or zsh. The first command shows where Yarn places global executables (usually ~/.yarn/bin), and the second exports that directory to your PATH. This is necessary because Yarn does not automatically add its global binaries to PATH, causing 'looptroop' to not be recognized as a command after a successful 'yarn global add looptroop'.

```bash
yarn global bin                 # usually ~/.yarn/bin
export PATH="$(yarn global bin):$PATH"
```

--------------------------------

### PUT /api/tickets/:id/beads

Source: https://www.looptroop.ovh/docs/beads

Rewrites the entire bead plan file atomically. This operation is only allowed while the ticket is in the WAITING_BEADS_APPROVAL state.

```APIDOC
## PUT /api/tickets/:id/beads

### Description
Rewrites the entire bead plan file atomically. This operation is only allowed while the ticket is in `WAITING_BEADS_APPROVAL`. The request body can include either `{ beads, sourceLines }` or just a bead array. Unknown statuses and invalid dependency edges are rejected.

### Method
PUT

### Endpoint
/api/tickets/:id/beads

### Parameters
#### Path Parameters
- **id** (string) - Required - The ticket identifier.

#### Request Body
- **beads** (array) - Required - The bead array to save. Alternatively, the body can include `{ beads, sourceLines }`.
- **sourceLines** (array of integers) - Optional - One strictly increasing positive safe integer per row, used only for diagnostics. Not required if sending a bead array without source positions.

### Request Example
```json
{
  "beads": [
    {"id":"B-1","status":"pending","priority":3}
  ],
  "sourceLines": [1]
}
```

### Response
#### Success Response (200)
- Confirms the atomic rewrite.

### Error Handling
- Rejects unknown statuses and invalid dependency edges.
- Rejects missing `status` or `priority` fields.
```

--------------------------------

### Diagnostic report output path

Source: https://www.looptroop.ovh/docs/diagnostics

The diagnostic command writes a timestamped local report to this path under tmp/diagnostics/. The report is read-only and does not mutate tickets, repair databases, or modify attached projects.

```text
tmp/diagnostics/runtime-stall-YYYYMMDD-HHMMSS.log
```

--------------------------------

### Uninstall LoopTroop via Docker

Source: https://www.looptroop.ovh/docs/installation

Use either command to remove the LoopTroop container image from Docker Hub or GitHub Container Registry.

```bash
docker rmi looptroopai/looptroop:latest
```

```bash
docker rmi ghcr.io/looptroop-ai/looptroop:latest
```