npm package: @polarityinc/paragon
Description: Paragon is the First AI QA Engineer and the Worlds best code reviewer.
Author: Polarity Inc.
Latest version: 0.1.4

# Paragon

<p align="center">
  <img width="450" alt="Paragon Logo" src="https://www.polarity.cc/paragon.png" />
</p>

<h3 align="center">The Best Code Review Agent in the World</h3>

<p align="center">
  Paragon catches more issues than any other tool, runs faster than competitors,<br/>
  and maintains the highest security standards.
</p>

<p align="center">
  <a href="https://polarity.cc/paragon"><strong>Learn more »</strong></a>
</p>

<p align="center">
  <a href="#installation">Installation</a> •
  <a href="#quick-start">Quick Start</a> •
  <a href="#features">Features</a> •
  <a href="#cli-reference">CLI Reference</a> •
  <a href="#keyboard-shortcuts">Shortcuts</a> •
  <a href="#configuration">Configuration</a>
</p>

---

## Why Paragon?

Paragon doesn't just score higher on tests—it sets the standard for what autonomous code review can achieve.

<table>
<tr>
<td align="center" width="25%">
<h3>🎯 81.2%</h3>
<strong>Issue Detection</strong><br/>
<sub>Highest accuracy on ReviewBenchLite</sub>
</td>
<td align="center" width="25%">
<h3>⚡ 3x</h3>
<strong>Faster</strong><br/>
<sub>Complete analysis in minutes</sub>
</td>
<td align="center" width="25%">
<h3>🔒 SOC 2</h3>
<strong>Compliant</strong><br/>
<sub>Enterprise-grade security</sub>
</td>
<td align="center" width="25%">
<h3>✨ 6.2%</h3>
<strong>False Positives</strong><br/>
<sub>When Paragon flags it, it's real</sub>
</td>
</tr>
</table>

---

## Benchmark Results

**ReviewBenchLite** - Accuracy comparison across leading code review agents:

| Agent | Accuracy |
|-------|----------|
| **Paragon Deep** | **81.2%** |
| Paragon Fast | 72.6% |
| Greptile V3 | 65.8% |
| Claude Code | 56.4% |
| Cursor | 51.3% |
| Codex | 44.4% |
| CodeRabbit | 22.2% |

---

## What Paragon Can Do

| Capability | Description |
|------------|-------------|
| ✅ **Security Scanning** | Comprehensive vulnerability detection before production |
| 🏗️ **Infrastructure Analysis** | Detect misconfigurations, security gaps, and bottlenecks |
| 🚀 **Performance Optimization** | Identify memory leaks, inefficient algorithms, and bottlenecks |
| ⚡ **Instant PR Reviews** | Automated reviews that catch issues in seconds |
| 🐛 **Bug Detection** | Industry-leading bug detection for production environments |
| 🤖 **AI Slop Detection** | Instantly detect and fix low-quality AI-generated code |
| 🔀 **Git Stacking** | Manage stacked branches with ease |
| 🧪 **E2E Testing** | Browser authentication capture for automated testing |
| 🔌 **MCP Integration** | Extend with Model Context Protocol servers |
| 📊 **LSP Analysis** | Deep code understanding via Language Server Protocol |

### Deep Review Mode

Run 8 parallel specialized agents for comprehensive analysis:

```bash
paragon deep-review --specialized
```

Each agent focuses on a specific area:
1. **Security Vulnerabilities** (SAST)
2. **Secrets & Sensitive Data** / Privacy
3. **Maintainability** & Code Smells
4. **Performance** & Efficiency
5. **Reliability** & Defensive Coding
6. **Concurrency** & Memory Safety
7. **Dependency** & Supply-Chain Risk (SCA)
8. **Infrastructure-as-Code** & Config

---

## Installation

```bash
npm install -g @polarityinc/paragon
```

**Requirements:**
- Node.js 18+ (for npm installation)
- Git 2.23+
- GitHub CLI (`gh`) for PR operations

**Alternative Installation:**

```bash
# Using Homebrew (macOS/Linux)
brew install polarity/tap/paragon

# Direct binary download
# Visit https://github.com/polarity/paragon/releases
```

---

## Quick Start

### 1. Authenticate

```bash
paragon auth login
```

Get your API key from [home.polarity.cc](https://home.polarity.cc).

> ⚠️ **Security:** Keep your API key secure. Never commit it to version control.

### 2. Launch Interactive Mode

```bash
paragon
```

### 3. Run a Quick Review

```bash
# Non-interactive code review
paragon run "Review the changes in this branch"

# Feature implementation mode
paragon run --feature "Add input validation to the API"

# Deep review with 8 parallel agents
paragon deep-review --specialized

# JSON output for CI/CD integration
paragon deep-review --specialized --json
```

---

## Features

### 🖥️ Interactive TUI

A beautiful terminal interface with:
- **Session management** — Maintain multiple work contexts per project
- **Command palette** — Access all features with `ctrl+p`
- **Real-time streaming** — Watch AI responses as they're generated
- **File attachments** — Add context with images and files

### LSP-Enhanced Analysis
Paragon uses Language Server Protocol (LSP) for deep code understanding, just like your IDE.

### Extensible via MCP
Add capabilities through Model Context Protocol (`http`, `stdio`, and `sse` transports).

Paragon ships with a Claude-compatible MCP CLI so you can manage servers without leaving the terminal:

```bash
# Add stdio server locally (stored in .paragon/mcp.local.json)
paragon mcp add local-filesystem --transport stdio --env ROOT=/work -- ls --color=never

# Share a server with your team via .mcp.json
paragon mcp add github --transport http --scope project https://api.githubcopilot.com/mcp/

# Inspect and manage servers
paragon mcp list
paragon mcp get github
paragon mcp remove local-filesystem --scope local

# Supabase works exactly like Claude
paragon mcp add --scope project --transport http supabase https://mcp.supabase.com/mcp
paragon mcp auth supabase

# Install every catalog MCP in one shot
paragon mcp catalog install --all --scope project
```

Scopes mirror Claude Code:

- `local` (default) → private to you per project, saved under `.paragon/mcp.local.json`
- `project` → shared `.mcp.json` in the repo root
- `user` → stored in your global Paragon config so every project can use it

The command palette’s **Add MCP Server** dialog now follows the same flow (scope selection, auth metadata, env vars) and will launch OAuth URLs automatically when provided. Supabase servers trigger the full Claude-style OAuth handshake (local callback server, PKCE, browser open) and save the resulting token to your local `.paragon/mcp.tokens.json`. For instant setup, run `paragon mcp catalog install --all --scope project` to pull in every curated MCP from the catalog; the `/mcp` dialog will walk you through approving and authenticating each one.

Inside the TUI, type `/mcp` (or run **Manage MCP Servers** from the command palette) to review servers, authenticate via browser, or disable entries. Project-scoped MCPs from `.mcp.json` prompt you to approve or reject them before Paragon connects, mirroring Claude Code’s safety flow.

### Works Everywhere
First-class support in every terminal on macOS, Linux, Windows (PowerShell and WSL), FreeBSD, OpenBSD, and NetBSD.

---

## CLI Reference

### Core Commands

| Command | Description |
|---------|-------------|
| `paragon` | Launch interactive TUI mode |
| `paragon run "<prompt>"` | Run a single non-interactive prompt |
| `paragon run --feature "<prompt>"` | Feature implementation mode |
| `paragon deep-review` | Run 8 parallel agents for comprehensive code review |
| `paragon deep-review --specialized` | Run 8 specialized agents (security, performance, etc.) |

### Authentication

| Command | Description |
|---------|-------------|
| `paragon auth login` | Authenticate with Polarity |
| `paragon auth logout` | Log out of Polarity |
| `paragon auth status` | Check authentication status |

### Browser Auth for E2E Testing

Capture and manage browser authentication states for testing dashboards with OAuth/SSO:

| Command | Description |
|---------|-------------|
| `paragon auth capture <url>` | Capture browser auth state (cookies, localStorage) |
| `paragon auth list` | List saved authentication states |
| `paragon auth test <domain>` | Verify if auth state is still valid |
| `paragon auth export <domain>` | Export to Playwright/Puppeteer format |
| `paragon auth remove <domain>` | Remove saved auth state |

### Git Stacking

| Command | Description |
|---------|-------------|
| `paragon stack` | Show the current branch stack tree |
| `paragon submit` | Submit stacked PRs |
| `paragon sync` | Sync stacked branches with trunk |

### MCP Server Management

| Command | Description |
|---------|-------------|
| `paragon mcp add <name>` | Add an MCP server |
| `paragon mcp list` | List configured MCP servers |
| `paragon mcp get <name>` | Show MCP server details |
| `paragon mcp remove <name>` | Remove an MCP server |
| `paragon mcp auth <name>` | Authenticate with an MCP server |
| `paragon mcp catalog install --all` | Install all curated MCP servers |

### Utility Commands

| Command | Description |
|---------|-------------|
| `paragon context` | Show the current context |
| `paragon logs` | View application logs |
| `paragon dirs` | Show Paragon data directories |

### Global Flags

| Flag | Description |
|------|-------------|
| `-c, --cwd <path>` | Set working directory |
| `-D, --data-dir <path>` | Custom Paragon data directory |
| `-d, --debug` | Enable debug logging |
| `-y, --yolo` | Auto-accept all permissions (dangerous) |
| `--no-update` | Disable auto-update check |
| `-h, --help` | Show help |
| `-v, --version` | Show version |

---

## Keyboard Shortcuts

### Navigation

| Shortcut | Action |
|----------|--------|
| `ctrl+p` | Open command palette |
| `ctrl+c` | Cancel current operation / Exit |
| `ctrl+l` | Clear screen |
| `ctrl+n` | New session |
| `ctrl+s` | Save session |

### Input

| Shortcut | Action |
|----------|--------|
| `Enter` | Send message |
| `Shift+Enter` | New line in input |
| `↑` / `↓` | Navigate history |
| `Tab` | Autocomplete |

### Command Palette Actions

Access these via `ctrl+p`:

- **New Session** — Start a fresh conversation
- **Switch Session** — Jump between work contexts  
- **Manage MCP Servers** — Add, remove, authenticate servers
- **Add MCP Server** — Configure a new MCP connection
- **Toggle Feature Mode** — Switch between review and implementation modes
- **View Logs** — Open the log viewer
- **Automation Scenarios** — Run saved automation flows

---

## Configuration

Paragon runs great with no configuration. For advanced usage, create a configuration file:

**Locations** (in priority order):
1. `.paragon.json` (project-local, hidden)
2. `paragon.json` (project-local)
3. `~/.config/paragon/paragon.json` (global)

### Example Configuration

```json
{
  "$schema": "https://polarity.cc/paragon.json",
  "lsp": {
    "go": {
      "command": "gopls"
    },
    "typescript": {
      "command": "typescript-language-server",
      "args": ["--stdio"]
    }
  },
  "mcp": {
    "filesystem": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/mcp-server.js"],
      "timeout": 120,
      "disabled": false
    },
    "api-service": {
      "type": "http",
      "url": "https://example.com/mcp/",
      "timeout": 120,
      "disabled": false,
      "headers": {
        "Authorization": "Bearer your-token"
      }
    },
    "streaming-service": {
      "type": "sse",
      "url": "https://example.com/mcp/sse",
      "timeout": 120,
      "disabled": false
    }
  }
}
```

---

## Impact

### Real Results From Teams Worldwide

- **93%** Faster PR Merge Time
- **81.2%** Production Issues Found Before Deployment
- **100M** Lines of Code Processed Per Month

---

## Enterprise

Paragon offers enterprise-grade features for teams:

- **SOC 2 Compliance** - Industry-leading security standards
- **Self-Hosted Options** - Deploy on your infrastructure
- **Priority Support** - Dedicated support team
- **Custom Integrations** - Tailored to your workflow
- **SLA Guarantees** - 99.9% uptime commitment

[Book a demo →](https://polarity.cc/demo)

---

## Environment Variables

| Variable | Description |
|----------|-------------|
| `PARAGON_DISABLE_METRICS` | Set to `true` to disable telemetry |
| `DO_NOT_TRACK` | Set to `true` to disable telemetry (standard) |
| `PARAGON_PROFILE` | Enable pprof profiling server on `localhost:6060` |

---

## License

Paragon is proprietary software by [Polarity](https://polarity.cc).

For inquiries, contact [sales@polarity.cc](mailto:sales@polarity.cc).

---

## Contributing

We welcome contributions! Please see our [CLA](CLA.md) before submitting pull requests.

---

<p align="center">
  <strong>Experience the world's best code review agent</strong><br/>
  Join teams worldwide who trust Paragon—the fastest, most accurate, and most secure code review agent.
</p>

<p align="center">
  <a href="https://home.polarity.cc/"><strong>Get Started →</strong></a> |
  <a href="https://polarity.cc/contact"><strong>Book a Demo →</strong></a>
</p>