External Reviewer planning
Bundle OKF 0.1 · 9 conceitos · julienlegoux/external-reviewer
Open source Repository Open in the app JSON README (API)
About
# External Reviewer planning
Planning bundle for External Reviewer — a CLI that reviews a repository on a model
from outside the Anthropic family and returns its report to the Claude Code session
that called it.
* [Concept](/CONCEPT.md) - What the product is, why it is a called binary rather than a gateway in front of the session, and where the judgment about models lives.
* [Scope](/SCOPE.md) - What v1 ships: users, goals, non-goals, constraints, and the three milestones.
* [Scope decisions](/scope/index.md) - The decision ledger behind SCOPE.md.
* [Specs](/SPECS.md) - The one-way technical doors: stack, the agent loop, confinement and the tools, interfaces, testing, distribution.
* [Specs decisions](/specs/index.md) - The decision ledger behind SPECS.md.
* [Conventions](/CONVENTIONS.md) - How code here is written, named, tested and committed: the personal baseline filtered to Go, with this project's deviations merged in.
* [Conventions decisions](/conventions/index.md) - The deviat
Details
- Kind
- OKF bundles
- Topic
- Developer tools
- Publisher
- julienlegoux
- Origin
- okf_github
- Category
- dados
- Version
- 0.1
- Last push
- 2026-08-14T09:12:53Z
- Repository state
- ativo
- Language
- Go
- Added
- 2026-09-08 22:08:51
- Updated
- 2026-09-08 22:08:51
- Origin id
julienlegoux/external-reviewer:docs/planning/index.md
README
# external-reviewer
A CLI that hands a repository to a second model for review. The model reads through four
read-only tools — `list`, `read_file`, `search`, `git_read` — against an explicitly
allowed slice of the repository, and returns markdown on stdout: leads for a reviewing
skill to verify against the files, not a verdict.
## Install
Go 1.26 or newer, and `git` on `PATH` for the `git_read` tool:
```
go install github.com/julienlegoux/external-reviewer@v0.1.0-beta.1
```
`@latest` resolves to the newest tag, which for now is the beta above — there is no
stable release yet.
## Quickstart
**1. Give `kern-link` a credential.** This binary reads none, stores none and has no
`login` command: provider credentials are resolved wholly by `kern-link`, from env vars
or its store at `~/.pi/agent/auth.json`, populated by its own `pi-ai login`. Use
`openai-codex` unless you have read the validation boundary below.
**2. Assign the tiers.** One hand-written, never-committed TOML at
`%AppData%\external-reviewer\config.toml` on Windows,
`$XDG_CONFIG_HOME/external-reviewer/config.toml` (or `~/.config/…`) elsewhere;
`EXTERNAL_REVIEWER_CONFIG` overrides the location with an absolute path.
```toml
[tiers.standard]
provider = "openai-codex"
model = "gpt-5.5"
```
**3. Check what this machine can actually reach**, before spending anything on a run:
```
external-reviewer tiers
external-reviewer models
```
**4. Review.** The system prompt and the task come from the caller, as a JSON request
object on stdin; `--allow` grants the subtrees the reviewer may read, and nothing outside
them is readable:
```
echo '{"system":"You are reviewing Go.","task":"Find correctness bugs in the tool layer."}' \
| external-reviewer review --allow internal/tools --allow docs/planning .
```
`external-reviewer help` prints the whole grammar. The report is on stdout; turn-by-turn
cost and diagnostics are on stderr.
## Validation boundary
The mechanism is fully generic: no provider is named anywhere in the binary except the
family classifier's data table, so all ~35 providers `kern-link` reaches stay usable. But
**v1 is validated against `openai-codex` over OAuth alone** — every other provider is
wired and reachable, not tested. Treat that as a boundary to act on: a provider outside
this one is unverified, whatever the classifier allows.
## What it does not do
- **Read-only, enforced structurally.** The write half of the filesystem API is not in
the codebase, and CI rejects it if it reappears. The binary writes nothing inside the
repository under review and produces no output file. The one exception lives outside
the repository: `kern-link`'s own credential store, rewritten in `~/.pi/agent/` when a
stored OAuth token is expired.
- No server, no daemon, no state between runs — one round trip per invocation.
## Where the plan lives
- [`docs/planning/SCOPE.md`](docs/planning/SCOPE.md) — what v1 ships.
- [`docs/planning/SPECS.md`](docs/planning/SPECS.md) — the stack and the CLI grammar.
- [`docs/planning/CONVENTIONS.md`](docs/planning/CONVENTIONS.md) — the repo's decided
standards.
- [`docs/epics/`](docs/epics/) — where implementation currently stands.