reflect

Autonomous code self-improvement system for Claude Code.

Reflect lets AI review its own work. It examines code, asks itself hard questions about what could be wrong, investigates the answers, and fixes what it finds — without human intervention. The name comes from the core mechanism: the system reflects on code by generating questions, then reasoning through each one in isolated context.

How It Works

Reflect operates as a closed loop: question -> investigate -> fix.

1. AI reads a file and generates dozens of targeted questions ("Is this race-condition-safe?", "Does this handle the null case?", "Is the touch target accessible?")
2. A fast model (Sonnet) screens questions — discarding obvious ones, keeping those worth investigating
3. A powerful model (Opus) investigates each surviving question in fresh, isolated context — reading related files, tracing dependencies, reasoning deeply
4. Findings are ranked by severity and written to structured reports
5. The fix pipeline reads findings and applies code changes autonomously

No config files to write. No rules to define. The system figures out what to ask by reading the code.

Installation

/plugin marketplace add aiclaudelib/marketplace
/plugin install reflect@aiclaudelib

Or run with --plugin-dir:

claude --plugin-dir /path/to/reflect

Commands

Command	Description
/reflect	Examine code, generate questions, investigate, report findings
/reflect-fix	Autonomously fix findings from a completed session
/reflect-status	List sessions, show progress, clean old sessions

Usage

/reflect --file src/components/UserForm.tsx
/reflect --glob "src/services/**/*.ts"
/reflect --all

Fix everything it found:

/reflect-fix --session <id> --auto

Or review interactively:

/reflect-fix --session <id>

The Pipeline

  Read code
    |
  Generate questions per file (Sonnet, 10 parallel)
    |
  Screen: keep only questions worth investigating
    |
  Deep investigation per question (Opus, 5 parallel, isolated context)
    |
  Rank findings by severity
    |
  Generate reports
    |
  Fix autonomously (/reflect-fix --auto)

Each investigation runs in its own fresh context — no cross-contamination between questions. This is what makes findings precise: Opus sees only the relevant code and the single question it needs to answer.

Multi-Model Architecture

Role	Model	Why
Screening & question generation	Sonnet	Fast, cost-effective — good at reading code and asking questions
Deep investigation	Opus	Thorough, high quality — good at reasoning through complex issues
Orchestration	Main session	Coordinates agents, tracks progress, manages state

Ecosystem Support

Reflect auto-detects the project from config files — no setup needed:

Language	Frameworks	Config Files
TypeScript/JavaScript	React, Next.js, Vue, Angular, Svelte, Express, NestJS	package.json, tsconfig.json
PHP	Laravel, Symfony	composer.json
Python	Django, Flask, FastAPI	pyproject.toml, setup.py, requirements.txt
Go	Gin, Echo, Fiber	go.mod
Rust	Actix, Axum, Rocket	Cargo.toml
Java/Kotlin	Spring Boot	pom.xml, build.gradle
Ruby	Rails	Gemfile
C#	ASP.NET	*.csproj
Elixir	Phoenix	mix.exs
Dart	Flutter	pubspec.yaml

Analysis dimensions adapt to the project type — backend gets security and data integrity checks, frontend gets UX and accessibility, fullstack gets both.

Output

.reflect/sessions/{sessionId}/
  manifest.json           # Session state and progress
  project-profile.json    # Auto-detected project config
  questions/              # Generated and screened questions
  analyses/               # Investigation results per question
  reports/
    summary.md            # Ranked findings across all files
    {file-hash}.md        # Per-file detailed reports

Configuration

Optional. Create .reflect.json in project root to override auto-detection:

{
  "language": "typescript",
  "framework": "next",
  "projectType": "fullstack",
  "aliases": { "@/": "src/" },
  "dimensions": ["SECURITY", "PERFORMANCE", "ERROR_HANDLING"]
}

Structure

reflect/
  .claude-plugin/
    plugin.json
  skills/
    reflect/              # Orchestrator — runs the full pipeline
      SKILL.md
      steps/              # 9 progressive disclosure steps
    reflect-fix/          # Autonomous fix pipeline
      SKILL.md
    reflect-status/       # Session management
      SKILL.md
  agents/
    screener.md           # Question generation & screening (sonnet)
    file-analyzer.md      # Deep investigation per question (opus)
  hooks/
    hooks.json
    scripts/
      write-status.sh
  scripts/
    reflect-ci.sh

License

MIT