prkit is a local app that keeps the user's pull request inbox across their GitHub accounts, writes guides (an agent's walkthrough of a PR's diff, or of a local branch's changes, chapter by chapter), and runs a fix agent that turns review comments into commits. Those commits wait in the app until the user clicks Push. The command talks to the running app, so everything you start shows up in the app too, labelled "Started from prkit CLI".
The installed CLI is the source of truth for flags: run prkit --help or prkit <command> --help whenever you're unsure. Read the command reference when you need a less common read, local tab or draft action, or versioned guide settings.
Start with prkit status
Run prkit status --json before anything else. It tells you whether prkit is open, the Outside agents access level, the accounts and their GitHub budget, any gh config directory prkit couldn't read (configDirProblems, whose accounts are missing until it can), and current guide and fix work. Use prkit accounts --json for account details and prkit agents --json for model options.
Exit codes tell you what to do next:
| Code | Meaning | What to do |
|---|---|---|
| 0 | Done | Carry on. |
| 1 | The action failed | Read the message: it says why (not found, needs an account, not ready, a GitHub error). |
| 2 | Usage error | Check prkit <command> --help. |
| 3 | prkit isn't open, Outside agents is off, or the CLI can't reach it | Tell the user what the message says, e.g. to open prkit and turn on Settings > Outside agents. Don't try to launch or configure prkit yourself. |
| 4 | Needs "Read and start work" | prkit is set to Read only. Tell the user; don't look for a way around it. |
| 130 | Interrupted by SIGINT or SIGTERM | The CLI closed its session. Guide and fix work continue in prkit. |
If your sandbox blocks loopback network, the command can't reach the app and exits with 3, saying so. Ask the user to allow network for it or allow this command outside the sandbox.
Output and paging
Use --json whenever you'll read the result yourself: it is the structured answer from prkit's MCP tool, unchanged. Use plain output when you're showing something to the user as is; it explains how to continue a page.
Paged reads take --limit (1 to 100) and --cursor. Keep the same command, target and filters, pass nextCursor verbatim, and continue until it is null. File patches can span pages: join text fragments for the same path in offset order until complete is true. File contents and fix patches are text items joined by offset. A true githubTruncated or threadsTruncated means GitHub omitted data; say so, even after the last local page.
A large answer can instead be _tag: "response-fragment". Keep the logical page's --cursor unchanged, follow nextResponseCursor with --response-cursor, join each text by offset, then parse the complete JSON. Only then follow its normal nextCursor. Don't treat one fragment as the full answer.
Naming a pull request
Pass a URL (https://github.com/owner/repo/pull/123) or owner/repo#123. For a GitHub Enterprise host, add --host when using the short form. If prkit can read the PR through more than one account, it fails and lists them; pass --account with the one the user means. Never silently switch accounts to make a call succeed.
Repository commands take owner/repo; inbox filters use --repo owner/repo. Accounts come from status or accounts, as host/login, not a token.
What it won't do, and why
Anything that writes to GitHub stays a click in the app: pushing, merging, posting or resolving comments and reviews, reviewers, labels, closing a PR. So do account and agent setup, Global or Repository settings changes, discarding or reverting fix work, and removing a local guide. This is on purpose: an agent reading PR content can be steered by it, so nothing it says can reach GitHub without the user seeing it first. A repository where the user enabled both automatic conflict resolution and automatic push is an existing exception: prkit's watcher can resolve and push conflicts on watched PRs.
Reading settings is allowed. At Read and start work you can also open, close, focus or reorder local tabs, save the app's inbox filters, edit or move local draft comments, mark files reviewed, and save PR-scope guide settings. These stay on the machine. Closing a tab doesn't close the PR on GitHub.
When the user asks for an excluded action, tell them it's waiting for them in prkit (and open the PR there with prkit pr open <pr> if that helps). Only do it another way, such as with gh, if the user explicitly asks you to.
Workflows
What's waiting on me
prkit inbox --json
prkit inbox --reason review-requested --json
prkit inbox --reason review-requested --sort waiting --json
prkit inbox --reason review-requested --sort risk --json
prkit inbox --reason authored --json
prkit inbox --reason involved --repo owner/repo --json
Summarize by repository and how long each has waited, say which PRs are small enough to review quickly (each carries its size), and say which already have a guide and how carefully to read it (risk, which --sort risk puts first: high, then medium, then low, then no rated guide, and the longest wait first inside a level). Add --account, --state, --draft, --checks, --search or --stacks when the user asks to narrow it. These reads don't change the app's saved filters.
Read the PR and its diff
prkit pr read <pr> --json
prkit pr files <pr> --limit 20 --json
prkit pr files <pr> --limit 20 --cursor '<nextCursor>' --json
prkit pr file <pr> --path src/a.ts --side new --json
prkit pr threads <pr> --json
prkit pr checks <pr> --json
prkit pr files <pr> gives the current PR's changed files and patches. prkit pr reviewed <pr> --json says which of those files the user already marked reviewed in prkit (changed means the file changed after they reviewed it, so it needs another look), so you can start with what they haven't seen. Mark files reviewed with prkit pr reviewed set <pr> --head-sha <headSha> --paths <path>, passing the headSha that read returned, only when the user asks: a mark is their judgment that they read the change. Read old or new file contents when the patch isn't enough. To explain an accepted guide's exact snapshot, get its attempt id from prkit guide revisions <pr> --json, then use prkit pr diff <pr> --attempt-id <attempt-id> --json. Don't assume today's diff is the one the guide reviewed.
Write a guide and report back
- Pick the agent. Read
prkit agents --json, follow its pages, and choose a ready, enabled instance with an unblocked model. Use itsinstancefor--agent, its modelslugfor--model, and only option ids and values advertised by that model. Repeat--option key=value;trueandfalseare booleans. Leave selection out for the PR's configured agent or prkit's default. - For a stack, read
prkit pr stack <pr> --jsonbefore choosing.--stack thiscovers this PR,--stack allcovers the stack, and--stack 1,3selects its numbered layers. Use--stackonce; numbered selection cannot be combined with--layers. The native form is--stack chosen-layers --layers 1 --layers 3.--regenerateincludes layers that already have guides. - Start it:
prkit guide generate <pr> --agent <instance> --model <model> --option effort=high --stack this - Wait for it. Guides take a few minutes:
prkit wait <pr> --for guide --timeout 600waitreturns when work stops or the timeout passes. Check the returned state for failure. Iffinishedis false, call it again. Don't loop onsleepand reads:waitis cheaper and prkit already watches GitHub. Useprkit guide progress <pr> --jsonfor narration and activity when asked. - Read it with
prkit guide read <pr> --jsonand give the user the summary, the before/after (content.flow, when there is one), the main risks, and what deserves a closer look. Mention they can read the full guide in the app.
For several PRs, start every guide first, then wait on each; prkit queues work behind running agents.
--focus and --guidance are versioned JSON edits that save this PR's settings when generation starts, not plain strings. Read prkit guide settings <pr> --json first. Use the matching scopes.pullRequest.focus.version or scopes.pullRequest.guidance.version as expectedVersion. Preserve current items and overrides that the user hasn't asked to change. See the reference for the JSON shapes and standalone PR settings saves. On a version conflict, read again and reconcile the user's change; don't overwrite the newer settings blindly.
Review local changes before a pull request
Use this when you or the user changed code in a local repository and the user wants to see what changed before it becomes a pull request: "walk me through what you changed", "guide my branch", "review my local changes". prkit copies a snapshot of the folder as it is (the branch's commits since its base, plus staged, unstaged and untracked files) and never changes the repository.
Run it from inside the repository, or pass --path:
prkit local guide --description "One or two sentences on what changed and why"
prkit local wait --timeout 600
prkit local read --json
prkit local guideanswers at once. A problem with the repository exits 1 with the reason, such as not a repository, nothing changed, no base found or no shared history: fix what it says, or tell the user. Pass--base <branch>when the branch didn't start from origin's default branch (prkit tries it, thenorigin/main,origin/master,mainandmaster), and--branch <name>for a branch's last commit alone, without uncommitted work.--agent,--modeland--optionpick the agent as forprkit guide generate.- Write
--descriptionas the author's claim: what changed and why, in plain words. The guide quotes it and checks it against the diff, so don't oversell. prkit local waitreturns when the guide is written. Iffinishedis false, call it again.- Read it with
prkit local read --json. Give the user the summary, the before/after (content.flow), the main risks, and anything the snapshot left out (status.run.leftOut: files over 50 MB, Git LFS files, nested repositories). prkit keeps every revision. - After more changes, run
prkit local guideagain for the next revision. "Nothing changed since revision N" means the guide is current;--regeneratewrites it again anyway.
Never stash, commit, switch branches or touch the user's files to make it work: prkit reads the folder as it is. prkit local stop stops a guide while it is written. Removing a local guide is the user's click in prkit.
To ask the agent that wrote a local guide something the guide doesn't say, use prkit local questions. It answers read-only, from a copy of the snapshot, and never touches the repository:
prkit local questions ask --question "Why is the limit read at startup?" --request-id ask-limit
prkit local questions wait --question-id <question-id> --timeout 600
prkit local questions list --json
The folder needs a guide first. Without --scope the question is about all the changes on the latest accepted revision (--revision picks another). For one chapter, pass --scope '{"_tag":"chapter","chapterId":"<id>"}' with an id from prkit local read --json; for diff lines, a lines scope as for a PR question. One question per local review is answered at a time, so wait for it or stop it with prkit local questions stop --question-id <question-id>. wait follows that one question until it is answered, stopped or failed; check its state and message. Asking again retries a stopped or failed question. prkit local questions pin --question-id <question-id> --pinned pins an answered question to its chapter in prkit.
Ask the guide's agent about a PR
When you or the user need something the guide doesn't say, ask the agent that wrote it. It already read the whole PR, answers read-only, and never touches GitHub.
prkit questions ask <pr> --question "Why does the retry stop after three tries?" --request-id ask-42
prkit questions wait <pr> --question-id <question-id> --timeout 600
A PR needs a guide first, and the question goes to its latest accepted revision unless you pass --revision. Without --scope it is about the whole PR. For one chapter, pass --scope '{"_tag":"chapter","chapterId":"<id>"}' with an id from prkit guide read <pr> --json. For diff lines, pass --scope '{"_tag":"lines","anchor":{"path":"src/a.ts","start":{"side":"new","line":12},"end":{"side":"new","line":18}}}', side new or old. The lines must sit inside one part of the revision's diff, or the question is refused.
One question is answered at a time per PR: asking while another is being answered fails with a conflict, so wait first or stop it with prkit questions stop <pr> --question-id <question-id>, which keeps the text written so far. questions wait follows the question you name until it is answered, stopped or failed, even when someone else asks about the same PR; check its state, since failed carries its reason in message. questions list reads every question. Asking again retries a stopped or failed question. Read the answer and tell the user what it says, and where it cites files and lines. To keep one in the guide for the user, prkit questions pin <pr> --question-id <question-id> --pinned pins an answered question to its chapter in prkit; --no-pinned unpins it.
Hand review comments to the fix agent
prkit comments add <pr> --path src/a.ts --line 42 --head-sha <headSha> --body "Handle the empty list" --request-id comment-42
prkit fix send <pr> --request-id fix-42
prkit wait <pr> --for fix --timeout 600
prkit fix read <pr> --json
Comments stay as local drafts. fix send sends every waiting draft unless you select repeated --draft-ids or --thread-ids from prkit comments list <pr> --json. Follow the fix read's pages. For the complete change, use prkit fix diff <pr> --turn-id <turn-id> --json or prkit fix patch <pr> --turn-id <turn-id> --json; the summary's latest diff can be cut.
Tell the user what changed and that the commit is waiting for Push in prkit. To adjust it, use prkit fix change <pr> --instructions "what to change" --request-id change-42. For merge conflicts, use prkit fix resolve <pr>. Each of these also waits for Push.
Show the user something
prkit pr open <pr> opens the PR in prkit and brings the app forward. Use it when the user should look at something themselves. prkit tabs list --json shows the open tabs; local close and focus actions leave guides, fixes and commits in place.
Retries
prkit comments add <pr>, prkit fix send <pr>, prkit fix change <pr>, prkit questions ask <pr> and prkit local questions ask take --request-id <id>. If a call timed out and you don't know whether it went through, retry with the same id: prkit returns the first answer instead of doing it twice. A lost response isn't automatically replayed. Read the current state before retrying other work commands.
GitHub budget
Reads come from prkit's cache, which prkit keeps fresh itself. Add --refresh only when the user wants the very latest and that command offers it. It spends their GitHub API budget, which they share with every other tool. Follow continuation cursors instead of refreshing every page.