Quickstart

Cog takes a GitHub issue and turns it into a merged pull request — autonomously. You describe what you want, Cog implements it, opens a PR, addresses review feedback, and merges when approved. This guide walks you through your first end-to-end run.

Step 1: Install

Run the install script:

curl -fsSL https://raw.githubusercontent.com/mechanical-advantage-ai/cog/main/install.sh | sh

The script downloads the right cog binary for your platform (macOS, Linux, or Windows; amd64 or arm64) and drops it on your PATH. Verify:

cog --version

Step 2: Prerequisites

Cog orchestrates a coding harness — it doesn’t do the coding itself. Before continuing, you need:

  • A supported harness, installed and authenticated. Any of these works:
  • GitHub CLI (gh) authenticated with repo access (gh auth login). Cog uses gh for every issue and PR operation.
  • A git repository with a GitHub remote. Cog discovers the repo from your working directory and reads its remote to determine the owner and repo name.

Step 3: Authenticate

Authenticate Cog with Mechanical Advantage:

cog auth login

This starts a device authorization flow, opens your browser, and prompts you to approve the device with a biometric passkey. First-time users: sign up at app.mechanicaladvantage.ai and add a payment method before running cog auth login. Approving the device activates your $1,000/month Cog subscription.

The token is stored at ~/.config/cog/auth.json. Check status any time:

cog auth status

Step 4: Install the capture and shape skills

Cog ships two interactive workflows as skills — templates that Cog installs into your harness’s native skill surface. You invoke them from inside the harness’s TUI, not via a cog subcommand.

cog skills install

By default this installs into your configured default harness at user scope. Pass --harness claude|codex|opencode|pi|all to target a specific harness, or --project to install into the current repo only.

After install, you have:

  • /cog-capture — investigates a bug or feature idea and files a well-documented GitHub issue.
  • /cog-shape — Socratic decomposition of complex work into ordered, implementable issues.

List what’s installed:

cog skills list

Step 5: File your first issue with /cog-capture

Open your harness in the repo you want Cog to work on. Invoke the capture skill (in Claude Code: type /cog-capture). The skill will:

  1. Ask you to describe what you observed and what you expected (for bugs), or what problem you’re solving and who it’s for (for features).
  2. Investigate the codebase — finding the affected components, data flows, and existing patterns.
  3. Show you a draft: title, description, steps to reproduce or motivation, affected components, and technical context. Wait for your approval.
  4. Check for duplicates with gh issue list.
  5. Create the issue with gh issue create.

The output is a high-quality GitHub issue ready for autonomous implementation.

For larger, nebulous work — “we need multi-tenant billing” — invoke /cog-shape instead. It runs a Socratic conversation that challenges your thinking and decomposes the work into a set of ordered issues.

Step 6: Run Cog

From inside the repo, start the priority loop:

cog start

cog start runs a single sequential loop: check for approved PRs to merge, then PRs needing revision, then unassigned issues to build. When it finds work, it self-assigns, creates a worktree and branch, invokes your harness, writes code, runs format/lint/tests, self-reviews, opens a PR, and handles the Copilot review cycle.

You’ll see formatted output in the terminal as it works. Leave it running; it will keep picking up work until you stop it (Ctrl-C stops cleanly, leaving worktrees intact for resume).

To run a single issue without the loop:

cog build 42

Step 7: Review and approve the PR

When Cog finishes building, you get a PR ready for human review. Open it on GitHub and do what you’d normally do — read the diff, leave inline comments, approve or request changes.

  • Request changes. Cog picks up the feedback on the next loop cycle, addresses every comment, pushes a fix commit, replies to each thread, and requests re-review.
  • Approve. Cog picks up the approved PR, merges main into the branch, resolves conflicts, fixes any CI failures caused by the merge, and squash-merges when everything is green.

Cog resumes the original harness session for revise and merge, so the harness has full context of why the code was written the way it was — no cold-start re-learning.

What’s next

You’ve run Cog end-to-end. A few commands worth knowing:

  • cog status — worktrees, PR states, and which cog start instances are running for this repo.
  • cog log 42 — stream the full lifecycle log for issue #42 (build, revise, and merge in one file).
  • cog arena 42 — run multiple harnesses against the same issue in parallel and have a judge runner synthesize the best-of-breed PR. For complex or high-stakes issues where cost is justified by quality.
  • cog config list — see all configurable defaults (default harness, review harness, timeouts, Copilot cycle cap).

See the full surface in the Command Reference.