crewmate
v0.7.0
Published
Watch GitHub PRs and issues for @crewmate mentions and reply with AI-generated explanations
Readme
crewmate
Watch GitHub PR comments (review and conversation) and issues for @crewmate mentions and reply with an AI-generated explanation.
Before you start
You need:
- GitHub CLI (
gh) installed and authenticated. - An LLM provider CLI in your PATH. The default is
claude(Anthropic's CLI), but you can use anyclaude-shaped CLI (--version,--model,-p) via--provideror config. Wrap other tools in a shim if needed.
Caveats
- Provider default is
claude. If you don't haveclaudeinstalled, set a different provider in your config or with--provider <command>. - Crewmate adds an
eyesreaction to each new@crewmatemention and swaps it for a thumbs-up or thumbs-down before posting the reply. --dry-rundoes not persist state. Any@crewmatemention it discovers will be reprocessed on the next poll. State already saved by a previous non-dry-run run is still honored.- Conversation comments and issue bodies/comments may be reprocessed if the state file is lost, because GitHub does not expose a parent id for top-level conversation replies or issue body edits.
- Repo scope uses the GitHub search API. Large repos may hit rate limits; use a longer
--intervalfor busy repositories.
Install
npm install -g crewmateIn non-TTY / agent shells, npx may hang waiting for an install confirmation. If you run via npx, use npx --yes crewmate ... so the command proceeds without a TTY.
You can also install the crewmate skills from this repository:
npx skills add YogliB/crewmate --skill crewmate
npx skills add YogliB/crewmate --skill crewmate-streamIf you are building from source, see docs/CONTRIBUTING.md.
Usage
crewmate watch [<target>] [options]
crewmate stream [<target>] [options]<target> is optional when crewmate watch or crewmate stream is run inside a git repository whose origin remote points to GitHub; it defaults to that repository. When provided, it can be:
- A single PR:
https://github.com/owner/repo/pull/4orowner/repo/pull/4. - A single issue:
https://github.com/owner/repo/issues/4orowner/repo/issues/4. - A repository:
https://github.com/owner/repoorowner/repo. - For GHES, use a full URL (
https://ghe.example.com/owner/repo).
Organization scope is not supported. A repository target watches open PRs and open issues by default; add --closed to include closed ones. To watch a specific closed PR or issue, pass its URL explicitly.
crewmate watch
Polls the target and replies to each new @crewmate mention with an explanation generated by the provider.
--interval <seconds>— seconds between polls. Default is60.--closed— for repository targets, also watch closed PRs and issues. Single PR/issue targets work regardless of state.--model <model>— use a specific model for explanations.--provider <command>— use a specific provider CLI instead ofclaude.--prompt <text>— prepend custom instructions to the LLM prompt. The default review prompt is in assets/SYSTEM_PROMPT.md.--timeout <seconds>— kill a provider call that runs longer than this. Default is600.--log— mirror structured log lines to stderr as well as writing them to the log file.--dry-run— preview the reply on stdout without posting to GitHub. Polls continuously like regular watch mode, but does not persist state.--user <login>— only reply to comments from this GitHub user (defaults to the activeghuser when omitted and not set in config). Always respected.--unsafe-no-user— reply to comments from any GitHub user. Disables the default filter that falls back to the activeghuser. This flag wins over--user.--debug— emit extra poll pipeline detail (fetched-comments,mention-filter,new-mentions) to the log.
crewmate watch never checks out, commits, or pushes code. It reads PR file contents through the GitHub API, so it can run anywhere, on any branch, with a dirty working tree.
crewmate stream
Emit new @crewmate mentions as NDJSON to stdout without invoking a provider or posting replies. Use this to feed an agent or another pipeline.
--interval <seconds>— seconds between polls. Default is60.--closed— for repository targets, also emit mentions from closed PRs and issues. Single PR/issue targets work regardless of state.--log— mirror structured log lines to stderr as well as writing them to the log file.--ack— post aneyesreaction to each new mention and include the returnedreactionIdin the emitted event. Useful when an agent is the handler.--output-file <path>— also append each emitted NDJSON line to the given file, creating its parent directory if needed. Useful when stdout is piped to a slow or non-TTY consumer.--since <ISO-timestamp>— only emit mentions whose GitHubcreated_atis at or after this timestamp. Useful when starting a stream and you want to skip older comments. A timestamp without an offset is read as UTC.--user <login>— only emit mentions from this GitHub user (defaults to the activeghuser when omitted and not set in config). Always respected.--unsafe-no-user— emit mentions from any GitHub user. Disables the default filter that falls back to the activeghuser. This flag wins over--user.--debug— emit extra poll pipeline detail (fetched-comments,mention-filter,new-mentions) to the log.
crewmate stream can run outside a git working tree. The <target> can be a single PR, an issue, a repo, or a GHES full URL. Each emitted line is a JSON object with at, event, owner, repo, number, commentId, kind, user, body, url, and path/line for review comments. When --ack is used, reactionId is also included.
State (tracked mentions) is stored in <config>/crewmate/state.json and logs in <config>/crewmate/crewmate.log, where <config> is $XDG_CONFIG_HOME, $HOME/.config (or %USERPROFILE%/.config on Windows), or the current working directory if none of those are set.
Reliability
- Jobs, not fire-and-forget. Each new mention becomes a job in the state file with a status of
pending,running,succeeded, orfailed. A crash between polls leaves jobspending, and the next poll retries them. - Retries with backoff. A failed reply is retried up to 3 times with an exponential backoff starting at 60 seconds. After the last attempt,
crewmateposts an error reply to the mention instead of silently dropping it. - Atomic state writes. State is written to a temporary file and renamed into place, so a crash never leaves a half-written
state.json. - Single watcher per config directory.
watchandstreamtake a lock in<config>/crewmate/lock; a second process on the same config directory exits instead of double-posting. - Bounded state and logs. Each target keeps at most 500 tracked mentions (oldest finished jobs are pruned), and
crewmate.logis rotated tocrewmate.log.1when it exceeds 1 MB. - Provider timeouts. A provider call that exceeds
--timeoutis killed and treated as a job failure (retried per the backoff above).
Configuration
Optional defaults live in a single flat file: <config>/crewmate/config.json.
Keys: provider, model, interval, user, prompt, log, debug, unsafeNoUser, and timeoutSeconds. CLI flags always win over the config file. Unknown keys and keys removed in 0.7.0 (fix, dryRun, defaults, profiles) are warned about and ignored. Invalid types for known keys are warned and ignored. See assets/config.schema.json for the schema; point your IDE at it for validation and autocomplete.
Example config.json:
{
"$schema": "https://raw.githubusercontent.com/YogliB/crewmate/main/assets/config.schema.json",
"interval": 120,
"provider": "my-llm",
"prompt": "Be terse"
}Log events
Each line in crewmate.log is an NDJSON object with an at ISO-8601 timestamp and an event field. Events include:
poll— started a poll iteration.mention— found a new@crewmatemention.reply— posted or would post a comment reply (kind: explain|error,failedon errors).warning— a recoverable problem such as an empty provider response, a poll failure, or a corrupted state file.error— an unhandled failure that stops the watch loop (errorType,message,stack).info— a notice such as dry-run mode.debug— diagnostic detail about the poll pipeline (stage: fetched-comments|mention-filter|new-mentions), useful for figuring out why a mention was or wasn't picked up.
Additional fields vary by event (e.g., owner, repo, number, commentId, url, path).
Example
crewmate watch owner/repo/pull/4
crewmate watch owner/repo --interval 120 --user myorg-botMore docs
- Contributing — build, test, and submit changes.
- Troubleshooting — common runtime issues.
- Security — how to report vulnerabilities.
- Changelog — what changed.
- Architecture — how the code is organized.
- AGENTS.md — setup and commands for coding agents.
