Stage CLI Code Review

Stage CLI Code Review

Skill by ara.so — Devtools Skills collection.

Stage CLI is a code review tool that organizes local code changes into logical chapters and highlights what to review. It runs entirely on your local machine and works with any AI agent to help you review code before committing or creating pull requests.

Installation

Install globally via npm:

npm install -g stagereview

Or use directly with npx:

npx stagereview

Core Commands

Basic Review

Review your current changes (auto-detects what to review):

stage-chapters

This will:

1. Analyze your git repository
2. Detect staged/unstaged/untracked changes
3. Organize changes into logical chapters
4. Open a browser UI for review

Review Staged Changes Only

Review only changes that are staged for commit:

stage-chapters --ref staged

Review Unstaged Changes Only

Review only unstaged working directory changes:

stage-chapters --ref unstaged

Review All Working Changes

Review staged + unstaged + untracked files:

stage-chapters --ref work

Diff Against Specific Branch

Compare your changes against a specific base branch:

stage-chapters --base develop

stage-chapters --base feature/authentication

stage-chapters --base origin/main

Common Workflows

Pre-Commit Review

Before committing, review staged changes:

git add .
stage-chapters --ref staged

Feature Branch Review

Review all changes in your feature branch against main:

stage-chapters --base main --ref work

Quick WIP Check

Review what you've changed since last commit:

stage-chapters --ref unstaged

Cross-Branch Comparison

Compare your current branch against another feature branch:

stage-chapters --base feature-a

Configuration Options

--base <ref>

Specifies the base git reference to diff against.

• Default: Auto-detects main, master, or develop
• Accepts: branch names, commit hashes, tags, remote refs

Examples:

--base main
--base origin/develop
--base abc123f
--base v1.2.0

--ref <mode>

Defines the scope of changes to review.

Options:

• work - All local changes (staged + unstaged + untracked)
• staged - Only changes in git staging area
• unstaged - Only working directory changes not staged
• Default: Auto-detects based on repository state

Examples:

--ref work
--ref staged
--ref unstaged

Integration with AI Agents

Stage CLI is designed to work seamlessly with AI coding agents. In your agent's chat interface:

/stage-chapters

Or with options:

/stage-chapters --ref staged --base develop

The agent can help you:

• Interpret the review chapters
• Identify potential issues
• Suggest improvements
• Explain complex changes

Programmatic Usage

While Stage CLI is primarily a command-line tool, you can integrate it into scripts:

#!/bin/bash
# Review script for CI/local checks

# Check if there are staged changes
if git diff --cached --quiet; then
  echo "No staged changes to review"
  exit 0
fi

# Run Stage review
stage-chapters --ref staged

#!/bin/bash
# Pre-push review workflow

MAIN_BRANCH="main"
CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD)

if [ "$CURRENT_BRANCH" != "$MAIN_BRANCH" ]; then
  echo "Reviewing changes against $MAIN_BRANCH..."
  stage-chapters --base $MAIN_BRANCH
fi

Understanding the Output

Stage CLI organizes changes into logical chapters based on:

• File proximity - Related files grouped together
• Change type - New files, modifications, deletions
• Logical boundaries - Module/component boundaries
• Change complexity - Similar complexity levels grouped

The browser UI shows:

• Chapter overview with file lists
• Contextual diff views
• Review points and suggestions
• Navigation between chapters

Troubleshooting

"Not a git repository" Error

Stage CLI requires a git repository. Initialize one:

git init

No Changes Detected

Verify you have changes:

git status

If using --ref staged, ensure files are staged:

git add <files>

Base Branch Not Found

Ensure the base reference exists:

git branch -a  # List all branches
git log --oneline  # Check commit history

Use a valid reference:

stage-chapters --base origin/main

Port Already in Use

Stage CLI starts a local web server. If the port is occupied, it will try alternative ports automatically. Close any conflicting applications if issues persist.

Large Diffs Timeout

For very large changesets, consider:

1. Review in smaller chunks:

stage-chapters --ref staged  # Review staged first
stage-chapters --ref unstaged  # Then unstaged

2. Split commits into smaller logical units
3. Use more specific base branches

Browser Doesn't Open

Manually open the URL shown in terminal output (typically http://localhost:3000 or similar).

Best Practices

1. Review Early and Often

Run Stage reviews before commits, not just before PRs:

# After making changes
git add -p  # Interactively stage
stage-chapters --ref staged  # Review staged
git commit

2. Use Appropriate Scope

Match the --ref option to your workflow:

• Before commit: --ref staged
• Checking progress: --ref unstaged
• Full feature review: --ref work --base main

3. Leverage Chapter Organization

Use chapters to:

• Review related changes together
• Spot unintended cross-module coupling
• Identify missing changes in related files

4. Combine with AI Agent Review

Let the AI agent analyze Stage's output:

Review the chapters from Stage CLI and identify:
1. Potential bugs or edge cases
2. Missing error handling
3. Inconsistent patterns

5. Pre-PR Workflow

Before creating a pull request:

# Ensure all changes are committed
git add -A
git commit -m "Feature complete"

# Review full feature against main
stage-chapters --base main

# Address review findings
# Create PR

Advanced Usage

Reviewing Specific File Patterns

Stage reviews all changes, but you can prepare specific changes:

# Stage only TypeScript files
git add '*.ts'
stage-chapters --ref staged

# Stage specific directory
git add src/components/
stage-chapters --ref staged

Multi-Branch Comparison

Compare changes across multiple branches:

# Review branch A vs main
git checkout feature-a
stage-chapters --base main

# Review branch B vs main
git checkout feature-b
stage-chapters --base main

Integration with Git Hooks

Add to .git/hooks/pre-commit:

#!/bin/bash
# Launch Stage review before commit
stage-chapters --ref staged
read -p "Proceed with commit? (y/n) " -n 1 -r
echo
if [[ ! $REPLY =~ ^[Yy]$ ]]; then
  exit 1
fi

Additional Resources

• Website: https://stagereview.app
• Examples: https://stagereview.app/explore
• Blog: https://stagereview.app/blog
• Discord: https://discord.gg/Hs7Eexp3
• Twitter: https://x.com/StageReviewApp
• GitHub: https://github.com/ReviewStage/stage-cli

The full Stage experience on the website offers additional features like team collaboration, persistent reviews, and integration with GitHub pull requests.