revisor

---

revisor is a codex-powered github review and repair cli. it clones pull requests and issues into temporary workspaces, runs the user's installed codex cli with bundled workflows, and then reports, patches, or opens a pull request depending on the command.

it is built for two audiences at once: humans who want a direct terminal command, and agents that need deterministic json output, non-interactive flags, and disposable workspaces.

why

if you already trust codex exec for code work, revisor gives it a narrower command surface for common github loops:

• review a pr without touching your local checkout
• debug an issue and get a source-backed diagnosis
• fix an issue in a temp clone and open or update a pr
• keep codex skills bundled with the tool instead of depending on ~/.codex/skills
• use --json, --no-input, and --dry-run in agent workflows
• clean up temp checkouts by default, with --keep when you want the workspace

quickstart

npm install -g @microck/revisor

revisor review https://github.com/owner/repo/pull/123
revisor debug https://github.com/owner/repo/issues/456
revisor fix https://github.com/owner/repo/issues/456 --yes

fix mutates remote state by design: it creates or updates a branch and opens or updates a pull request. for humans, omit --yes to get a confirmation prompt. for agents, pass --yes --no-input --json.

requirements

• codex installed and authenticated
• git
• gh authenticated for private repos, issue/pr metadata, forks, pushes, and pr creation
• node.js 18+ for the npm wrapper

prebuilt npm binary packages are used when available. if the matching platform package is not installed, revisor falls back to building the go binary locally, which requires go.

installation

npm

npm install -g @microck/revisor

the main package installs a small javascript launcher. published platform packages provide the go binary:

package	platform
@microck/revisor-darwin-arm64	macos apple silicon
@microck/revisor-darwin-x64	macos intel
@microck/revisor-linux-arm64	linux arm64
@microck/revisor-linux-x64	linux x64
@microck/revisor-win32-arm64	windows arm64
@microck/revisor-win32-x64	windows x64

if the optional platform package is missing, the launcher builds from source on first run. that fallback is useful for local tarballs and unusual platforms, but normal npm installs should use prebuilt packages.

from source

git clone https://github.com/Microck/revisor
cd revisor
npm test
npm run build
node bin/revisor.js --help

build all npm platform binaries:

npm run build:prebuilts

command surface

command	purpose
revisor review <pr-url>	clone a pr, check out the pr branch, and run a read-only codex review
revisor debug <url-or-text>	diagnose an issue, pr, or text prompt without remote mutation
revisor fix <issue-url>	fix a github issue, push a branch, and open or update a pr
revisor issue <issue-url>	alias for fix

workflows

review

revisor review https://github.com/owner/repo/pull/123

review clones the repository into a temp directory, checks out the pr branch, and runs codex with revisor's bundled review workflow. codex runs in a read-only sandbox and is instructed not to modify files.

useful flags:

flag	description
--json	print a machine-readable run summary
--keep	keep the temp checkout and print its path
--model <model>	pass a model to codex exec
--no-input	disable codex approval prompts

debug

revisor debug https://github.com/owner/repo/issues/456
revisor debug "why does this cli hang after startup?"

debug is for diagnosis. with a github url, it clones the repository and includes issue or pr metadata in the codex prompt. with plain text, it runs in the current directory. it uses a read-only sandbox by default and does not push, commit, or open prs.

fix

revisor fix https://github.com/owner/repo/issues/456 --yes

fix is the remote-mutating path:

1. clone the target repository into a temp directory
2. create or reuse a branch named revisor/issue-<number>-<slug>
3. run codex with revisor's bundled fix workflow
4. commit the resulting diff with a Revisor-Run: <issue-url> footer
5. push the branch
6. open or update a pull request
7. delete the temp checkout unless --keep is set

for repos owned by the authenticated user, revisor uses an upstream branch when a fork is unavailable and gh reports write access. for other repos, it prefers a fork branch.

use patch-only mode when you want the fix but no remote mutation:

revisor fix https://github.com/owner/repo/issues/456 --patch-only --patch ./issue-456.patch

flags

flag	default	description
--branch <name>	generated	override the revisor/issue-N-slug branch name
--codex <path>	codex	codex executable to run
--dry-run	false	print planned commands and prompt text without mutating state
--json	false	print a structured run summary
--keep	false	keep the temp checkout
--model <model>	unset	pass a model to codex exec
--no-input	false	set codex approval policy to never
--patch <path>	generated	patch destination for --patch-only
--patch-only	false	write a patch instead of pushing/opening a pr
--sandbox <mode>	workspace-write	codex sandbox for writable commands
--tmp-dir <path>	os temp dir	parent directory for temp checkouts
--upstream-branch	false	push to upstream instead of a fork
-y, --yes	false	approve push/pr creation without prompting
-h, --help		show help
--version		print version

for review and debug, revisor forces codex into read-only mode. for fix, --sandbox controls the writable codex run.

agent usage

use --json --no-input --yes for non-interactive fix runs:

revisor fix https://github.com/owner/repo/issues/456 \
  --yes \
  --no-input \
  --json

example json shape:

{
  "command": "fix",
  "target": {
    "owner": "owner",
    "repo": "repo",
    "kind": "issue",
    "number": 456,
    "url": "https://github.com/owner/repo/issues/456"
  },
  "tempPath": "/tmp/revisor-123/repo",
  "kept": false,
  "prUrl": "https://github.com/owner/repo/pull/789",
  "exitCode": 0
}

progress, clone output, and codex diagnostics go to stderr/stdout as produced by the underlying tools. the json summary is intended as the stable completion artifact.

agent skill

this repo includes a source skill at skills/revisor/SKILL.md for agents that should route github pr reviews, issue diagnosis, and issue fixes through revisor.

safety model

• review and debug are read-only codex runs
• fix requires a github issue url
• fix prompts before remote mutation unless --yes is provided
• fix --patch-only avoids push and pr creation
• temp checkouts are deleted by default
• --keep preserves the checkout when you need to inspect or continue manually
• revisor never depends on user-installed codex skills; prompts are bundled in the binary

examples

review a pr:

revisor review https://github.com/Microck/tailstick/pull/47

diagnose an issue:

revisor debug https://github.com/Microck/tailstick/issues/46

open or update a pr from an issue:

revisor fix https://github.com/Microck/tailstick/issues/46 --yes

run a dry-run to inspect the planned codex prompt:

revisor fix https://github.com/Microck/tailstick/issues/46 --dry-run --yes

generate a patch only:

revisor fix https://github.com/Microck/tailstick/issues/46 \
  --patch-only \
  --patch ./tailstick-46.patch

keep the temp checkout:

revisor review https://github.com/Microck/tailstick/pull/47 --keep

development

run tests:

npm test

build the local binary:

npm run build

build all prebuilt npm package binaries:

npm run build:prebuilts

package smoke test:

npm pack
tmp="$(mktemp -d)"
cd "$tmp"
npm init -y
npm install /path/to/microck-revisor-0.1.0.tgz
./node_modules/.bin/revisor --version