The Problem

Every AI coding session starts from scratch. The AI doesn't know your architecture, ignores your conventions, and repeats the same mistakes you corrected yesterday. Static rule files are manual and fragile. Every new conversation is a cold start.

Your corrections vanish. Your preferences reset. Your AI has amnesia.

Why Not Just CLAUDE.md?

CLAUDE.md is great for explicit instructions — but it's static text you maintain by hand. Symbiote is a living knowledge graph that updates itself every time your codebase changes.

They're complementary. Use CLAUDE.md for explicit instructions your AI should always follow. Use Symbiote for the deep project understanding no static file can provide.

Quick Start

As a Claude Code Plugin

/plugin marketplace add MohmmedAshraf/synapse
/plugin install symbiote@symbiote-plugins

No setup required — the plugin auto-installs the CLI, registers the MCP server, hooks, skills, and agents.

Manual Install (all editors)

npm install -g symbiote-cli
symbiote install

Auto-detects your installed editors (Claude Code, Cursor, Windsurf, Copilot, OpenCode), registers the MCP server globally for each, and sets up 9 Claude Code hooks + skills. Run it once.

Then in any project, open Claude Code and run:

/symbiote-init

This scans your codebase, extracts your coding preferences, project constraints, and architectural decisions — all in one step.

Symbiote initialized — scanned 142 files, recorded 18 DNA entries, 5 constraints, 3 decisions.

No manual config. No copy-pasting. After the first init, Symbiote's SessionStart hook auto-scans and boots the server on every new Claude Code session — zero cold start.

How It Works

Symbiote has two layers of intelligence that work together: Developer DNA (who you are) and the Project Brain (what your code is).

sequenceDiagram
    participant Brain as .brain/<br>Code Graph
    participant Sym as Symbiote
    participant AI as Claude Code
    participant DNA as ~/.symbiote/<br>Developer DNA

    Brain->>Sym: project structure, dependencies, health
    DNA->>Sym: coding rules, reasons, scoping

    loop Every interaction
        Sym->>AI: injects context (MCP + hooks)
        AI->>Sym: actions observed
        Sym->>Brain: re-indexes changed files
        Sym->>DNA: records corrections
    end

    Note over DNA: confidence evolves across sessions

Developer DNA — Your Coding Identity

Lives at ~/.symbiote/profiles/. Follows you across every project. Shareable.

When you correct your AI — "no, use early returns" — Symbiote captures it with the rule, the reason why, and which languages it applies to. Same correction across three sessions? Auto-promoted. Explicit instruction? Approved immediately at full confidence.

Your DNA is a single JSON profile — portable, exportable, switchable:

symbiote dna              # Active profile summary
symbiote dna export       # Export to .dna.json — share it anywhere
symbiote dna import <file|url>  # Load someone else's DNA
symbiote dna switch <name>      # Swap profiles instantly

Import a senior developer's DNA and your AI immediately codes in their style. Switch back to yours anytime. Your DNA is never lost.

Project Brain — Your Codebase's Nervous System

Lives at .brain/ in each repo. Auto-generated, optionally enriched.

• Code graph — Every function, class, import, and call chain mapped via Tree-sitter
• Semantic search — Natural language queries over your codebase (local embeddings, no API)
• Intent layer — Architectural decisions and constraints that travel with the repo
• Health engine — Dead code, circular deps, coupling hotspots, constraint violations
• Impact analysis — "What breaks if I change this?" with confidence-weighted blast radius

DNA Learning System

Corrections don't just get recorded — they evolve. Symbiote tracks confidence across sessions and promotes patterns that hold up over time.

stateDiagram-v2
    [*] --> Detected: AI observes pattern
    Detected --> Suggested: Confidence 0.3
    Suggested --> Reinforced: Pattern holds (+0.05/session)
    Reinforced --> Approved: 3+ sessions at ≥0.7
    Approved --> Core: Auto-promoted

    Detected --> Approved: Explicit correction (1.0)

    Reinforced --> Decayed: 30+ days unseen
    Suggested --> Decayed: 30+ days unseen
    Decayed --> [*]: Fades away

    Approved --> Replaced: Contradiction detected
    Replaced --> [*]: Old pattern removed

Session Intelligence

Symbiote hooks into 9 Claude Code lifecycle events — not just file reads and edits, but session start, user prompts, subagent spawns, compaction, and session end.

sequenceDiagram
    participant Dev as Developer
    participant CC as Claude Code
    participant Sym as Symbiote

    Note over CC,Sym: Session starts
    CC->>Sym: SessionStart
    Sym-->>CC: DNA + constraints + project overview

    Note over Dev,CC: Developer types a prompt
    Dev->>CC: "refactor the auth module"
    CC->>Sym: UserPromptSubmit
    Sym->>Sym: Haiku detects corrections

    Note over CC,Sym: AI reads a file
    CC->>Sym: PreToolUse (Read)
    Sym-->>CC: File context + dependencies + constraints
    CC->>Sym: PostToolUse (Read)
    Sym->>Sym: Update attention set

    Note over CC,Sym: AI edits a file
    CC->>Sym: PreToolUse (Edit)
    Sym-->>CC: Impact warnings + dependents
    CC->>Sym: PostToolUse (Edit)
    Sym->>Sym: Re-index file + record observation

    Note over CC,Sym: AI spawns subagent
    CC->>Sym: SubagentStart
    Sym-->>CC: DNA + constraints (~50 tokens)

    Note over CC,Sym: Context compacts
    CC->>Sym: PreCompact
    Sym->>Sym: Snapshot session state

    Note over CC,Sym: Session ends
    CC->>Sym: SessionEnd
    Sym->>Sym: Evolve DNA confidence

The hooks are the key. Your AI doesn't choose to use Symbiote — Symbiote is injected into every interaction. The AI writes better code because it has better context.

Every tool call is observed and correlated with the code graph — not raw text logs, structured graph metadata. Over time, Symbiote learns:

• Corrections — detected in real-time via Haiku, recorded with evidence
• Style patterns — extracted from what you actually write, not what you say
• Hotspots — files edited 3+ times in a session get flagged
• Failure patterns — errors correlated with affected symbols across sessions

The Living Brain

symbiote serve

Open the URL printed in your terminal. Your project's brain — a 3D neural graph of your entire codebase. Nodes are files, functions, classes. Edges are calls, imports, dependencies. Color-coded by module cluster. Sized by PageRank importance.

It reacts in real time. When your AI reads a file, the node glows. When it edits, the node pulses bright. When it navigates between files, impulses fire along the edges. You're watching your AI think.

Editor Support

Symbiote works with any MCP-compatible AI tool. symbiote install auto-detects your editors and configures everything.

Claude Code gets the deepest integration — 9 hook events cover the full session lifecycle. The brain reacts in real time. Other hosts access Symbiote through MCP tools the AI calls when it needs context.

Manual Setup

If you prefer to configure manually instead of symbiote install:

Claude Code:

claude mcp add symbiote -- npx -y symbiote-cli mcp

Cursor (~/.cursor/mcp.json):

{
    "mcpServers": {
        "symbiote": {
            "command": "npx",
            "args": ["-y", "symbiote-cli", "mcp"]
        }
    }
}

OpenCode (~/.config/opencode/.opencode.json):

{
    "mcpServers": {
        "symbiote": {
            "command": "npx",
            "args": ["-y", "symbiote-cli", "mcp"]
        }
    }
}

What Your AI Gets

When bonded, your AI gains 20 tools via MCP:

Plus 3 MCP resources: symbiote://dna, symbiote://project/overview, symbiote://project/health

Project Health

symbiote impact   # What breaks from your uncommitted changes?

The health engine scores your project 0-100 across four dimensions:

Every issue links to a file and line number. The Health Pulse view in the web UI makes them actionable.

What Gets Created

~/.symbiote/                 # Global — your coding identity
├── config.json              # { "active_profile": "personal" }
└── profiles/
    ├── personal.json        # Your DNA — always exists
    ├── theprime.json        # Imported from someone else
    └── kent-react.json      # Another imported profile

your-project/.brain/         # Per-project — the brain
├── symbiote.db              # Code graph + embeddings (gitignored)
└── intent/                  # Committed to git — shared with team
    ├── overview.md          # AI-generated project summary
    ├── decisions/           # "Why we chose X over Y"
    └── constraints/         # "No raw SQL in application code"

Each DNA profile is a single .dna.json file containing rich entries — rule, reason, category, language scoping, and evidence. Export yours, share it on Twitter, import someone else's with one command.

The intent layer is committed to git. New team member runs /symbiote-init — they get the full project brain plus their personal DNA on top. Same project understanding, individual style.

Language Support

Symbiote uses Tree-sitter for precise code parsing. Bundled languages ship with the package and have dedicated extraction patterns. On-demand languages are downloaded on first encounter and use generic AST traversal.

Any other language with a Tree-sitter grammar also works — downloaded and cached at ~/.symbiote/grammars/ on first encounter. Functions and classes are extracted via generic traversal; deeper features depend on language-specific patterns.

CLI Reference

Tech Stack

Privacy

Everything runs locally. No data leaves your machine. No external API calls for core features. The code graph, embeddings, DNA, session observations, and health analysis all run on your hardware. Observations store graph metadata only (which tool, which file, which symbols) — never file contents or command outputs.

License

MIT