Context Rail: Code Review Agent Client Integration Guide

Summary

@contextrail/code-review-agent is a CLI for running structured, AI-assisted PR/code reviews in your repository.

Use it to:

• review a git diff (--from / --to)
• review explicit files (--files / --file)
• emit machine-readable review artifacts (result.json, reviewer logs, token metrics)

Install and Run

Choose one:

• No install (recommended to start):

npx -y @contextrail/code-review-agent review --help

• Project dependency:

npm i -D @contextrail/code-review-agent
npx code-review-agent review --help

• Global install:

npm i -g @contextrail/code-review-agent
code-review-agent review --help

Configuration

Required (sensitive — use environment variables)

export CONTEXTRAIL_MCP_JWT_TOKEN="<your-contextrail-jwt-token>"
export OPENROUTER_API_KEY="<your-openrouter-key>"

These contain credentials and should not be passed as CLI flags to avoid exposure in shell history and process listings.

Getting Your ContextRail MCP Token

To get your CONTEXTRAIL_MCP_JWT_TOKEN:

1. Sign up at https://contextrail.app (if you don't have an account)
2. Get your token at https://contextrail.app/settings/profile

The token is used to authenticate with the ContextRail MCP server to retrieve your organization's review standards and contexts.

Required (env var or CLI flag)

export CONTEXTRAIL_MCP_SERVER_URL="https://<your-mcp-host>"
# or pass inline:
# --mcp-server-url https://<your-mcp-host>

Optional

export LLM_MODEL_ORCHESTRATOR="google/gemini-3-flash-preview"  # or --orchestrator-model
export LLM_MODEL_REVIEWER="qwen/qwen3-coder-next"              # or --reviewer-model
export LLM_MODEL_CRITIC="qwen/qwen3-coder-next"                # or --critic-model
export REVIEW_DOMAINS="security,architecture"                   # or --domains
export PR_DESCRIPTION="Optional PR context"                     # or --pr-description

Run Against a PR Diff

git fetch origin
BASE_SHA="$(git merge-base origin/main HEAD)"
HEAD_SHA="$(git rev-parse HEAD)"

npx -y @contextrail/code-review-agent review \
  --repo . \
  --from "$BASE_SHA" \
  --to "$HEAD_SHA" \
  --output ./.review

With optional domain focus:

npx -y @contextrail/code-review-agent review \
  --repo . \
  --from "$BASE_SHA" \
  --to "$HEAD_SHA" \
  --domains "security,architecture" \
  --output ./.review

Run Against Explicit Files

npx -y @contextrail/code-review-agent review \
  --repo . \
  --files "src/a.ts,src/b.ts" \
  --output ./.review

or:

npx -y @contextrail/code-review-agent review \
  --repo . \
  --file src/a.ts \
  --file src/b.ts \
  --output ./.review

Local Change Recipes

Staged files:

FILES_CSV="$(git diff --name-only --cached | paste -sd, -)"
[ -z "$FILES_CSV" ] && echo "No staged tracked files to review." && exit 1
npx -y @contextrail/code-review-agent review --repo . --files "$FILES_CSV" --output ./.review

Unstaged files:

FILES_CSV="$(git diff --name-only | paste -sd, -)"
[ -z "$FILES_CSV" ] && echo "No unstaged tracked files to review." && exit 1
npx -y @contextrail/code-review-agent review --repo . --files "$FILES_CSV" --output ./.review

Tracked changes vs HEAD:

FILES_CSV="$(git diff --name-only HEAD | paste -sd, -)"
[ -z "$FILES_CSV" ] && echo "No tracked local changes vs HEAD." && exit 1
npx -y @contextrail/code-review-agent review --repo . --files "$FILES_CSV" --output ./.review

Output and Exit Behavior

Primary output:

• ./.review/result.json

Additional artifacts:

• ./.review/orchestrator/*
• ./.review/reviewers/<reviewer>/*
• ./.review/token-budget.json

Exit codes:

• 0: all reviewers validated and final decision is approve
• 1: reviewer validation failed and/or final decision is request-changes

Troubleshooting

• Command "code-review-agent" not found
  • use npx -y @contextrail/code-review-agent ... or install globally
• Missing required env vars
  • set CONTEXTRAIL_MCP_JWT_TOKEN and OPENROUTER_API_KEY as environment variables
  • set CONTEXTRAIL_MCP_SERVER_URL as an environment variable or pass --mcp-server-url
• One reviewer failed with structured-output/schema errors
  • inspect ./.review/reviewers/<reviewer>/failures.md
  • inspect ./.review/reviewers/<reviewer>/progress.json

Related

• contributor guide: packages/code-review-agent/CONTRIBUTORS.md
• npm publishing guide: packages/code-review-agent/NPM_PUBLISHING.md
• model cost guide: packages/code-review-agent/MODEL_RECOMMENDATIONS.md