spectra

Quickstart

Three lines, under a minute:

pip install spectra-ai
export ANTHROPIC_API_KEY=sk-ant-...
spectra analyze https://github.com/your/repo

Open spectra-report.html when it finishes. Requires Python 3.12+ and an Anthropic API key.

At-rest cache encryption (optional). The local SQLite cache always carries per-row HMAC integrity. To also encrypt cache contents at rest, install the opt-in extra: pip install "spectra-ai[encryption]". This pulls pysqlcipher3, which source-builds against libsqlcipher — macOS users need brew install sqlcipher first; Debian/Ubuntu apt-get install libsqlcipher-dev. Without the extra, Spectra runs with plain SQLite + HMAC and emits a single WARN at startup.

Drop into any GitHub Action

- uses: leocder07/spectra@v1
  with:
    anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }}

The Problem

AI-generated code ships faster than ever, but quality assurance hasn't kept up. One LLM call can't catch architecture drift, security flaws, and documentation gaps at the same time.

Spectra deploys 8 AI agents — 6 parallel specialists, a planning agent, and a critique agent — to give you the full spectrum in minutes.

What You Get

A weighted ScoreCard plus a self-contained HTML report. Here's what the terminal looks like at the end of a run:

▸ INGEST: cloned expressjs/express (1,247 files, 184K LOC)
▸ PLAN:   MetaPrompter built 6-agent plan (4.2K tokens)
▸ ANALYZE: 6 specialists running in parallel...
   ✓ Architecture     12.4s   8 findings
   ✓ Security          9.8s   14 findings (3 critical)
   ✓ Quality          11.2s   11 findings
   ✓ Documentation     7.6s   6 findings
   ✓ Maintainability   8.1s   4 findings
   ✓ Performance      10.5s   3 findings
▸ MERGE:    deduplicated 46 → 38 findings
▸ CRITIQUE: validated findings, dropped 4 false positives (Opus 4.7 + thinking)
▸ REPORT:   spectra-report.html

┌─────────────────────────────────────────────┐
│  SPECTRA SCORECARD                          │
│  repo: expressjs/express                    │
│  Overall: B- (80/100)                       │
├─────────────────────────────────────────────┤
│  Architecture   █████████░  89  A-          │
│  Security       ██████░░░░  67  D+          │
│  Quality        █████████░  87  B+          │
│  Documentation  ██████░░░░  68  C-          │
│  Maintainability██████████  92  A           │
│  Performance    ████████░░  76  C+          │
├─────────────────────────────────────────────┤
│  34 findings · 3 critical · 87s · $2.41     │
└─────────────────────────────────────────────┘

✓ Top issues: SQL injection in middleware/parser.js:142
              prototype pollution in utils/merge.js:38
              missing auth on /admin/* routes

See Spectra analyze itself: the v0.7.0 self-scan grades A (92/100), 55 findings (0 critical), $6.62 real Anthropic spend — alongside FastAPI, HTTPX, Aider, and Simon Willison's LLM on the public leaderboard.

Three Things That Set Spectra Apart

Other things you get

• Multi-model strategy — Opus 4.7 (medium effort) for planning, Opus 4.7 (xhigh effort) for deep analysis, Opus 4.7 with adaptive thinking for critique
• Self-contained HTML reports — Radar charts, interactive findings, keyboard navigation, file hotspot heatmaps — one file, works offline
• Due diligence frameworks — OWASP Top 10, SOC 2 Trust Criteria, PCI DSS 4.0, NIST CSF 2.0, and Investment Readiness scoring
• Cost transparency — Every report shows exact token usage and dollar cost
• Clean Architecture — 4-layer dependency rule, frozen Pydantic models, zero Any types — the tool that audits architecture follows strict architecture itself

Memory (v0.9.1+) — every scan deposits, the next scan reads

Spectra carries forward what the last scan learned. Each run deposits a scan_completed event to a per-repo memory log; the next run reads that log and feeds the planner a short prior-context paragraph. The result: the planner sees "this finding was waived 6 weeks ago for reason X" before it re-flags it.

What the memory log carries

Three event kinds, all JSON-safe, all idempotent on re-deposit:

Three seams, one Protocol

Stage 1 (INGEST)     →  scan_adrs walks the workspace, deposits adr_ingested
                        events. Symlinked dirs + files REJECTED; per-file
                        1 MB cap; per-dir 500-file cap.

Stage 2 (PLAN)       →  Query last 10 scan_completed + 20 waiver_added +
                        50 adr_ingested. Render a ≤2000-char paragraph.
                        Inject under <prior_context> guardrail. _scrub()
                        strips any hostile </prior_context> tag-escape
                        attempt in attacker-controlled fields.

Stage 6 (REPORT)     →  Append one scan_completed event after the report
                        is built. Idempotent on scan_id.

The port boundary is the architectural payoff: MemoryPort is a Protocol in Layer 2. v0.9.1 ships LocalFileMemoryAdapter (SQLite + FTS5, local-first, free, on-disk under 0o600); a future ManagedAgentMemoryAdapter (Anthropic Memory Store, paid org tier) drops in as a sibling without touching the use-case layer. See ADR-025.

Storage location

Default: $XDG_DATA_HOME/spectra/memory/<sha256-of-canonical-repo-url>.db (or ~/.local/share/spectra/memory/... if XDG is unset).

URL canonicalization collapses scheme variants so HTTPS, SSH, git+SSH, and scp-style clones of the same repo share one DB:

[email protected]:foo/bar.git         ┐
ssh://[email protected]/foo/bar.git   ├──→  sha256("https://github.com/foo/bar").db
HTTPS://GitHub.com/foo/bar/        │
https://github.com/foo/bar.git     ┘

CLI flags

spectra analyze <repo> \
  --memory-dir /path/to/dir   # override (env: SPECTRA_MEMORY_DIR)
  --no-memory                 # disable (env: SPECTRA_NO_MEMORY) — CI-safe

Failure contract (port-level promise, not adapter detail)

Per ADR-025, the asymmetry is part of the MemoryPort Protocol — a future remote KV adapter cannot silently weaken it:

• Writes degrade to a one-shot WARN; the scan completes and the report ships even if the memory log is unwritable.
• Reads raise AgentError(SPEC-010); the call site decides whether to surface (e.g. spectra ask) or degrade (Stage 2 falls back to a no-prior-context plan).

What's deferred to v0.10.0

• spectra ask <question> — natural-language Q&A over the memory log
• spectra brief — 10-things-to-know onboarding mode
• ManagedAgentMemoryAdapter (Anthropic Memory Store)
• Drift event deposits + waiver writer

Verification on real OSS — sindresorhus/p-limit (2026-05-22)

Six end-to-end tests against the published wheel (pip install spectra-ai==0.9.1) on a real OSS repo:

Total demo cost: $5.25 across 4 wheel-based scans. All 6 acceptance criteria from the v0.9.1 handoff verified.

How Spectra Compares

Honest tradeoffs. Spectra is built for full-repo audits — not for inline PR comments or IDE feedback. Use it alongside, not instead of, the tools your team already runs.

If you need inline PR comments while reviewing diffs, run CodeRabbit, Greptile, or Copilot's review. If you need a signed, architecture-level audit with security and compliance scoring before a release or a due-diligence review, run Spectra. They complement each other — Spectra grades the repo; they review the diff.

How It Works

graph LR
    A[INGEST<br/>Clone repo<br/>+ ADR ingest] --> B[PLAN<br/>MetaPrompter<br/>+ Prior context]
    B --> C[ANALYZE<br/>6 Specialists<br/>Opus 4.7 xhigh]
    C --> D[MERGE<br/>Deduplicate<br/>& Score]
    D --> E[CRITIQUE<br/>CritiqueAgent<br/>Opus 4.7 adaptive]
    E --> F[REPORT<br/>HTML + Charts<br/>+ Deposit]

    MEM[(MemoryPort<br/>SQLite + FTS5)]
    A -.->|adr_ingested| MEM
    MEM -.->|query| B
    F -.->|scan_completed| MEM

    style A fill:#7C3AED,stroke:#7C3AED,color:#fff
    style B fill:#7C3AED,stroke:#7C3AED,color:#fff
    style C fill:#F59E0B,stroke:#F59E0B,color:#fff
    style D fill:#7C3AED,stroke:#7C3AED,color:#fff
    style E fill:#EF4444,stroke:#EF4444,color:#fff
    style F fill:#22C55E,stroke:#22C55E,color:#fff
    style MEM fill:#1e293b,stroke:#7C3AED,color:#fff,stroke-dasharray: 5 5

Dotted lines show the v0.9.1 memory wiring: Stage 1 deposits ADRs, Stage 2 reads prior context, Stage 6 deposits the new scan_completed event. See the Memory section above for the full contract.

The ANALYZE stage fans out to 6 parallel specialists:

graph TD
    MP[MetaPrompter Plan] --> ARCH[Architecture Agent]
    MP --> SEC[Security Agent]
    MP --> QUAL[Quality Agent]
    MP --> DOC[Documentation Agent]
    MP --> DEP[Dependency Agent]
    MP --> PERF[Performance Agent]

    ARCH --> MERGE[Merge & Score]
    SEC --> MERGE
    QUAL --> MERGE
    DOC --> MERGE
    DEP --> MERGE
    PERF --> MERGE

    style MP fill:#7C3AED,stroke:#7C3AED,color:#fff
    style MERGE fill:#F59E0B,stroke:#F59E0B,color:#fff

Agent Roster

ScoreCard

Every analysis produces a weighted ScoreCard:

Grades: A+ (95-100) · A (90-94) · A- (87-89) · B+ (83-86) · B (80-82) · B- (77-79) · C+ (73-76) · C (70-72) · C- (67-69) · D+ (63-66) · D (60-62) · D- (57-59) · F (0-56)

Report Features

Every analysis generates a self-contained HTML report with:

• Executive summary — Top strengths and concerns at a glance
• Radar chart — Scores across all 6 dimensions
• Interactive findings — Filter by severity/dimension, text search, keyboard navigation (j/k, o, /)
• File hotspot heatmap — Files ranked by finding density
• Technical debt quantification — Estimated hours and cost to remediate
• ROI analysis — Estimated return on fixing identified issues
• Compliance mapping — OWASP Top 10, SOC 2, PCI DSS 4.0, NIST CSF 2.0

Works offline. No external dependencies. One HTML file. Print-friendly for PDF export.

See sample reports

GitHub displays .html files as raw source when clicked. Use the "View rendered" links to see the actual reports in your browser.

• Sample reports — real Spectra runs against the Anthropic SDK, FastAPI, HTTPX, Aider, Simon Willison's LLM, and the Spectra repo itself
• Quickstart demo reports — Django, Express, FastAPI, Flask + a multi-repo leaderboard
• v0.6.0 self-scan — Spectra grading itself, with prompt-injection isolation, encrypted cache, signed receipts, and the audit log all active

Architecture

Full architecture reference: docs/architecture/ — 10 documents + 19 PlantUML diagrams covering the C4 model, domain entities, pipeline flow, agent orchestration, cache subsystem, security model, data flow, plugin extensibility, and the release pipeline. Status table tracks what shipped in v0.6.0 (the Q1 + Q2 capabilities) vs Q3+ designed work. Diagrams render via plantuml -tsvg docs/architecture/diagrams/*.puml.

Glossary: docs/glossary.md — at-a-glance index for the three numbering schemes that recur in code comments and audit events: roadmap capability numbers (#1-#70), SPEC-NNN error codes, and ADR-NNN architecture decisions. All 20 ADRs are now consolidated under docs/architecture/adr/.

System context

Spectra in its environment — who invokes it and what it talks to. Two install paths (local pip + GitHub Action), one PyPI package. Source: docs/diagrams/system-context.md.

flowchart LR
    classDef person      fill:#dbeafe,stroke:#1e3a8a,stroke-width:2px,color:#1e293b
    classDef system      fill:#ede9fe,stroke:#7C3AED,stroke-width:4px,color:#1e293b
    classDef external    fill:#fef3c7,stroke:#92400e,stroke-width:2px,color:#1e293b
    classDef storage     fill:#dcfce7,stroke:#166534,stroke-width:2px,color:#1e293b
    classDef distribution fill:#fef3c7,stroke:#92400e,stroke-width:2px,color:#1e293b

    Dev["<b>Developer</b><br/>[Person]<br/>Runs spectra analyze<br/>from a terminal"]:::person
    PR["<b>GitHub PR</b><br/>[External CI]<br/>pull_request event<br/>invokes the Action"]:::person

    Spectra(["<b>Spectra CLI</b><br/>[Software System]<br/>8 AI agents · 6 dimensions<br/>Clean Architecture · Python 3.12+<br/>6-stage pipeline + cache"]):::system

    Anthropic["<b>Anthropic API</b><br/>[External SaaS]<br/>Claude Opus 4.7<br/>all 8 agents"]:::external
    GitHub["<b>GitHub.com</b><br/>[External Service]<br/>Git clone source<br/>HTTPS only"]:::external
    PyPI["<b>PyPI</b><br/>[Distribution]<br/>pip install spectra-ai<br/>also installed by Action"]:::distribution
    FS[("<b>Local Filesystem</b><br/>[OS]<br/>~/.cache/spectra/cache.db (SQLite WAL)<br/>spectra-report.{html,json,sarif}")]:::storage

    Dev      -- "spectra analyze ."          --> Spectra
    PR       -- "uses: leocder07/spectra@v1" --> Spectra
    Spectra  -- "HTTPS · streaming /messages" --> Anthropic
    Spectra  -- "git clone (depth=1)"        --> GitHub
    Spectra  <-- "cache R/W · report write"  --> FS
    PyPI     -. "install (cold path)"        .-> Spectra

Clean Architecture layers

Four strict layers with one rule:

graph TB
    subgraph "Layer 4 — Infrastructure"
        INF[Anthropic API · Git · Tokens · Agents]
    end
    subgraph "Layer 3 — Adapters"
        ADP[CLI · Rich Terminal · HTML Presenter]
    end
    subgraph "Layer 2 — Use Cases"
        UC[Pipeline Orchestration · Protocol Interfaces]
    end
    subgraph "Layer 1 — Entities"
        ENT[Domain Models · Enums · Errors]
    end

    INF --> ADP
    INF --> UC
    INF --> ENT
    ADP --> UC
    ADP --> ENT
    UC --> ENT

    style ENT fill:#22C55E,stroke:#22C55E,color:#fff
    style UC fill:#7C3AED,stroke:#7C3AED,color:#fff
    style ADP fill:#F59E0B,stroke:#F59E0B,color:#fff
    style INF fill:#EF4444,stroke:#EF4444,color:#fff

The dependency rule: Source code dependencies only point inward. No exceptions.

Design Patterns

How Spectra Uses Claude

Multi-Model Strategy

Key Capabilities Used

• Parallel execution — 6 agents via asyncio.gather with semaphore rate limiting
• Token budget management — 800K tokens distributed by MetaPrompter's plan
• Adaptive thinking — CritiqueAgent reasons through each finding before passing judgment
• Structured output — Every agent returns Pydantic-validated JSON
• Prompt engineering — Few-shot JSON examples, hallucination guardrails, CWE/OWASP references
• Graceful degradation — If 2+ agents fail, partial report in DEGRADED state

Technology Stack

Numbers That Matter

See It Run on Real Repos

We scan well-known OSS projects on every release and check the results into the repo. Real Anthropic API spend, no cherry-picking, one shot per repo.

Per-repo grades + per-dimension breakdown live in the canonical leaderboard (docs/launch/leaderboard.md), which also links the per-repo public-mode JSON (overall grade, per-dimension scores, counts, cost, signed receipt — findings stripped per the dual-mode renderer). To inspect findings at file:line resolution, reproduce the run yourself with the snippet in the leaderboard's "Reproduce" section.

CI Integration

The official GitHub Action installs Spectra from PyPI and runs spectra analyze on every PR — no Python setup, no extra steps. See docs/github-action.md for the full reference.

# .github/workflows/spectra-analyze.yml
name: Spectra Analysis
on:
  pull_request:
    branches: [main]
jobs:
  analyze:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write   # post the grade as a PR comment
    steps:
      - uses: actions/checkout@v4
      - uses: leocder07/spectra@v1
        with:
          anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }}
          min-score: 70       # fail the build below 70/100

To send findings to the Security tab instead of a PR comment, set format: sarif and grant security-events: write:

    permissions:
      contents: read
      security-events: write
    steps:
      - uses: actions/checkout@v4
      - uses: leocder07/spectra@v1
        with:
          anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }}
          format: sarif

Severity gate (fail-on)

The Action ships with a fail-on: critical default — any critical finding fails the build so a regression cannot land silently. Loosen or tighten the gate per workflow:

- uses: leocder07/spectra@v1
  with:
    fail-on: high   # also fail on high — protect main from anything ≥ high

Set fail-on: none on draft / preview PRs when you want the report without the gate firing. Accepted values: critical, high, medium, low, none.

CLI Reference

Two top-level commands: spectra analyze and spectra cache.

spectra analyze

spectra analyze <repo-url-or-path> [flags]

The argument can be an HTTPS Git URL, a local path, or . for the current working tree (no clone).

Pre-flight: secret scan + workspace filtering

Spectra runs a fast pre-flight stage between INGEST and PLAN that:

1. Honors .gitignore (root + every nested .gitignore) so excluded files never reach a prompt or cache key. Use --no-gitignore to opt out.
2. Honors .spectraignore — same gitwildmatch syntax — for Spectra-only exclusions you don't want polluting your .gitignore. Always applied.
3. Scans for hard-coded secrets with a curated regex list (AWS keys, GitHub PATs, Anthropic keys, bearer tokens, Slack webhooks, RSA/OpenSSH private keys, plus an .env* heuristic). On detection, fails with SPEC-011 listing every match. Override with --allow-secrets (CI-safe; the run continues but every finding is logged at WARN).

Example .spectraignore:

# Generated client SDKs we don't author
clients/generated/
# Vendored protobuf stubs
**/proto/*_pb2.py
# Large fixtures
tests/fixtures/large_repo/

Per-agent model + effort

Override the default Claude Opus 4.7 wiring per agent role.

# Run all 6 specialists on Sonnet 4.6 (cheaper, slightly less accurate)
spectra analyze <repo> --model claude-sonnet-4-6

# Bump security agent's effort to max while keeping others at xhigh
spectra analyze <repo> --security-effort max

# Use Haiku for documentation only (it's cheap and docs don't need much reasoning)
spectra analyze <repo> --documentation-model claude-haiku-4-5

# Power-user JSON override
spectra analyze <repo> \
  --model-overrides '{"security":"claude-opus-4-7","documentation":"claude-haiku-4-5"}' \
  --effort-overrides '{"security":"max"}'

Roles: meta, architecture, security, quality, documentation, dependency, performance, critique.

Constraint: max effort is Opus-tier only (Sonnet 4.6 and Haiku 4.5 reject it).

JSON overrides win over per-flag overrides when both are present.

spectra cache

Spectra writes a SQLite cache to ${XDG_CACHE_HOME:-~/.cache}/spectra/$UID/cache.db (WAL mode, AES-256 via SQLCipher in v0.6.0). Five subcommands manage it:

Cache I/O failures are never fatal — the pipeline degrades to no-cache for the rest of the run (see SPEC-010).

Error codes

Every fallible operation in Spectra raises a typed SpectraError — SPEC-001 through SPEC-014. The full reference (when each fires, what to do, retryable yes/no, max retries) lives in docs/error-codes.md. The CLI surfaces the code in every brand-voice ✗ message so CI logs are searchable.

Verifying releases

Every release ships with two independent supply-chain attestations: SLSA L3 build provenance (via GitHub's attest-build-provenance) and a Sigstore keyless signature on every wheel. Both are produced inside the publish workflow and bound to the tag commit.

1. Verify SLSA build provenance

Confirms the artifact was built by leocder07/spectra's publish workflow on the expected tag commit — defeats the tag-move attack class.

# Install once
brew install gh   # or: see https://cli.github.com/

# Download the wheel from PyPI (or the release page)
pip download --no-deps spectra-ai==0.6.0 -d /tmp/spectra-verify

# Verify provenance
gh attestation verify /tmp/spectra-verify/spectra_ai-0.6.0-py3-none-any.whl \
  --repo leocder07/spectra

Expected output: Loaded digest sha256:... ✓ Verification succeeded!

2. Verify Sigstore signature

Confirms the wheel was signed by the publish workflow's OIDC identity. Bundles are attached to each GitHub Release as *.sigstore assets.

# Install once
pip install "sigstore>=3.0,<4.0"

# Download wheel + bundle
VER=0.6.0
gh release download "v${VER}" --repo leocder07/spectra \
  --pattern "spectra_ai-${VER}*.sigstore*"
pip download --no-deps "spectra-ai==${VER}" -d .

# Verify
python -m sigstore verify identity \
  --bundle "spectra_ai-${VER}-py3-none-any.whl.sigstore" \
  --cert-identity "https://github.com/leocder07/spectra/.github/workflows/publish.yml@refs/tags/v${VER}" \
  --cert-oidc-issuer "https://token.actions.githubusercontent.com" \
  "spectra_ai-${VER}-py3-none-any.whl"

Expected output: OK: spectra_ai-0.6.0-py3-none-any.whl

If either check fails, do not install — open an issue at https://github.com/leocder07/spectra/security/advisories/new.

Privacy & Data Processing

Spectra runs on the Customer's machine; the only outbound data flow is to Anthropic's API for inference, governed by the Customer's own Anthropic agreement. We publish a template Data Processing Addendum, an authoritative sub-processor list, and a per-edge data flow diagram so procurement and legal teams have a starting position rather than a blank page.

• docs/legal/DPA.md — GDPR Art. 28 — compatible Data Processing Addendum (template — requires legal review)
• docs/legal/SUBPROCESSORS.md — Sub-processor declaration (Anthropic only)
• docs/legal/DATA_FLOW.md — Per-edge data flow diagram, v0.6.0 baseline (audit sink + receipt edges)
• SECURITY.md — Vulnerability reporting, supported versions, hardening already shipped

Contributing

# Clone and install
git clone https://github.com/leocder07/spectra.git
cd spectra
pip install -e ".[dev]"

# Run tests
pytest tests/ -v

# Lint
ruff check src/ tests/
mypy src/

PRs welcome. Please follow the Clean Architecture dependency rule — it's enforced.