A reference implementation is available at
redline.
Key features:
- Claude (or you) decides when a review is necessary
- Claude Code is in full control of the reviewer agent — it runs as an async background process
- Both agents are observable, customizable, and cost-monitored on OpenRouter
- Log into both agents with one command:
redline login
- Implemented as a single Claude Code stop hook, providing transparency and customizability on the agent and model(s) used
What This Achieves
Every time Claude Code finishes a response and there
are uncommitted changes, a hook automatically triggers
a background Codex code review — without blocking your
workflow. You keep working while the review runs. When
it finishes, Claude reads the output and presents the
findings.
Claude Code Stop event
→ redline check (fast, <1s)
→ git diff --stat HEAD (any uncommitted changes?)
→ hash diff stat, compare to .git/redline-last-diff
→ if changes exist AND diff has changed since last check:
save hash to .git/redline-last-diff
output { "decision": "block", "reason": "..." }
reason includes diff stat summary
Claude decides if changes warrant a review
Claude spawns `redline review` as background task
→ codex exec review streams output in real-time
→ user can monitor, kill, or keep working
→ when done, Claude reads output, presents findings
→ if no changes OR same diff as last check:
exit 0 silently → Claude proceeds normally
No background processes, no daemons, no filesystem
protocols. The hook is the trigger, and Claude Code’s
own background task system handles async execution.
Prerequisites
Configuring OpenRouter
Both agents route inference through OpenRouter, but
they use different API skins with different base URLs.
Claude Code
Set these environment variables in your shell profile
(~/.zshrc, ~/.bashrc). Do not use a .env
file — Claude Code doesn’t read them.
export ANTHROPIC_BASE_URL="https://openrouter.ai/api"
export ANTHROPIC_AUTH_TOKEN="sk-or-..."
export ANTHROPIC_API_KEY=""
The base URL is https://openrouter.ai/api — no
/v1 suffix. This is OpenRouter’s Anthropic Skin,
which speaks the native Anthropic protocol. Using
/v1 causes model-not-found errors.
ANTHROPIC_API_KEY must be explicitly empty to
prevent Claude Code from authenticating directly
with Anthropic.
Verify by running /status in a Claude Code session.
See the full
Claude Code integration guide
for details.
Codex CLI
Create or edit ~/.codex/config.toml:
[model_providers.openrouter]
name = "openrouter"
base_url = "https://openrouter.ai/api/v1"
env_key = "OPENROUTER_API_KEY"
Then set the API key:
export OPENROUTER_API_KEY="sk-or-..."
At runtime, pass
-c 'model_provider="openrouter"' to select the
OpenRouter provider.
Common pitfalls:
- Codex CLI does not have a
--provider flag —
use -c for all runtime config overrides
- The TOML section is
[model_providers.openrouter],
not [provider.openrouter]
- Codex uses
https://openrouter.ai/api/v1 (with
/v1), while Claude uses
https://openrouter.ai/api (without /v1) —
they use different protocol skins
See the full
Codex CLI integration guide
for details.
Understanding the Stop Hook
Claude Code has a hook system configured in
settings.json. The key hook for this use case is
Stop, which fires every time Claude finishes a
response cycle.
How decision: "block" works
- The hook command runs and outputs JSON to stdout
- If the JSON contains
"decision": "block" with a
"reason" string, Claude Code:
- Does not stop — it continues the conversation
- The
reason text is injected into Claude’s
context as new information
- Claude processes it and acts on it (e.g.,
spawning a background task as instructed)
- If the command exits 0 with no JSON output, Claude
proceeds normally (no blocking)
- If the command exits non-zero, it’s treated as a
non-blocking error
This is the key mechanism: the check command uses
decision: "block" to inject a diff stat summary
and review instructions into Claude’s context. Claude
sees the summary, decides whether the changes warrant
a review, and if so spawns the review command via its
Bash tool. The background task appears in Claude’s
task list — visible, monitorable, and killable.
Settings file locations
In order of precedence:
~/.claude/settings.json — global (all projects)
.claude/settings.json — project (shareable,
committed)
.claude/settings.local.json — project (local,
gitignored)
Use .claude/settings.local.json for the review
hook so it doesn’t affect other collaborators.
Hook configuration
{
"hooks": {
"Stop": [
{
"hooks": [
{
"type": "command",
"command": "redline check",
"timeout": 10
}
]
}
]
}
}
The timeout is 10 seconds — the check is fast. This
is much lower than the 300s you’d need for a
synchronous review.
Why Async Matters
A simpler synchronous approach — running the full
review inside the Stop hook — has three problems:
- Blocking.
codex exec review can take minutes.
A synchronous Stop hook blocks Claude Code the
entire time — no progress visibility, no way to
cancel.
- No filtering. The hook fires after every
response, even when Claude just answered a question
and made no code changes.
- Duplicate reviews. Nothing prevents the hook
from triggering a second review while one is
already running.
The async approach solves all three: the check is
fast (<1s), only fires when changes exist, hashes
the diff stat to skip when nothing has changed since
the last check, and the reason text tells Claude to
skip if a review is already running. The actual
review runs as a Claude Code background task that the
user can monitor and kill.
The Two-Command Architecture
The tool splits into two commands: check (the
fast gate, called by the hook) and review (the
actual work, spawned by Claude as a background task).
Building the check command
The check command runs on every Stop event and must
complete in under a second.
import { execSync } from "child_process";
import {
existsSync,
readFileSync,
writeFileSync,
} from "fs";
import { join } from "path";
function getDiffStat(): string {
// Prefer diff --stat for a concise summary
const diff = execSync("git diff --stat HEAD", {
encoding: "utf-8",
}).trim();
if (diff) return diff;
// Fall back to status for untracked files
return execSync("git status --porcelain", {
encoding: "utf-8",
}).trim();
}
function hash(s: string): string {
let h = 0;
for (let i = 0; i < s.length; i++) {
h = ((h << 5) - h + s.charCodeAt(i)) | 0;
}
return h.toString(36);
}
function check(model?: string): void {
const diffStat = getDiffStat();
if (!diffStat) {
process.exit(0);
}
// Deduplicate: skip if diff unchanged since last check
const gitDir = execSync("git rev-parse --git-dir", {
encoding: "utf-8",
}).trim();
const hashFile = join(gitDir, "redline-last-diff");
const currentHash = hash(diffStat);
if (existsSync(hashFile)) {
const lastHash = readFileSync(
hashFile,
"utf-8",
).trim();
if (lastHash === currentHash) {
process.exit(0);
}
}
writeFileSync(hashFile, currentHash);
const cmd = model
? `redline review --model ${model}`
: "redline review";
const hookOutput = {
decision: "block",
reason: [
"Redline: Here is a summary of uncommitted",
"changes since the last review:",
"",
diffStat,
"",
"If these changes are substantial enough to",
"warrant a code review (e.g., new logic, bug",
"fixes, refactors — not just formatting or",
"comments), run the following command as a",
"background task:",
"",
` ${cmd}`,
"",
"If the changes are trivial, or a review is",
"already running, skip it. When a review",
"completes, assess the findings and inform",
"the user of any issues.",
].join("\n"),
};
console.log(JSON.stringify(hookOutput));
}
The check uses git diff --stat HEAD for a concise
summary of what changed, falling back to
git status --porcelain for untracked files. It
hashes the diff stat and stores it in
.git/redline-last-diff — if the diff hasn’t changed
since the last check, the hook exits silently. This
prevents the same diff from repeatedly firing the
hook. The diff stat is included in the reason text so
Claude can decide whether the changes warrant a
review.
Building the review command
The review command is spawned by Claude as a
background task. It streams Codex output in real-time
for progress visibility, then prints a final summary.
import { spawn } from "child_process";
import { readFileSync, unlinkSync } from "fs";
import { join } from "path";
import { tmpdir } from "os";
async function review(model?: string): Promise<void> {
const outputFile = join(
tmpdir(),
`redline-review-${Date.now()}.txt`,
);
const args = [
"exec",
"review",
"-c",
'model_provider="openrouter"',
"--uncommitted",
"-o",
outputFile,
];
if (model) {
args.push("-c", `model="${model}"`);
}
// Stream output in real-time so background task
// shows progress
const exitCode = await new Promise<number>(
(resolve) => {
const proc = spawn("codex", args, {
cwd: process.cwd(),
env: process.env,
stdio: ["ignore", "inherit", "inherit"],
});
proc.on("close", (code) => resolve(code ?? 1));
},
);
// Read the final review from the -o output file
let review = "";
try {
review = readFileSync(outputFile, "utf-8").trim();
unlinkSync(outputFile);
} catch {
// No output file — output was already streamed
}
if (exitCode !== 0 && !review) {
console.error(`Codex review failed (exit ${exitCode}).`);
process.exit(1);
}
if (review) {
console.log("\n--- Review Summary ---\n");
console.log(review);
}
}
Key details:
codex exec review --uncommitted — reviews all
staged, unstaged, and untracked changes
stdio: "inherit" — streams Codex output in
real-time so the background task shows progress
-o <file> — writes the last agent message to a
file for reliable output capture
-c 'model_provider="openrouter"' — routes
through OpenRouter
- Optional:
-c 'model="openai/gpt-5.4-pro"' for
model override
- Exit code is checked — if Codex fails and produced
no output, the tool exits with an error
The reason text that instructs Claude
The check command’s reason field includes the diff
stat and lets Claude decide whether to review:
Redline: Here is a summary of uncommitted changes
since the last review:
src/commands/check.ts | 25 +++++++++++++++------
src/commands/review.ts | 12 +++++-----
2 files changed, 22 insertions(+), 15 deletions(-)
If these changes are substantial enough to warrant
a code review (e.g., new logic, bug fixes, refactors
— not just formatting or comments), run the
following command as a background task:
redline review
If the changes are trivial, or a review is already
running, skip it. When a review completes, assess
the findings and inform the user of any issues.
Claude sees the summary, judges whether the changes
are substantive, and either spawns the review as a
background task or skips it. When the review
completes, Claude reads the streamed output and
presents the findings.
Installing and Removing the Hook
The tool should provide commands to programmatically
install and remove the hook from
.claude/settings.local.json.
Install
Read .claude/settings.local.json, deep-merge the
Stop hook entry, and write back. Create the .claude/
directory if needed. Be idempotent — if the hook
already exists with the same config, skip. If it
exists with a different model, update it. Identify
your hooks by command prefix (commands starting with
"redline").
The resulting file:
{
"hooks": {
"Stop": [
{
"hooks": [
{
"type": "command",
"command": "redline check",
"timeout": 10
}
]
}
]
}
}
Remove
Filter out hook entries whose command starts with
"redline". Clean up empty arrays and objects
(remove Stop: [] if empty, remove hooks: {} if
empty).
Implementation
import {
readFileSync,
writeFileSync,
mkdirSync,
} from "fs";
import { join } from "path";
const SETTINGS_PATH = join(
".claude",
"settings.local.json",
);
const HOOK_PREFIX = "redline";
function readSettings(): Record<string, unknown> {
try {
return JSON.parse(
readFileSync(SETTINGS_PATH, "utf-8"),
);
} catch {
return {};
}
}
function writeSettings(
settings: Record<string, unknown>,
): void {
mkdirSync(".claude", { recursive: true });
writeFileSync(
SETTINGS_PATH,
JSON.stringify(settings, null, 2) + "\n",
);
}
function installHook(model?: string): void {
const settings = readSettings();
const command = model
? `${HOOK_PREFIX} check --model ${model}`
: `${HOOK_PREFIX} check`;
const hookEntry = {
hooks: [
{
type: "command",
command,
timeout: 10,
},
],
};
const hooks = (settings.hooks ?? {}) as Record<
string,
unknown[]
>;
const stopHooks = (hooks.Stop ?? []) as Array<{
hooks: Array<{ command: string }>;
}>;
// Check for existing redline hook
const existing = stopHooks.findIndex((h) =>
h.hooks?.some((inner) =>
inner.command?.startsWith(HOOK_PREFIX),
),
);
if (existing >= 0) {
stopHooks[existing] = hookEntry;
} else {
stopHooks.push(hookEntry);
}
hooks.Stop = stopHooks;
settings.hooks = hooks;
writeSettings(settings);
}
function removeHook(): void {
const settings = readSettings();
const hooks = (settings.hooks ?? {}) as Record<
string,
unknown[]
>;
const stopHooks = (hooks.Stop ?? []) as Array<{
hooks: Array<{ command: string }>;
}>;
hooks.Stop = stopHooks.filter(
(h) =>
!h.hooks?.some((inner) =>
inner.command?.startsWith(HOOK_PREFIX),
),
);
if (
Array.isArray(hooks.Stop) &&
hooks.Stop.length === 0
) {
delete hooks.Stop;
}
if (Object.keys(hooks).length === 0) {
delete settings.hooks;
}
writeSettings(settings);
}
Putting It Together
The full CLI has four commands:
# Install the hook
redline install
# Install with a specific review model
redline install --model openai/gpt-5.4-pro
# Remove the hook
redline off
# Run a review manually (prints to stdout)
redline review
# Fast gate check (called by the Stop hook)
redline check
Full CLI entry point
const args = process.argv.slice(2);
const command = args[0];
const modelFlag = args.indexOf("--model");
const model =
modelFlag >= 0 ? args[modelFlag + 1] : undefined;
switch (command) {
case "install":
installHook(model);
console.log(
"Hook installed in",
".claude/settings.local.json",
);
break;
case "off":
removeHook();
console.log("Hook removed.");
break;
case "check":
check(model);
break;
case "review":
review(model);
break;
default:
installHook(model);
console.log(
"Hook installed in",
".claude/settings.local.json",
);
break;
}
Testing
Verify hook installation
redline install
cat .claude/settings.local.json
You should see the Stop hook entry with the
redline check command and a 10-second timeout.
Test check with no changes
Ensure your working tree is clean, then:
No output — the check exits silently when there are
no uncommitted changes.
Test check with changes
Make a small change to any file, then:
You should see JSON with "decision": "block" and a
"reason" containing the diff stat summary and
review instructions.
Test review
You should see streamed Codex output followed by a
review summary.
Full integration test
- Install the hook:
redline install
- Start Claude Code:
claude
- Ask Claude to make a small code change
- When Claude finishes, the Stop hook fires the
check — if there are uncommitted changes, Claude
spawns the review as a background task
- You can keep working while the review runs
- When the review completes, Claude reads the output
and presents any findings
Limitations and Future Work
Claude Code only
This pattern relies on Claude Code’s
decision: "block" hook output, which injects
instructions directly into the agent’s conversation.
Codex CLI’s hook system (as of early 2026) is more
limited — its Stop hook is fire-and-forget and
cannot feed structured output back into the model’s
context. Native hooks ([[hooks]] in config.toml)
support several events, but only SessionStart can
feed stdout into the model. There is no equivalent of
decision: "block" + reason for injecting
mid-session instructions. When Codex adds full
structured hook output support, this pattern can be
extended.
Review granularity
The review covers everything uncommitted — all
staged, unstaged, and untracked changes. It does not
distinguish between changes Claude just made and
pre-existing uncommitted work. Future versions could
use smarter change detection (e.g., diffing against a
baseline snapshot taken before Claude’s response).
Resources