👻 Specter

Give your codebase a voice.
A code intelligence CLI that speaks as your codebase in first person.
65 commands. 14 MCP tools. 12 personality modes. 1 ghost in your git history.

---

What Makes Specter Different?

Traditional analysis tools show metrics without meaning. Specter connects the dots:

The Problem	Specter's Answer
"Cyclomatic complexity: 45"	Where the hotspots are + why they matter
"Tech debt exists"	$510k annual maintenance burden (your hourly rate)
"Bus factor: 1"	Who owns what + what breaks if they leave
Numbers without context	AI-powered explanations in 12 personality modes

# Install and get started in 30 seconds
npm install -g @purplegumdropz/specter
specter scan && specter health

# Or try without installing
npx @purplegumdropz/specter-roast

Watch 30-second demo →

---

Real-World Examples

Find the code that's slowing your team down

specter hotspots              # Complexity × Churn = Refactoring Priority
specter cost                  # Tech debt in dollars ($510k/year)
specter bus-factor            # Who leaves = what breaks?

Understand why code exists

specter why src/utils/api.ts  # Git history + patterns + context
specter ask "What are the main architectural patterns?"
specter ask "What would break if I changed this file?"

Get insights with personality

specter health --personality mentor   # Educational explanations
specter health --personality critic   # Brutal honesty
specter roast                         # Comedic codebase roast

---

GitHub Copilot CLI Integration

Let AI assistants analyze your codebase directly:

# Add to Copilot CLI
copilot mcp add specter -- npx @purplegumdropz/specter-mcp

# Then use natural language
copilot -p "Use specter to find complexity hotspots"
copilot -p "Use specter to suggest refactoring for the most complex file"

14 MCP tools for file relationships, complexity hotspots, dead code detection, impact analysis, bus factor, code archaeology, and more.

6 prompt templates: specter:introduce, specter:review, specter:onboard, specter:refactor-plan, specter:standup-summary, specter:health-check

See Copilot CLI Integration | MCP Integration | Example Prompts

---

Command Reference

Health & Diagnostics

Command	What it tells you
health	Overall codebase health (0-100) with complexity distribution
scan	Build the knowledge graph (run this first!)
doctor	Environmental diagnostics
status	Graph freshness and stats
vitals	Real-time vital signs

Hotspots & Risk Analysis

Command	What it reveals
hotspots	Complexity × Churn heatmap
bus-factor	Who owns critical code? Replacement risk?
coupling	Hidden dependencies that change together
cycles	Circular dependencies
drift	Duplicate/diverged patterns
cost	Tech debt in dollars
risk	Risk analysis for staged changes
knowledge-map	Team expertise heatmap

Metrics & Trends

Command	Measures
velocity	Complexity growth per week
trajectory	Project health trends
trends	Historical health with sparklines
dora	DORA metrics
predict	PR impact prediction

Intelligent Search & Q&A

Command	Use case
ask <question>	Natural language Q&A
search <query>	Semantic code search
who <file>	Find experts for any file
why <file>	Explain why code exists
explain-hotspot	Deep dive on hotspots
suggest-refactor	AI refactoring suggestions

Team & Workflow

Command	Purpose
morning	Daily standup briefing
standup	Generate standup notes
precommit	Risk check before committing
compare	Health between branches
review <pr>	AI-powered PR review
reviewers	Suggest PR reviewers
safe	Safe zones for new contributors
danger	High-risk danger zones
report	Comprehensive markdown report

Fun & Shareable

Command	Vibe
roast	Comedic codebase roast
tinder	Dating profile (green/red flags)
horoscope	Daily code horoscope
wrapped	Spotify Wrapped-style review
fortune	Tarot-style three-card spread
dna	Visual DNA fingerprint
anthem	AI-generated theme song
fame	Compare to famous projects
origin	AI-generated origin story
confess <file>	File confesses its sins
obituary <file>	Memorial for deleted files
seance	Summon deleted code spirits
meme	Generate meme from metrics
blame-game	Gamified blame awards

Utilities

Command	Purpose
init	Interactive project setup
init-hooks	Install git hooks
dashboard	Interactive web visualization
diagram	Architecture diagrams (ASCII, Mermaid, D2)
changelog	Generate changelog
breaking-changes	Detect breaking changes
achievements	Unlock 18 badges
streaks	Daily usage streaks
leaderboard	Team gamification
watch	Real-time file monitoring
tour	Guided walkthrough
fix [file]	Actionable fix suggestions

Output Formats

All analysis commands support structured output:

specter health --json              # Machine-readable
specter hotspots --json            # Parse in scripts/CI
specter dora --json | jq '.score'  # Extract specific fields

---

12 Personality Modes

Add --personality <mode> to any command:

Mode	Tone	Best for
default	Balanced, professional	Daily use
mentor	Educational, explains why	Learning
critic	Harsh, points out flaws	Honest feedback
historian	Focuses on evolution	Understanding decisions
cheerleader	Positive, encouraging	Team morale
minimalist	Brief, data-only	Automation
noir	Hard-boiled detective	Fun presentations
therapist	Gentle, understanding	Sensitive topics
roast	Brutal comedy	Entertainment
dramatic	Epic narrator	Presentations
ghost	Deleted code voice	Historical analysis
executive	Business-focused, ROI	Leadership reports

---

CI/CD Integration

# Fail build if health drops
specter health --exit-code --threshold 70

# Fail on circular dependencies
specter cycles --exit-code

# Check PR impact
specter predict --branch feature/my-change

GitHub Actions

name: Specter Analysis
on: [pull_request]
jobs:
  analyze:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - run: npx @purplegumdropz/specter scan --json
      - run: npx @purplegumdropz/specter health --json --exit-code --threshold 60
      - run: npx @purplegumdropz/specter predict --branch ${{ github.head_ref }}

---

Accessibility

Specter supports colorblind-friendly mode:

specter health --accessible
# or
SPECTER_ACCESSIBLE=true specter health

See the Accessibility Guide for details.

---

Data Storage

Specter creates a .specter/ directory (auto-added to .gitignore):

.specter/
  graph.json      # Knowledge graph
  metadata.json   # Quick-access metadata
  streaks.json    # Usage streaks and achievements
  history/        # Health snapshots over time

---

Requirements

• Node.js 20+
• Git repository (optional, for history features)
• ~50MB disk for typical projects

No external services. No telemetry. Your data stays on your machine.

---

Documentation

Guide	Topic
Copilot CLI Integration	GitHub Copilot CLI setup
MCP Integration	All 14 MCP tools
Example Prompts	Real-world AI prompts
Accessibility	Colorblind-friendly mode
Comparison	vs SonarQube, CodeClimate, etc
Troubleshooting	Common issues & solutions
Contributing	How to contribute
Security	Security policy

---

License

MIT

---

Built with 👻 by Liz Stein
"I am the ghost in your git history."