Overview

This is the command reference for the cog CLI. It covers every command’s purpose, the most useful flags, and a representative example. For exhaustive flag listings and edge-case behavior, run cog <command> --help.

Cog runs against the current repository. Every work-executing command (start, build, revise, merge, rubber-stamp, arena) discovers the repo from the working directory — to operate on a different repo, cd into it.

---

skills

Interactive workflows (capture, shape) live inside your coding harness, not as cog subcommands. Manage them here.

cog skills install

Install the cog-capture and cog-shape skills into your harness’s native skill surface.

Flags:

--harness <name>   Target: claude, codex, opencode, pi, or all (default: configured default harness)
--project          Install into the current repo instead of user-global
--force            Overwrite existing files with the same name

Example:

cog skills install --harness claude

After install, invoke from inside the harness: /cog-capture to file an issue, /cog-shape to decompose complex work.

cog skills uninstall

Remove skills Cog previously installed. Only touches files Cog tracks in its install manifest — never user-authored skills with the same name.

cog skills uninstall --harness claude

cog skills list

Show installed skills with harness, scope, path, and version.

cog skills list

---

start

Run the priority loop continuously for the current repo. This is the main way to run Cog.

The loop checks for work in priority order: approved PRs to merge, PRs with changes requested to revise, unassigned issues to build. Finishing existing work always takes precedence over starting new work.

Flags:

--rubber-stamp     Also auto-approve PRs awaiting review (off by default)
--arena            Route the build step through cog arena (multi-candidate + judge)
--no-arena         Force plain build even if arena-mode config is true
--no-build         Skip the build step (merge + revise only)
--no-revise        Skip the revise step
--no-merge         Skip the merge step

Example:

cog start                            # Full priority loop
cog start --arena                    # Every picked-up issue goes through arena
cog start --no-build                 # Drain existing PRs without starting new work

Run multiple cog start instances against the same repo to increase throughput. GitHub state plus a remote claims API coordinate them automatically.

---

build

Implement the next unassigned open issue, or a specific issue by number. Runs once and exits.

Cog self-assigns the issue, pulls main, creates a worktree and branch ({type}/issue-{n}-{slug}), invokes your harness with the build prompt, runs checks until green, self-reviews the diff, opens a PR, and handles the Copilot review cycle.

Flags:

--harness <runner>         Override default-harness for this run (e.g., claude@opus)
--review-harness <runner>  External review runner (skipped when unset)
--max-turns <n>            Maximum harness turns (default: 200)
--timeout <duration>       Kill the harness after this duration (default: 1h)

Example:

cog build                                  # Next unassigned issue, default harness
cog build 42                               # Implement issue #42
cog build 42 --harness claude@opus

Runner-string syntax:

Flags documented as taking <runner> use runner strings of the form <harness>@<model>[:<variant>]. Examples: claude@opus, codex@gpt-5, gemini@gemini-2.5-pro, opencode@anthropic/claude-opus-4-7, pi@anthropic/claude-opus-4-7:high.

For pi, the runner string is pi@<provider>/<model>[:<thinking>], where :<thinking> maps to one of off | minimal | low | medium | high | xhigh.

In cog arena, --harnesses takes a comma-separated list of runner strings.

---

revise

Address review feedback on PRs with CHANGES_REQUESTED. Runs once across all eligible PRs and exits.

For each PR, Cog finds the worktree, resumes the original harness session, reads review bodies, inline comments, and conversation threads, implements the fixes, runs checks, pushes a single fix commit, replies to each thread, resolves each thread, and requests re-review.

Flags:

--harness <runner>    Override default-harness for this pass
--max-turns <n>       Maximum harness turns per PR (default: 100)
--timeout <duration>  Kill the harness after this duration (default: 30m)

Example:

cog revise

---

merge

Shepherd approved PRs to merge. Runs once across all eligible PRs and exits.

For each approved non-draft PR, Cog resumes the original session, merges main into the branch, resolves conflicts preserving the PR’s intent, fixes any CI failures caused by the merge, and squash-merges when everything is green. Changes are mechanical — the intent of the PR must not change.

Flags:

--harness <runner>    Override default-harness for this pass
--max-turns <n>       Maximum harness turns per PR (default: 200)
--timeout <duration>  Kill the harness after this duration (default: 45m)

Example:

cog merge

---

rubber-stamp

Auto-approve all PRs that are awaiting review in the current repo. Runs once and exits.

This is for workflows where the human reviewer is the bottleneck and you trust the self-review, external review, and Copilot review pipeline to catch issues. Rubber-stamp is off by default in cog start; opt in with --rubber-stamp or run this command manually.

GitHub does not allow a user to approve their own PR, so rubber-stamp must run under a different GitHub identity than the one that created the PR.

Example:

cog rubber-stamp

---

arena

Run multiple harness/model runners in parallel against the same issue, then have a judge runner cross-compare and synthesize a best-of-breed PR.

Arena is for complex or high-stakes issues where the cost of multiple implementations (4–6x a normal build) is justified by the quality improvement. The resulting PR feeds the normal revise/merge lifecycle.

Flags:

--candidates <n>       Number of parallel implementations (default: 3)
--harnesses <list>     Comma-separated runners, e.g., claude@opus,codex@gpt-5
--judge <runner>       Judge runner (required; falls back to judge-harness config)
--judge-max-turns <n>  Judge phase max turns (default: 300)
--timeout <duration>   Per-candidate timeout (default: 1h)
--judge-timeout <d>    Judge phase timeout (default: 2h)
--keep-candidates      Keep candidate worktrees after the judge completes

Example:

cog arena 42 --harnesses claude@opus,codex@gpt-5,gemini@gemini-2.5-pro,opencode@anthropic/claude-opus-4-7 \
  --judge claude@opus

The PR body includes an Arena Summary showing which candidates passed checks and how much of the final diff came from each.

cog arena stats

Aggregate arena attribution across runs to reveal which runners are contributing in your actual codebase.

Flags:

--since <duration>  Only include runs after this time (e.g., 30d, 7d)
--runner <name>     Filter to a specific runner
--judge <name>      Filter to runs with a specific judge
--repo <name>       Restrict or expand scope; use --repo all for every repo
--limit <n>         Max runs to include (default: 100)
--json              Output raw JSON instead of the table

Example:

cog arena stats --since 30d

---

stop

Stop all running cog processes for the current repo. Sends SIGTERM to each (graceful first-stage shutdown); escalates to SIGKILL after 10 seconds. Worktrees and branches survive for session resume.

cog stop

---

log

Stream or review an issue’s full lifecycle log (build, revise, and merge combined).

Flags:

--raw                 Output raw JSONL instead of human-readable format
--list                List all issue logs with status, last phase, and timestamps
--candidate <n>       Stream a specific candidate's log from an arena run
--harness <runner>    Select the log formatter when reading a log produced by a different harness family

Example:

cog log                 # Most recently active issue log
cog log 42              # Full lifecycle for issue #42
cog log --list

---

status

Show worktrees, PR states, and whether cog start is running for the current repo.

cog status

Output includes each running Cog instance (PID, command, state) and a list of worktrees matched to their PR states.

---

clean

Prune orphaned worktrees — worktrees whose branch has no open PR.

Flags:

--dry-run   Show what would be removed without removing anything
--force     Remove even claimed or dirty worktrees

Example:

cog clean --dry-run
cog clean

---

config

Manage configuration stored at ~/.config/cog/config.yaml.

cog config set

Set a config value.

cog config set default-harness claude@sonnet
cog config set judge-harness claude@opus
cog config set review-harness codex@gpt-5
cog config set slack-webhook https://hooks.slack.com/services/...

cog config get

Get a config value.

cog config get timeout.build

cog config list

List every config value.

cog config list

Notable keys:

default-harness       Runner used by build, revise, merge, and arena candidates (default: claude@sonnet)
judge-harness         Runner for the arena judge phase (required for arena)
review-harness        External review runner; when unset, self-review alone gates push
slack-webhook         Slack incoming webhook for notifications
copilot-review        Gate for the Copilot review cycle (default: true)
copilot-cycles        Max Copilot review cycles before stopping (default: 10)
arena-mode            Route cog start's build step through arena (default: false)
max-turns.{build,revise,merge}
timeout.{build,revise,merge}

Command-line flags override config file values; config values override built-in defaults.

---

auth

Authenticate with Mechanical Advantage to validate your Cog subscription. Cog uses the same device auth flow as the rest of Mechanical Advantage — one account covers both products.

cog auth login

Start the device authorization flow. Opens your browser, prompts for biometric passkey approval, and stores a token at ~/.config/cog/auth.json. First-time users need an existing account with a payment method on file at app.mechanicaladvantage.ai.

cog auth login

cog auth logout

Clear stored credentials.

cog auth logout

cog auth status

Show the authenticated account and whether the Cog subscription is active.

cog auth status

---

feedback

Report friction, bugs, or improvement ideas to Mechanical Advantage. User-initiated only.

cog feedback submit

Submit a feedback item. --title is required (max 200 chars). --description is optional (max 10,000 chars); if the value ends in .md or .txt, Cog reads the file at that path as the body.

cog feedback submit --title "copilot review polling feels slow when there are no comments"
cog feedback submit --title "arena judge race on timeout" --description notes.md

cog feedback list

List your submitted feedback items.

Flags:

--status <status>   Filter: received, triaged, in-progress, resolved, declined
--limit <n>         Max results per page (1–100)
--cursor <cursor>   Pagination cursor from a previous response

Example:

cog feedback list --status resolved

cog feedback view

View a specific feedback item with full description and any response.

cog feedback view FB-1234

---

update

Check for and install the latest version of cog.

cog update