co-maintainer

init

First-time knowledge build for a GitHub repository. init fetches sources from GitHub, runs AI synthesis, and writes review guides under your co-maintainer config directory (not inside the git clone). Expect minutes of runtime and non-trivial API cost on large repos.

Before you run

Check Why
Install co-maintainer init is a CLI command
probe on the same owner/repo (recommended) Gives a ready-made init line with limits and --include-* flags
GitHub auth Reads the repo through gh or a PAT
AI provider A key and both models via co-maintainer set or flags. There is no default model

Run probe first when you are unsure which --max-* limits to use.

Usage

co-maintainer set --auth=gh --ai=openrouter --token=YOUR_KEY \
  --low-model=openai/gpt-oss-120b --high-model=openai/gpt-5.6-luna

co-maintainer probe owner/repo
# copy the recommended init line from probe output, for example:
co-maintainer init owner/repo --include-codebase --include-pull-requests \
  --max-pr-months=12 --max-commits=500

If AI settings are missing, the CLI prompts for provider, API key, and models. Values from set, --env=PATH, or flags are not asked again.

Parameters

Flag Meaning
owner/repo Repository to analyze (required)
--auth=gh GitHub CLI (default, or from set / config)
--auth=pat Personal access token (see Authentication)
--github-pat=... PAT when not in env or config
--env=PATH Load env vars from a file
--ai=openrouter AI provider (openrouter, openai, anthropic, opencode-zen or opencode-go). Required, see AI providers
--token=... Provider API key
--low-model=... Model for extraction steps
--high-model=... Model for synthesis steps
--include-codebase Include default-branch tree and files
--include-pull-requests Include PR metadata and discussions
--include-pull-request-changes Include PR diffs
--include-commit-history Include commit messages on the default branch
--include-how-repo-works Include issues / workflow signals when available
--max-pr-months=N Limit how far back PR history goes
--max-commits=N Limit commits scanned on the default branch
--max-pull-request-change-lines=N Skip oversized PR diffs
--max-comment=N Cap discussion comments kept per pull request
--only-request-changed-pr Keep only pull requests with at least one CHANGES_REQUESTED review
--pr-state=open,closed,merged Keep a comma-separated subset of open, closed, and merged
--gh-concurrent=N Parallel GitHub fetches (default 1)
--ai-concurrent=N Parallel AI jobs (default 3)
--json One JSON document on stdout, no prompts (see JSON output)
--debug Verbose logs on stderr
--log-time Print timing per phase

Include flags: If you pass any --include-* on the command line, only the flags you list are enabled. With no --include-* flags, all sources default to on (unless a prior init stored different choices in config for this repo).

Pull request filters: --only-request-changed-pr applies inside the --max-pr-months window. A dismissed review does not count. Dropped pull requests skip comment and diff downloads. The run logs only request-changed pr · kept N · dropped N. Off by default. --pr-state takes open, closed, and merged, separated by commas. closed means closed and not merged. Omit it to keep every state. The listing cache is stored per state set, so a different set is not filled from the previous listing.

Both are saved for the repo. A later sync without the flag keeps the saved choice. --only-request-changed-pr does not turn itself off. To collect every state again, pass --pr-state=open,closed,merged.

Limits and include defaults can also come from per-repo config after the first successful run.

What it writes

Under <config dir>/repos/owner/repo/ (see Caching):

  • SKILL.md and CODEBASE.md
  • PR_REVIEW_GUIDE.md and related review guides when PR sources were included

Every file is written by the AI provider. There is no offline or AI-free build, so init and sync refuse to run when no provider is configured.

SKILL.md holds the contribution guidance and links to CODEBASE.md for the codebase sections (layout, style, tests, development and debugging), so the same text is not repeated in both files and paid for twice in a review prompt. CODEBASE.md is where that text actually lives.

Findings read out of a single pull request stay out of the guidance sections: a request under review describes that request, not how the repository works. Only the review guide, built from recurring review findings, learns from them.

The guide is a method, not a list. Each pass states a general invariant a future change must satisfy, keeps the concrete case as an example under it, and ends with an exit check followed by its obligations, when <surface> changes → what must also change, so a reviewer who sees only a diff can apply the rule. PR_REVIEW_GUIDE.md is the short checklist and PR_REVIEW_DETAILED_GUIDE.md the full method.

The review guides need at least three review findings, drawn from PR discussions and merged-PR feedback. A repository with fewer keeps only SKILL.md and CODEBASE.md. When that happens init says why on one line:

[write] PR_REVIEW_GUIDE.md skipped: found 1 review signals, needs at least 3

The count is what init saw, so adding PR sources or another review signal and running sync can push a repository over the threshold. The threshold itself does not change.

Evidence and AI job results go into cache.db for faster sync. A provider call is retried three times, and if it still fails that one unit is dropped, or a response that never matches its shape is left out. A format or provider failure never fails the whole run: SKILL.md and CODEBASE.md are still written, and a guide the last run wrote is kept. Fetching and extraction are cached, so rerunning sync continues without re-fetching. After init succeeds, run review on a PR or local changes.

What it reports

The last line on stderr is the run's cost and time:

Done in 21.0s · 3,125 in, 1,308 out tokens · $0.0016

When the provider does not report a price the dollar field is cost unknown, and a cache-hit sync that made no AI call still prints the line with 0 in, 0 out tokens. stdout is unchanged, so piped output stays clean. review prints the same line.

JSON output

With --json, stdout is a single JSON object (schemaVersion 1) and every progress line goes to stderr. Fields: command (init or sync), repo, skillPath, changed[] (the sections this run rewrote, empty when the guide was already current), facts, pullRequests, commits, reviewGuide (detailed, single, or skipped), validation (errors[] and warnings[]), usage (tokensIn, tokensOut, costUsd, costNote), and durationMs. costUsd is null when the provider did not report a price. Without a terminal or saved config, --json exits with code 2 instead of prompting. Errors with --json are JSON on stdout as well.