Claude Redline
Redline enhances AI coding assistants by enabling real-time feedback during implementation.
The Problem
When working with AI coding assistants, you typically review work after it's done. This leads to:
- 🔄 Expensive rewrites when the approach was wrong
- 😤 Frustration when AI misunderstands requirements
- ⏰ Wasted time reviewing large changesets
- 🎯 Missed opportunities to guide implementation
The Solution
Redline creates natural checkpoints where Claude pauses and asks for your input:
You: "Build a user authentication system"
Claude: "Here's my implementation plan. Let me get your feedback first."
→ Browser opens with the plan
→ You highlight concerns, add comments
→ Click "Submit Review"
Claude: "Thanks! Based on your feedback, I'll use JWT instead of sessions..."
→ Implements Phase 1
Claude: "Phase 1 complete. Here's what I built:"
→ Browser opens with summary
→ You approve or request changes
Claude: → Continues to Phase 2...
Result: You guide the implementation in real-time, catching issues before they become expensive problems.
Features
- Automatic Review Triggers — Claude knows when to pause and ask for feedback
- Rich Markdown Rendering — Beautiful display of plans, specs, and summaries
- Text Highlighting — Select any text to add contextual comments
- Inline Comments — Detailed feedback directly on the document
- Structured Feedback — Returns JSON that Claude can act on
- Zero Config — Works immediately with Claude Desktop and Claude Code
- Customizable Themes — 6 built-in themes with easy extensibility
Quick Start
Prerequisites
Before installing Redline, you'll need uv (Python's fast package manager):
macOS/Linux:
curl -LsSf https://astral.sh/uv/install.sh | sh
Windows (PowerShell):
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
Verify installation: uv --version
Install as Plugin (Recommended)
The easiest way to install Redline is as a Claude Code plugin:
# Add the marketplace
/plugin marketplace add switchbm/claude-redline
# Install the plugin
/plugin install redline@redline-marketplace
This automatically configures the MCP server and adds the /redline slash command.
Verify installation:
/mcp
redline: connected
Auto-allow without permission prompts (optional):
Add to your ~/.claude/settings.json:
{
"permissions": {
"allow": ["mcp__redline__request_human_review"]
}
}
Manual Installation
<details> <summary><strong>Click to expand manual setup instructions</strong></summary>Claude Code Setup
Option 1: Global Installation (Recommended)
This makes Redline available in ALL your Claude Code sessions:
claude mcp add-json redline '{"type":"stdio","command":"uvx","args":["--from","git+https://github.com/switchbm/claude-redline","redline"],"timeout":86400000}' -s user
Option 2: Project-Specific Installation
# Run this from your project directory
claude mcp add-json redline '{"type":"stdio","command":"uvx","args":["--from","git+https://github.com/switchbm/claude-redline","redline"],"timeout":86400000}'
This creates/updates .mcp.json in your project root.
Local Development Setup
If you're developing Redline locally or want to run from source:
# Clone and install
git clone https://github.com/switchbm/claude-redline.git
cd claude-redline
uv sync --dev
# Add to Claude Code (global)
claude mcp add-json redline '{"type":"stdio","command":"uv","args":["run","--directory","/path/to/claude-redline","redline"],"timeout":86400000}' -s user
# Or project-specific (omit -s user)
claude mcp add-json redline '{"type":"stdio","command":"uv","args":["run","--directory","/path/to/claude-redline","redline"],"timeout":86400000}'
Replace /path/to/claude-redline with your actual clone path.
Claude Desktop Setup
<details> <summary><strong>Click to expand Claude Desktop instructions</strong></summary>Add to your config file:
| Platform | Location |
|---|---|
| macOS | ~/Library/Application Support/Claude/claude_desktop_config.json |
| Windows | %APPDATA%\Claude\claude_desktop_config.json |
| Linux | ~/.config/Claude/claude_desktop_config.json |
{
"mcpServers": {
"redline": {
"command": "uvx",
"args": ["--from", "git+https://github.com/switchbm/claude-redline", "redline"],
"timeout": 86400000
}
}
}
The timeout is set to 24 hours (86400000ms) to allow unlimited time for thorough document review.
Choose a Theme (Optional)
Redline includes 6 built-in themes. Add --theme <name> to customize the look:
| Theme | Description |
|---|---|
dark | Modern dark mode (default) |
clean | Clean professional blue/gray |
forest | Nature-inspired with earthy green tones |
ocean | Calm oceanic with blue and teal accents |
sunset | Warm sunset with orange and amber tones |
minimal | Ultra-clean with subtle contrasts |
claude mcp add-json redline '{"type":"stdio","command":"uvx","args":["--from","git+https://github.com/switchbm/claude-redline","redline","--theme","clean"],"timeout":86400000}' -s user
Or in .mcp.json:
{
"mcpServers": {
"redline": {
"type": "stdio",
"command": "uvx",
"args": ["--from", "git+https://github.com/switchbm/claude-redline", "redline", "--theme", "clean"],
"timeout": 86400000
}
}
}
{
"mcpServers": {
"redline": {
"command": "uvx",
"args": ["--from", "git+https://github.com/switchbm/claude-redline", "redline", "--theme", "ocean"],
"timeout": 86400000
}
}
}
List available themes:
uvx --from git+https://github.com/switchbm/claude-redline redline --list-themes
Use It
Tell Claude to present plans and summaries for review. Trigger words include "redline", "review", "present for review":
Build a REST API for user management. Present your implementation
plan for review first, then show me phase summaries as you complete them.
That's it! Claude will automatically open your browser for reviews at the right moments.
Note: Redline has no timeout - take as long as you need. The browser will stay open until you click "Submit Review".
Troubleshooting
<details> <summary><strong>MCP Timeout Errors</strong></summary>If you see "MCP error -32001: Request timed out", your MCP configuration may be missing the timeout setting.
Solution: Re-add Redline with a long timeout (the setup commands above include this by default):
claude mcp remove redline
claude mcp add-json redline '{"type":"stdio","command":"uvx","args":["--from","git+https://github.com/switchbm/claude-redline","redline"],"timeout":86400000}' -s user
The timeout value is in milliseconds (86400000 = 24 hours).
If the browser doesn't open automatically:
- Check the terminal/console output for a log message like "Opening browser to http://localhost:XXXXX" to find the dynamically-assigned port number
- Manually navigate to that URL in your browser
- Ensure you have a default browser configured
Note: Redline uses dynamic port allocation, so each instance runs on a different port to support multiple concurrent Claude Code sessions.
</details> <details> <summary><strong>Redline Not Appearing in /mcp</strong></summary>- Restart Claude Code after adding the MCP server
- Check your config with
claude mcp list - Verify the JSON syntax in your command
- For global install, ensure you used
-s user
How It Works
┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐
│ Claude Code │────▶│ Redline Server │────▶│ Browser UI │
│ or Desktop │ │ (MCP + HTTP) │ │ (React + TW) │
└─────────────────┘ └──────────────────┘ └─────────────────┘
│ │ │
│ 1. Calls tool with │ │
│ markdown spec │ │
│──────────────────────▶│ │
│ │ 2. Opens browser │
│ │─────────────────────▶ │
│ │ │
│ │ 3. User reviews, │
│ │ highlights, │
│ │ comments │
│ │◀───────────────────── │
│ 4. Returns JSON │ │
│ feedback │ │
│◀──────────────────────│ │
│ │ │
│ 5. Claude acts on │ │
│ feedback │ │
▼ ▼ ▼
Technical Details:
- MCP server communicates via stdio with Claude
- FastAPI HTTP server runs on a dynamically-allocated localhost port
- React frontend renders markdown and captures feedback
- Feedback returns as structured JSON
- Dynamic port allocation supports multiple concurrent Claude Code instances
Example Output
When you submit a review, Claude receives structured feedback like this:
{
"user_overall_comment": "Good approach, but consider caching",
"comments": [
{
"id": "c1a2b3c4",
"quote": "query the database on every request",
"text": "This could be slow with many users. Add Redis caching?",
"fullLineContext": "The API will query the database on every request",
"timestamp": "2024-12-01T10:30:00Z"
}
]
}
Claude uses this to adjust the implementation, addressing your specific concerns.
Prompt Templates
Copy-paste these prompts to trigger automatic reviews:
<details> <summary><strong>Implementation with Reviews</strong></summary>Build [FEATURE]. Before starting:
1. Present your implementation plan for review
2. After each major phase, show a summary for review
3. Address any feedback before continuing
Refactor [CODE/SYSTEM]. Present your refactoring plan for review first.
Show before/after comparisons at each step for approval.
Design the architecture for [SYSTEM]. Present options with pros/cons
for review. Wait for my decision before proceeding.
See PROMPT-TEMPLATES.md for 15+ more templates.
Documentation
| Document | Description |
|---|---|
| INTEGRATION.md | Detailed setup, architecture, troubleshooting |
| DATA-STRUCTURE.md | JSON response format specification |
| PROMPT-TEMPLATES.md | Copy-paste prompts for common scenarios |
| AUTO-REVIEW-SETUP.md | Workflow customization guide |
| CONTRIBUTING.md | How to contribute |
Development
Prerequisites
- Python 3.12+
- Node.js 18+ (for frontend changes)
- uv package manager
Setup
git clone https://github.com/switchbm/claude-redline.git
cd claude-redline
uv sync --dev
Running Tests
uv run pytest # Run tests with coverage
uv run mypy src/redline # Type checking
uv run ruff check . # Linting
Building Frontend
Only needed if you modify the React code:
python build_ui.py
Tech Stack
| Layer | Technology |
|---|---|
| MCP Server | Python 3.12, MCP SDK |
| HTTP Server | FastAPI, Uvicorn |
| Frontend | React 18, TypeScript, Vite |
| Styling | Tailwind CSS |
| Package Manager | uv |
Roadmap
- Customizable UI themes
- Dynamic port allocation (supports multiple concurrent instances)
- User-specified port configuration
- Multiple reviews in a single browser window
- Review history persistence
- VS Code extension
- Custom review templates
- Team collaboration features
Contributing
We welcome contributions! See CONTRIBUTING.md for guidelines.
Quick Links
License
MIT License - see LICENSE for details.
Acknowledgments
Built for the Model Context Protocol ecosystem.
<p align="center"> <strong>If Redline helps your workflow, consider giving it a ⭐</strong> </p>