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:

bash

npm install -g stagereview

Or use directly with npx:

bash

npx stagereview

Core Commands

Basic Review

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

bash

stage-chapters

This will:

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

Review Staged Changes Only

Review only changes that are staged for commit:

bash

stage-chapters --ref staged

Review Unstaged Changes Only

Review only unstaged working directory changes:

bash

stage-chapters --ref unstaged

Review All Working Changes

Review staged + unstaged + untracked files:

bash

stage-chapters --ref work

Diff Against Specific Branch

Compare your changes against a specific base branch:

bash

stage-chapters --base develop

bash

stage-chapters --base feature/authentication

bash

stage-chapters --base origin/main

Common Workflows

Pre-Commit Review

Before committing, review staged changes:

bash

git add .
stage-chapters --ref staged

Feature Branch Review

Review all changes in your feature branch against main:

bash

stage-chapters --base main --ref work

Quick WIP Check

Review what you've changed since last commit:

bash

stage-chapters --ref unstaged

Cross-Branch Comparison

Compare your current branch against another feature branch:

bash

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:

bash

--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:

bash

--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:

bash

#!/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

bash

#!/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:

bash

git init

No Changes Detected

Verify you have changes:

bash

git status

If using

--ref staged

, ensure files are staged:

bash

git add <files>

Base Branch Not Found

Ensure the base reference exists:

bash

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

Use a valid reference:

bash

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:

Review in smaller chunks:

bash

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

Split commits into smaller logical units
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:

bash

# 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:

bash

# 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:

bash

# 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:

bash

# 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

bash

#!/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.

stage-cli-code-review

NPX Install

Tags

SKILL.md Content

Stage CLI Code Review

Installation

Core Commands

Basic Review

Review Staged Changes Only

Review Unstaged Changes Only

Review All Working Changes

Diff Against Specific Branch

Common Workflows

Pre-Commit Review

Feature Branch Review

Quick WIP Check

Cross-Branch Comparison

Configuration Options

--base <ref>

--ref <mode>

Integration with AI Agents

Programmatic Usage

Understanding the Output

Troubleshooting

"Not a git repository" Error

No Changes Detected

Base Branch Not Found

Port Already in Use

Large Diffs Timeout

Browser Doesn't Open

Best Practices

1. Review Early and Often

2. Use Appropriate Scope

3. Leverage Chapter Organization

4. Combine with AI Agent Review

5. Pre-PR Workflow

Advanced Usage

Reviewing Specific File Patterns

Multi-Branch Comparison

Integration with Git Hooks

Additional Resources

`--base <ref>`

`--ref <mode>`