👻 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:

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

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

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

Hotspots & Risk Analysis

Metrics & Trends

Intelligent Search & Q&A

Team & Workflow

Fun & Shareable

Utilities

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:

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

License

MIT

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