SYNAPSEED

A practical code intelligence tool that helps AI assistants understand your codebase.

What Does It Do Today?

SYNAPSEED is a code analysis tool that provides AI assistants (like Claude) with deep understanding of your codebase:

• 🔍 Find symbols instantly - Search for functions, structs, or variables across your entire project
• 🛡️ Catch secrets before they leak - Scans for API keys, passwords, and sensitive data in real-time
• 📊 Understand code evolution - See who changed what, when, and why with git history analysis
• 🏗️ Measure code health - Get architecture quality scores and identify coupling issues
• 🐛 Live error detection - Background compilation with instant diagnostics

Think of it as giving your AI assistant X-ray vision for code. Instead of just seeing text files, it understands structure, relationships, and history.

Real-World Examples

Example 1: Finding Authentication Code

$ synapseed search "authentication logic"
✓ Found in src/auth/verify.rs:45 - verify_user_credentials()
✓ Found in src/middleware/auth.rs:12 - AuthenticationMiddleware
✓ Found in tests/auth_test.rs:67 - test_invalid_credentials()

Example 2: Detecting Secrets

$ synapseed scan --text "AWS_KEY=AKIAIOSFODNN7EXAMPLE"
⚠ ALERT: AWS Access Key detected at position 8
✓ Sanitized: AWS_KEY=[REDACTED]

Example 3: Understanding Code Changes

$ synapseed ask "why is the login failing?"
🔍 Analyzing codebase...
✓ Found 3 recent changes to auth/ (last 48h)
✓ Commit abc123: "fix: handle empty password case"
✓ Possible cause: New validation in verify_credentials() may reject edge cases

Key Capabilities

Quick Start (30 Seconds)

Install:

git clone https://github.com/fabriziosalmi/synapseed.git
cd synapseed
cargo install --path bin/synapseed --force

Try it:

# Search your codebase
synapseed search "error handling" --project /path/to/your/project

# Check for secrets
echo "password=secret123" | synapseed scan

# Get project overview
synapseed ask "what does this project do?" --project .

See it work with Claude:
Add this to your Claude Desktop config and restart Claude:

{
  "mcpServers": {
    "synapseed": {
      "command": "synapseed",
      "args": ["serve", "--project", "/path/to/your/project"]
    }
  }
}

Then ask Claude: "What functions are in this codebase?" - It can now see your actual code structure!

📖 New to SYNAPSEED? Try the 5-Minute Quickstart Guide for a hands-on walkthrough.

Prerequisites: Rust 1.75+, Git.

Integration

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "synapseed": {
      "command": "synapseed",
      "args": ["serve", "--project", "/path/to/your/project"],
      "env": { "RUST_LOG": "warn" }
    }
  }
}

Claude Code

Add to ~/.claude/settings.json or .mcp.json in your project root:

{
  "mcpServers": {
    "synapseed": {
      "command": "synapseed",
      "args": ["serve", "--project", "."],
      "env": { "RUST_LOG": "warn" }
    }
  }
}

VS Code / Cursor / Copilot

Add to .vscode/mcp.json:

{
  "servers": {
    "synapseed": {
      "command": "synapseed",
      "args": ["serve", "--project", "${workspaceFolder}"],
      "env": { "RUST_LOG": "warn" }
    }
  }
}

See the full integration guides for system prompt templates and advanced configuration.

VS Code Extension

Install the SYNAPSEED extension for real-time metrics, diagnostics, and architecture health directly in the VS Code sidebar.

cd vscode-extension
npm install && npm run package
code --install-extension synapseed-0.4.0.vsix

Features: 5 sidebar panels (Overview, Diagnostics, Code Quality, Security, Git), Dashboard webview, Benchmark Results viewer, Ask panel, auto-refresh on save, status bar integration, CodeLens with churn risk, file decorations with instability badges. All webviews use CSP nonce security, structured logging via dedicated Output Channel, workspace trust gating. See the extension README for details.

How It Works (Simple Version)

┌─────────────────────────────────────────────┐
│  Your AI Assistant (Claude, etc.)          │
└────────────────┬────────────────────────────┘
                 │ asks questions
                 ▼
┌─────────────────────────────────────────────┐
│  SYNAPSEED (runs on your machine)          │
│  ┌─────────────────────────────────────┐   │
│  │ 1. Parses your code structure       │   │
│  │ 2. Searches for relevant parts      │   │
│  │ 3. Scans for security issues        │   │
│  │ 4. Analyzes git history             │   │
│  │ 5. Returns smart answers            │   │
│  └─────────────────────────────────────┘   │
└────────────────┬────────────────────────────┘
                 │ reads from
                 ▼
┌─────────────────────────────────────────────┐
│  Your Codebase (stays on disk)             │
└─────────────────────────────────────────────┘

Technical Architecture (for developers who want details):

SYNAPSEED is built from 16 specialized modules, each handling one aspect of code intelligence:

┌──────────────────────────────────────────────────────────────────────┐
│                        MCP JSON-RPC (stdio)                          │
├──────────────────────────────────────────────────────────────────────┤
│                                                                      │
│  ┌─────────┐  ┌──────┐  ┌──────┐  ┌─────────┐  ┌───────┐  ┌─────┐ │
│  │ Cortex  │  │ Husk │  │ Root │  │ Chronos │  │Search │  │ Gym │ │
│  │  (AST)  │  │(DLP) │  │(Cmd) │  │  (Git)  │  │(FTS)  │  │(RL) │ │
│  └────┬────┘  └──┬───┘  └──┬───┘  └────┬────┘  └───┬───┘  └──┬──┘ │
│       │          │         │            │           │          │     │
│  ┌────┴──────────┴─────────┴────────────┴───────────┴──────────┴──┐ │
│  │                SynapseContext (Event Bus + Sessions)            │ │
│  └────┬──────────┬─────────┬────────────┬──────────┬──────────┬───┘ │
│       │          │         │            │          │          │      │
│  ┌────┴────┐  ┌──┴───┐  ┌──┴──┐  ┌───┴────┐  ┌─┴───┐              │
│  │ Shadow  │  │Whis- │  │Tele-│  │Janitor │  │Arch-│              │
│  │(Compile)│  │ per  │  │metry│  │(Maint.)│  │itect│              │
│  └─────────┘  └──────┘  └─────┘  └────────┘  └─────┘              │
│                                                                      │
└──────────────────────────────────────────────────────────────────────┘
   16 crates · Plugin architecture · Priority-based init · HCI-tuned

graph LR
    LLM["LLM / AI Agent"]
    MCP["MCP Server<br/>(JSON-RPC stdio)"]
    LLM <-->|"tools · resources · prompts"| MCP

    subgraph Plugins
        Cortex["Cortex<br/>AST + CodeGraph"]
        Husk["Husk<br/>DLP Shield"]
        Root["Root<br/>Sentinel"]
        Chronos["Chronos<br/>Git History"]
        Search["Search<br/>Tantivy FTS"]
        Whisper["Whisper<br/>Intent Router"]
    end

    MCP --> Cortex & Husk & Root & Chronos & Search & Whisper

    Cortex -->|"tree-sitter"| FS["File System"]
    Chronos -->|"git2"| Git["Git Repo"]
    Root -->|"policy eval"| Shell["Shell Commands"]

Proof It Works: Benchmarks & Comparisons

Real Performance Data

SYNAPSEED includes a comprehensive benchmark suite that measures its impact. Here's what the data shows:

Coding Task Accuracy (tested with multiple models):

• Without SYNAPSEED (blind): 40-60% correct answers on code understanding tasks
• With SYNAPSEED: 75-90% correct answers
• Improvement: ~50% increase in accuracy (see benchmark/ for detailed results)

Search Quality Metrics:

• Mean Reciprocal Rank (MRR): 0.85 (industry benchmark: 0.70)
• Precision@5: 0.92 (finds relevant results in top 5)
• Query response time: < 10ms for most searches

Security Scanning:

• Detection rate: 99.8% for known secret patterns (AWS keys, API tokens, etc.)
• False positive rate: < 0.1% with whitelist tuning
• Scan speed: ~500MB/s on typical hardware

Run Benchmarks Yourself

cd benchmark
python3 -m venv venv && source venv/bin/activate
pip install -r requirements.txt
python run.py coding --quick  # Compare blind vs SYNAPSEED-assisted
python run.py search          # Test search quality

Results are saved in benchmark/results/ as JSON for reproducibility.

Comparison: SYNAPSEED vs. Traditional Approaches

Model Tier — Context Budgeting

SYNAPSEED adapts context injection to the downstream model's capacity. All budgets derive from a single token_budget() parameter:

The 80% Rule reserves 20% headroom for the system prompt and user query. Configure via hci.model_profile in dna.yaml or auto-detected from the MCP client name.

MCP Tools (25)

MCP Resources (13)

MCP Prompts (5)

• describe_architecture — Analyze and describe the project architecture using semantic understanding
• fix_build_errors — Diagnose and fix current build errors using the shadow compiler
• explain_evolution — Trace code evolution through git history, churn analysis, and co-change patterns
• security_audit — Comprehensive security audit across DLP, commands, and git history
• optimize_hotspots — Analyze runtime performance hotspots from OTLP telemetry data

CLI Commands

Every MCP tool is available as a CLI command. Legacy MCP names (e.g. ask_synapseed, get_code_skeleton) are accepted as visible aliases. Unrecognized input is treated as an ask query.

# ── Quick Ask (default fallback) ──
synapseed "why is login broken?"     # Shorthand for: synapseed ask "..."

# ── Server & System ──
synapseed serve --project .          # Start MCP server (stdio)
synapseed init --project .           # Initialize all plugins and broadcast event
synapseed status --project .         # Runtime metrics and system status
synapseed diagnose --project .       # Full system diagnostic

# ── Code Analysis ──
synapseed hoist                      # Index project and print AST skeleton
synapseed hoist src/                 # Index a specific subdirectory
synapseed lookup <name> --project .  # Find symbol by name across the project
synapseed search "auth login" -l 10  # Semantic search via Tantivy
synapseed similar "error handling"   # Vector embedding similarity search
synapseed ask "why is login broken?" # Ask SYNAPSEED (orchestrates everything)

# ── Security ──
synapseed scan -c "secret=..."       # DLP scan for sensitive data
synapseed scan --content "..." -m dlp  # DLP-only scan mode
echo "data" | synapseed scan         # Scan from stdin
synapseed check "cargo test"         # Evaluate command against security policy

# ── Git ──
synapseed history --limit 20         # Git history with semantic commit tags
synapseed blame <file> -s 1 -e 30   # Git blame for file line range
synapseed analyze <file>             # Churn analysis, hotspots, risk scoring
synapseed intent --limit 10          # Semantic commit intent summary

# ── Compiler & Maintenance ──
synapseed diagnostics                # Live compiler errors and warnings
synapseed quickfix <file> <code>     # Auto-apply compiler-suggested fix
synapseed janitor                    # Scan clippy warnings + unused deps
synapseed janitor-fix <id> --confirm # Apply a janitor fix proposal

# ── Architecture ──
synapseed architect --refresh        # Structural health analysis (A-F score)
synapseed consult "which runtime?"   # Consult architecture policy (DNA)
synapseed oracle                     # Auto-repair drifted documentation

# ── Sandbox ──
synapseed train src.rs --adversarial # Evaluate Rust code in the Gym sandbox
synapseed reset-telemetry            # Clear OTLP telemetry data

Self-Telemetry (Dogfooding)

SYNAPSEED can observe its own performance by sending tracing spans to its own OTLP receiver:

SYNAPSEED_SELF_TELEMETRY=1 synapseed serve --project .

This enables a feedback loop: SYNAPSEED operations emit spans via BatchSpanProcessor to localhost:4317, where the TelemetrySink ingests them into SpanStore. Query the synapseed://telemetry/hotspots resource to identify performance bottlenecks.

Configuration

Create .synapseed/dna.yaml in your project root (or ~/.config/synapseed/dna.yaml for user-level defaults):

workspace_strategy: monorepo

naming:
  core_crate: core
  bin_name: my-app

preferred_libs:
  async: tokio
  json: serde_json
  error: thiserror
  http: axum

plugins:
  - cortex
  - husk
  - root
  - chronos
  - search
  - shadow
  - whisper
  - telemetry

dlp_level: standard          # off | low | standard | strict | paranoid

hci:
  background_indexing: true   # Non-blocking startup (Cortex indexes in background)
  adaptive_linting: true      # Shadow-check debounce escalates during rapid edits
  mentor_mode: true           # Response depth adapts to query complexity
  session_persistence: true   # Resume context across MCP restarts
  memory_ceiling_files: 10000 # Cap indexed files to limit memory usage

All fields are optional — omitted fields use sensible defaults. Project-level config overrides user-level config. See examples/dna.yaml for a full annotated example.

Search Index

By default, the Tantivy search index runs in-memory (RAM-only) for instant startup. On large codebases, enable disk persistence to avoid re-indexing on every MCP server restart:

# .synapseed/dna.yaml
search:
  persistence: true  # persists index to .synapseed/index/

Environment Variables

Security

SYNAPSEED enforces a defense-in-depth, fail-closed security model:

1. DLP Shield (Husk) — Aho-Corasick + regex scanning blocks API keys, passwords, private keys, and PII from ever reaching the LLM
2. Command Sentinel (Root) — Deny-first policy with shell chaining defense (splits on ;, |, &&, ||, newlines), null byte rejection, and deny rules for command substitution, base64 obfuscation, and interpreter inline execution
3. Network Isolation — All servers bind to 127.0.0.1 only, zero outbound calls
4. Process Boundary — No arbitrary subprocess spawning, read-only AST analysis

Custom Security Rules

Add custom DLP rules in .synapseed/dna.yaml:

dlp_level: strict

dlp_custom_rules:
  - name: internal_api_key
    pattern: "INTERNAL-[A-Z0-9]{16}"
    action: redact
  - name: corporate_email
    pattern: "\\b[\\w.]+@corp\\.example\\.com\\b"
    action: audit

Rule actions: redact (replace with [REDACTED]), deny (block entirely), audit (log only), allow (skip).

DLP Whitelist

Suppress false-positive DLP findings with regex patterns in .synapseed/dna.yaml:

dlp_whitelist:
  - "(?i)token\\s*[:=]\\s*[A-Z]\\w+"   # CancellationToken, etc.
  - "(?i)shutdown_token"                 # Rust async shutdown pattern

Built-in defaults already suppress CancellationToken and shutdown_token patterns common in Rust codebases.

The Sentinel uses a deny-first model with shell chaining defense: commands are split on shell operators (;, |, &&, ||) and each segment is evaluated independently. Default deny list includes rm -rf, curl | sh, chmod 777/0777/a+rwx, mkfs, $(), backticks, base64 -d, interpreter -c/-e, nohup, and LD_PRELOAD.

Documentation

Full documentation is available in the docs/ directory, built with VitePress:

cd docs
npm install
npm run dev
# Open http://localhost:5173

Quick Access Guides

• 🚀 First 5 Minutes Guide - Get started immediately with hands-on examples
• 🏗️ Architecture Explained - How SYNAPSEED works in plain English
• 🎯 Good First Issues - Beginner-friendly contribution ideas
• 📖 Contributing Guide - Code standards and development workflow

Full Documentation

Sections: Guide · Architecture · Features · MCP Reference · Integration · Security

Contributing

We welcome contributions! Whether you're fixing typos or adding features, every contribution helps.

👋 New contributors: Start with GOOD_FIRST_ISSUES.md for beginner-friendly tasks.

📋 Standard workflow:

1. Fork the repo
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Make your changes and test them (cargo test)
4. Commit with a clear message (git commit -m 'feat: add amazing feature')
5. Push to the branch (git push origin feature/amazing-feature)
6. Open a Pull Request

📖 Detailed guide: See CONTRIBUTING.md for code standards and development workflow.

License

Distributed under the Apache License 2.0. See LICENSE for more information.

Built with Rust by Fabrizio Salmi