prism

Decompose pull requests into stable, reviewable system context

A prism decomposes light into its spectrum. prism decomposes pull requests — extracting structure, intent, and risk from raw diffs so that AI reviews become designable and reproducible.

PR → structured context → stable AI review.

The problem

AI code reviews are inconsistent — not because models are bad, but because the input is unstructured:

Raw diffs lack context about what changed and why
Reviewers must decide review depth and focus points every time
Different prompts produce wildly different review quality
No standardized way to tell AI what to look for

prism solves this by compiling PRs into structured, reviewable system context.

What prism does

prism is a Review Context Compiler — it decomposes Pull Requests into AI-review-ready system context by:

Extracting PR metadata and diffs
Classifying change types (feature, bugfix, refactor, ...)
Estimating risk level
Suggesting review axes (security, backward compatibility, error handling, ...)
Detecting related files (test/source pairs, peer files)
Generating structured output (JSON / Markdown / text)
Producing mode-specific review prompts (light / detailed / cross)

The simplest way to use it

prism analyze <PR_URL> --format json | claude -p "Review this pull request"

Quick Start

Requires Go 1.26 or later.

go install github.com/hidetzu/prism/cmd/prism@latest
export GITHUB_TOKEN=your-token
prism analyze https://github.com/owner/repo/pull/123 --format json

Use Cases

Analyze a PR

prism analyze <PR_URL> --format json       # Structured JSON for AI tools
prism analyze <PR_URL> --format markdown   # Human-readable summary
prism analyze <PR_URL> --format text       # Plain text summary

Generate review prompts

prism prompt <PR_URL> --mode light         # Quick screening
prism prompt <PR_URL> --mode detailed      # Deep review with patches
prism prompt <PR_URL> --mode cross         # Cross-file consistency review
prism prompt <PR_URL> --mode light --lang ja  # Japanese prompt

Pipe to Claude

prism analyze <PR_URL> --format json | claude -p "Review this pull request"
prism prompt <PR_URL> --mode detailed | claude -p

Debug PR data

prism fetch <PR_URL> --format json         # Raw PR data (no analysis)
prism fetch <PR_URL> --format text         # Raw PR data as text

What you get

JSON output example

{
  "pull_request": {
    "provider": "github",
    "repository": "owner/repo",
    "id": "123",
    "title": "Add retry handling for payment API",
    "author": "example",
    "source_branch": "feature/payment-retry",
    "target_branch": "main",
    "url": "https://github.com/owner/repo/pull/123"
  },
  "analysis": {
    "change_type": "feature",
    "risk_level": "medium",
    "affected_areas": ["payment"],
    "review_axes": [
      "error handling",
      "test coverage",
      "edge cases"
    ],
    "related_files": [
      "internal/payment/client_test.go",
      "internal/payment/handler.go",
      "internal/payment/service.go"
    ],
    "warnings": [
      "No test files included in this change"
    ],
    "summary": "feature: Add retry handling for payment API (1 file changed, +45/-3)"
  },
  "changed_files": [
    {
      "path": "internal/payment/client.go",
      "status": "modified",
      "additions": 45,
      "deletions": 3,
      "language": "Go"
    }
  ]
}

Markdown output example

# Add retry handling for payment API

## Pull Request

| Field | Value |
|-------|-------|
| Repository | owner/repo |
| PR | #123 |
| Author | example |
| Branch | feature/payment-retry -> main |
| Provider | github |
| URL | https://github.com/owner/repo/pull/123 |

## Analysis

- **Change Type:** feature
- **Risk Level:** medium
- **Summary:** feature: Add retry handling for payment API (1 file changed, +45/-3)

### Review Axes

- error handling
- test coverage
- edge cases

### Warnings

- No test files included in this change

## Changed Files

| File | Status | +/- | Language |
|------|--------|-----|----------|
| internal/payment/client.go | modified | +45/-3 | Go |

Commands reference

# Analyze
prism analyze <PR_URL>                     # JSON (default)
prism analyze <PR_URL> --format json       # Structured JSON
prism analyze <PR_URL> --format markdown   # Markdown summary
prism analyze <PR_URL> --format text       # Plain text summary

# Prompt generation
prism prompt <PR_URL> --mode light         # Quick screening prompt
prism prompt <PR_URL> --mode detailed      # Deep review prompt
prism prompt <PR_URL> --mode cross         # Cross-file review prompt
prism prompt <PR_URL> --lang ja            # Japanese prompt
prism prompt <PR_URL> --template my.tmpl   # Custom template

# Debug
prism fetch <PR_URL> --format json         # Raw PR data
prism fetch <PR_URL> --format text         # Raw PR data as text

# Provider selection (available on all commands)
prism analyze <PR_URL> --provider github   # Explicit provider

Prompt Modes

Mode	Purpose	Depth
`light`	Quick screening for obvious bugs, security issues	Minimal context
`detailed`	Implementation review, coverage gaps, edge cases	Full context with patches
`cross`	Cross-file consistency, interface contracts	Module structure focus

Providers

Supported providers

Provider	Type	Status
GitHub	Built-in	Supported
AWS CodeCommit	Plugin	Supported (prism-provider-codecommit)

Provider selection

By default, prism auto-detects the provider from the PR URL. Use --provider to specify explicitly:

prism analyze https://github.com/owner/repo/pull/123              # auto-detected as GitHub
prism analyze <PR_URL> --provider github                          # explicit GitHub
prism analyze <PR_URL> --provider codecommit                      # explicit CodeCommit (requires plugin)

CodeCommit plugin

CodeCommit support is provided by the prism-provider-codecommit plugin, which wraps ccpr to fetch CodeCommit PR data.

# Install the plugin
go install github.com/hidetzu/prism-provider-codecommit/cmd/prism-provider-codecommit@latest

# Use it
prism analyze https://ap-northeast-1.console.aws.amazon.com/codesuite/codecommit/repositories/my-repo/pull-requests/42

Plugin architecture

External providers are distributed as separate binaries named prism-provider-<name> and discovered on PATH. Plugins receive a PR URL and return structured JSON to stdout.

prism (core)
    ↓ subprocess
provider plugin (prism-provider-<name>)
    ↓ API call
provider (GitHub / CodeCommit / ...)

This keeps the prism core lightweight and provider-agnostic. Writing a new plugin requires only conforming to the plugin protocol.

See ADR-0001 for design rationale.

Configuration

GitHub token

Set GITHUB_TOKEN environment variable:

export GITHUB_TOKEN=ghp_xxxxxxxxxxxx

Config file

prism loads configuration from ~/.config/prism/config.yaml (override with --config or PRISM_CONFIG env var).

github_token: ghp_xxxxxxxxxxxx
default_format: json        # json, markdown, text
default_mode: light         # light, detailed, cross
default_lang: en            # en, ja

Environment variables override config file values. GITHUB_TOKEN always takes precedence.

Custom templates

Use --template to provide a custom Go template for prompt output:

prism prompt <PR_URL> --template review.tmpl

Available template variables:

Variable	Type	Description
`.PR`	PullRequest	PR metadata and changed files
`.Analysis`	AnalysisResult	Classification, risk, review axes
`.Mode`	string	Prompt mode (light/detailed/cross)
`.Lang`	string	Language code (en/ja)
`.SystemPrompt`	string	Built-in system prompt for the mode

Example template:

Review: {{.PR.Title}} ({{.Analysis.ChangeType}}, risk: {{.Analysis.RiskLevel}})

{{range .Analysis.ReviewAxes}}- Focus: {{.}}
{{end}}
{{range .PR.ChangedFiles}}- {{.Path}} ({{.Status}}, +{{.Additions}}/-{{.Deletions}})
{{end}}

Language support

Use --lang to switch prompt language:

prism prompt <PR_URL> --lang ja    # Japanese system prompts

Supported: en (English, default), ja (Japanese)

Exit Codes

Code	Meaning
0	Success
1	General error
2	Invalid arguments (bad URL, invalid flag values)
3	Provider error (GitHub API failure, auth error)
4	Analysis error

Library Usage

prism exposes a stable public API at pkg/prism for embedding in other Go programs.

import (
    "context"
    "fmt"
    "os"

    "github.com/hidetzu/prism/pkg/prism"
)

ctx := context.Background()

// Analyze: structured analysis
result, err := prism.Analyze(ctx, prism.AnalyzeOptions{
    PRURL:       "https://github.com/owner/repo/pull/123",
    GitHubToken: os.Getenv("GITHUB_TOKEN"),
})
if err != nil {
    // errors.Is(err, prism.ErrInvalidInput)
    // errors.Is(err, prism.ErrUnsupportedProvider)
    // errors.Is(err, prism.ErrAuthRequired)
    // errors.Is(err, prism.ErrUpstreamFailure)
    return err
}
fmt.Println(result.PR.Title, result.Analysis.RiskLevel)

// Prompt: review prompt text for AI consumption
reviewPrompt, err := prism.Prompt(ctx, prism.AnalyzeOptions{
    PRURL:       "https://github.com/owner/repo/pull/123",
    GitHubToken: os.Getenv("GITHUB_TOKEN"),
    Mode:        "detailed", // light | detailed | cross
    Language:    "en",       // en | ja
})
if err != nil {
    return err
}
fmt.Println(reviewPrompt)

Stable surface

Only the symbols exported from pkg/prism are part of the public API contract. Everything under internal/ is subject to change.

prism.Analyze(ctx, opts) (Result, error) — structured analysis
prism.Prompt(ctx, opts) (string, error) — review prompt text
prism.AnalyzeOptions / prism.Result / prism.PRInfo / prism.AnalysisResult / prism.ChangedFile
Sentinel errors: ErrInvalidInput, ErrUnsupportedProvider, ErrAuthRequired, ErrUpstreamFailure

See ADR-0002 for the design rationale and compatibility policy.

Philosophy

Stop prompting. Start structuring. — Consistent AI review quality starts with structured input, not better prompts.
PRs are not readable by LLMs as-is. — Raw diffs lack intent, risk, and context.
AI review quality starts with review design. — prism is the design layer between PRs and AI.

Development

make build    # Build binary to bin/prism
make test     # Run all tests with -v -race
make lint     # golangci-lint
make vet      # go vet
make clean    # Remove bin/

Roadmap

v0.1.0 — GitHub provider, analyze/prompt/fetch commands, JSON/Markdown/text output, light/detailed/cross modes, config/lang/template support, exit codes ✅
v0.2.0 — Provider plugin architecture, --provider flag, AWS CodeCommit support via plugin ✅
v0.3.0 — Public library API (pkg/prism), CLI uses pkg/prism internally, foundation for prism-api (HTTP service)
v0.4.0 — Policy files, custom review axes, project-specific rules
v0.5.0+ — SARIF output, metrics, IDE/CI integration

Releases

v0.2.0 — Provider plugin architecture + CodeCommit support
v0.1.0 — Initial release

See CHANGELOG.md for the full history and breaking changes.

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 8 Commits
.github		.github
cmd/prism		cmd/prism
docs		docs
internal		internal
pkg/prism		pkg/prism
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
go.mod		go.mod
go.sum		go.sum

Folders and files

Latest commit

History

Repository files navigation

prism

Decompose pull requests into stable, reviewable system context

The problem

What prism does

The simplest way to use it

Quick Start

Use Cases

Analyze a PR

Generate review prompts

Pipe to Claude

Debug PR data

What you get

Prompt Modes

Providers

Supported providers

Provider selection

CodeCommit plugin

Plugin architecture

Configuration

GitHub token

Config file

Custom templates

Language support

Exit Codes

Library Usage

Stable surface

Philosophy

Development

Roadmap

Releases

License

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 3

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages