Reygent

An AI-powered CLI that orchestrates multiple Claude agents to automate the software development lifecycle — from spec to shipped PR.

Reygent reads a spec (markdown file, Jira issue, or Linear issue), then runs the reygent workflow — a sequence of specialized agents that plan the work, implement code, write tests, run quality gates, perform a security review, create a pull request, and review the PR.

Prerequisites

• Node.js 22+
• AI Provider — one of:
  • Claude CLI (claude) installed and authenticated (default, recommended)
    • Direct via Anthropic API, or via Google Vertex AI Model Garden
  • Gemini CLI (gemini) for Google Gemini models
    • Direct via Google AI API, or via Google Vertex AI
  • Codex CLI (codex) for GPT models
  • OpenRouter API key for 200+ model access (API-only, limited tool support)
• GitHub CLI (gh) installed and authenticated (for PR operations)
• Git configured in your project

See the Providers Guide for provider setup details, including Google Vertex AI configuration for Claude and Gemini.

Install

npm install -g reygent

Or run directly with npx:

npx reygent

Run globally from source (without publishing to NPM)

Clone the repo, build, and use npm link to symlink the package globally:

git clone https://github.com/your-org/reygent.git
cd reygent
npm install
npm run build
npm link

Now reygent is available as a command anywhere on your machine. To remove it later:

npm unlink -g reygent

Quick Start

See the full Quickstart Guide to go from zero to your first AI-driven PR.

reygent init                                               # initialize local config
reygent generate-spec "Add login endpoint" --output spec.md # generate a spec
reygent run --spec spec.md                                 # run the full workflow

Commands

| Command | Description | |---|---| | reygent init | Initialize .reygent/ config in current project | | reygent generate-spec | Generate a markdown spec from a short description | | reygent spec | Load and display a parsed spec | | reygent agent | Start an interactive agent session | | reygent run | Run the full 7-stage workflow | | reygent continue | Resume a previously failed or interrupted run | | reygent review-work | Review current branch and post to PR/MR | | reygent review-comments | Fetch PR comments and address with dev agent | | reygent config | Configure provider, model, and per-agent overrides | | reygent skills | Manage skills from the registry | | reygent telemetry | Manage telemetry data and configuration | | reygent analyze | Analyze telemetry data for insights | | reygent dashboard | Generate HTML dashboard or run CLI telemetry queries | | reygent last | Show latest run details | | reygent knowledge | Manage knowledge base |

See the Commands Reference for full options and examples.

Global Flags

These flags apply to all commands:

| Flag | Description | |---|---| | --model <id> | Override the AI model (e.g., claude-opus-4-6) | | --provider <name> | AI provider: claude, gemini, codex, openrouter | | --debug | Show full stack traces on errors | | --no-telemetry | Disable telemetry for this run | | --telemetry-level <level> | Override telemetry level (minimal, standard, verbose) | | --telemetry-verbose | Shorthand for --telemetry-level verbose |

Reygent Workflow

The reygent workflow is an implementation of the agent harness pattern — a structured framework for orchestrating AI agents through complex, multi-stage tasks. See Harness Pattern for details.

spec
 |
 v
[1] Plan ──────────────── Planner agent validates spec, outputs goals/tasks/constraints
 |
 v
[2] Implement ─────────── Dev + QE agents run in parallel (code and tests)
 |
 v
[3] Gate: Unit Tests ──── Dev agent runs unit tests (workflow halts if tests fail)
 |
 v
[4] Gate: Func Tests ──── QE agent runs functional tests (workflow halts if tests fail)
 |
 v
[5] Security Review ───── Security agent scans for vulnerabilities
 |
 v
[6] PR Create ─────────── Creates branch, commits, pushes, opens PR via gh
 |
 v
[7] PR Review ─────────── Reviews the PR diff and outputs comments

Agents

| Agent | Role | What it does | |---|---|---| | planner | Planner | Validates the spec and breaks it into goals, tasks, constraints, and definition of done | | dev | Developer | Implements code based on the plan | | qe | Quality Engineer | Writes functional tests (does not modify source code) | | security-reviewer | Security Reviewer | Scans for OWASP Top 10 vulnerabilities | | pr-reviewer | Reviewer | Creates PRs and performs code review | | adhoc | General | Runs one-off tasks with full tool access |

See the Agents Guide for details on customization, output formats, and execution modes.

Providers

Reygent supports multiple AI providers. The default is Claude (via the claude CLI).

| Provider | Type | Default Model | Requires | |---|---|---|---| | claude | CLI | Claude Sonnet 4.5 | claude CLI installed | | gemini | CLI | Gemini 2.5 Pro | gemini CLI installed | | codex | CLI | o4-mini | codex CLI installed | | openrouter | API | Claude Sonnet 4.5 | OPENROUTER_API_KEY env var |

reygent run --spec spec.md --provider gemini
reygent run --spec spec.md --provider openrouter --model anthropic/claude-sonnet-4-5

See the Providers Guide for setup and configuration.

Spec Sources

Reygent accepts specs from three sources (auto-detected):

| Source | Example | |---|---| | Markdown file | reygent run --spec ./specs/feature.md | | Jira issue | reygent run --spec PROJ-123 | | Linear issue | reygent run --spec ENG-456 or reygent run --spec https://linear.app/... |

Requires corresponding API keys in .env for tracker sources. See Commands Reference.

Configuration

Global (default): Reygent uses built-in agents defined in the package.

Local (per-project): Run reygent init to create .reygent/config.json:

{
  "agents": [
    {
      "name": "dev",
      "description": "Write, edit, and refactor implementation code",
      "systemPrompt": "You are the Dev agent...",
      "tools": ["read", "write", "bash", "search"],
      "role": "developer"
    }
  ],
  "skills": {
    "path": "skills"  // Agents can access custom skills from this directory
  },
  "model": "claude-sonnet-4-5-20250929"
}

Reygent searches upward from the current directory to find .reygent/, so you can run commands from any subdirectory.

Telemetry & Learning

Reygent tracks local telemetry and learns from past runs to improve future performance.

Telemetry Analysis:

• reygent last - Show latest run details
• reygent analyze failures - Common error patterns
• reygent analyze success - What works well
• reygent analyze costs - Cost breakdown and savings
• reygent analyze agents - Agent-specific performance breakdown
• reygent knowledge - Manage knowledge base (list, show, search, edit, add entries)

Living Documentation: Reygent automatically learns from your project through .reygent/knowledge/:

• Auto-generated failure solutions from past errors
• Success patterns extracted from high-performing runs
• Agent-specific tips that prevent repeated mistakes

Privacy: All data stored locally. Error messages automatically sanitized to remove tokens, passwords, and paths. By default writes to both project-local and global DBs.

Security (enforced across all providers):

• Auto-sanitizes error messages (removes tokens, API keys, paths)
• Validates knowledge files to prevent prompt injection
• DB size limits prevent disk exhaustion
• Optional global telemetry opt-out for cross-project isolation
• See SECURITY.md for full details

Disable:

export REYGENT_TELEMETRY=false         # Disable all telemetry
export REYGENT_GLOBAL_TELEMETRY=false  # Disable global DB only (security)
export REYGENT_KNOWLEDGE=false         # Disable knowledge learning

See Telemetry Guide, Chesstrace Internals, and Living Documentation Guide for full details.

Documentation

| Document | Description | |---|---| | Quickstart | Zero to first PR guide | | Commands Reference | Every command, flag, and option | | Agents Guide | Agent specs, customization, output formats | | Providers Guide | Multi-provider setup and configuration | | Skills Guide | Extend reygent with custom skills | | Telemetry | Telemetry analysis, privacy, and troubleshooting | | Chesstrace | Telemetry engine internals, backends, event system | | Living Documentation | Auto-learning knowledge system from past runs | | Security | Security measures, threat model, and developer guidelines | | Workflows | Visual diagrams of pipeline and retry logic | | Architecture | Technical deep-dive into internals | | Harness Pattern | How reygent implements Anthropic's harness pattern | | Verify Pricing | Claude Code skill for verifying provider token pricing |

Development

git clone https://github.com/your-org/reygent.git
cd reygent
npm install
npm run build         # Compile to dist/
npm run dev           # Watch mode
npm test              # Run tests
npm run docs:dev      # Start VitePress dev server
npm run docs:build    # Build documentation site
npm run docs:preview  # Preview built docs locally

License

Apache-2.0 - see LICENSE for details.

Disclaimer

This software is provided "as is", without warranty of any kind.

AI-generated output: Reygent orchestrates AI agents that produce code, tests, and reviews. All AI-generated output should be reviewed by a human before merging or deploying. The authors are not responsible for any damages resulting from the use of this tool or its output.