symbiote-cli 0.1.0 → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +404 -0
  2. package/package.json +2 -2
package/README.md ADDED
@@ -0,0 +1,404 @@
1
+ <div align="center">
2
+
3
+ # Symbiote
4
+
5
+ **Your AI forgets. Symbiote remembers.**
6
+
7
+ _Symbiote bonds with your AI tools — giving them memory, context, and your coding DNA._
8
+
9
+ [![npm](https://img.shields.io/npm/v/symbiote-cli?style=flat-square&color=7b5fff)](https://www.npmjs.com/package/symbiote-cli)
10
+ [![license](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](LICENSE)
11
+ [![TypeScript](https://img.shields.io/badge/TypeScript-strict-blue?style=flat-square)](https://www.typescriptlang.org/)
12
+ [![MCP](https://img.shields.io/badge/MCP-compatible-7b5fff?style=flat-square)](https://modelcontextprotocol.io/)
13
+
14
+ </div>
15
+
16
+ ---
17
+
18
+ ## The Problem
19
+
20
+ 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.
21
+
22
+ **Your corrections vanish. Your preferences reset. Your AI has amnesia.**
23
+
24
+ ## Why Not Just CLAUDE.md?
25
+
26
+ 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.
27
+
28
+ | | CLAUDE.md | Symbiote |
29
+ | ------------------------- | --------------------------------- | ------------------------------------------------ |
30
+ | **Project structure** | You write and maintain it | Auto-scanned, always current |
31
+ | **Dependencies & impact** | Not possible | Full graph — "what breaks if I change this?" |
32
+ | **File connections** | You document them manually | Every import, call, and edge mapped |
33
+ | **Coding style** | You write rules once | Learns from corrections, carries across projects |
34
+ | **Stays current** | Only if you remember to update it | Re-indexes on every change |
35
+
36
+ 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.
37
+
38
+ ---
39
+
40
+ ## Quick Start
41
+
42
+ ```bash
43
+ npx symbiote-cli install
44
+ ```
45
+
46
+ One command. 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 + the `/symbiote-init` skill. Run it once.
47
+
48
+ Then in any project, open Claude Code and run:
49
+
50
+ ```
51
+ /symbiote-init
52
+ ```
53
+
54
+ This scans your codebase, extracts your coding preferences, project constraints, and architectural decisions — all in one step.
55
+
56
+ ```
57
+ Symbiote initialized — scanned 142 files, recorded 18 DNA entries, 5 constraints, 3 decisions.
58
+ ```
59
+
60
+ 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.
61
+
62
+ ---
63
+
64
+ ## How It Works
65
+
66
+ Symbiote has two layers of intelligence that work together: **Developer DNA** (who you are) and the **Project Brain** (what your code is).
67
+
68
+ ```mermaid
69
+ sequenceDiagram
70
+ participant Brain as .brain/<br>Code Graph
71
+ participant Sym as Symbiote
72
+ participant AI as Claude Code
73
+ participant DNA as ~/.symbiote/<br>Developer DNA
74
+
75
+ Brain->>Sym: project structure, dependencies, health
76
+ DNA->>Sym: style traits, preferences, anti-patterns
77
+
78
+ loop Every interaction
79
+ Sym->>AI: injects context (MCP + hooks)
80
+ AI->>Sym: actions observed
81
+ Sym->>Brain: re-indexes changed files
82
+ Sym->>DNA: records corrections
83
+ end
84
+
85
+ Note over DNA: confidence evolves across sessions
86
+ ```
87
+
88
+ ### Developer DNA — Your Coding Identity
89
+
90
+ Lives at `~/.symbiote/dna/`. Follows you across every project.
91
+
92
+ When you correct your AI — _"no, use early returns"_ — Symbiote captures it. Same correction across three sessions? Auto-promoted from suggestion to approved trait. Explicit instruction? Approved immediately.
93
+
94
+ Your DNA is human-readable markdown. Review it, edit it, or ignore it:
95
+
96
+ ```bash
97
+ symbiote dna # Summary: 34 traits, 2 pending review
98
+ symbiote dna list # All traits with confidence scores
99
+ symbiote dna approve <id> # Promote a suggestion
100
+ ```
101
+
102
+ ### Project Brain — Your Codebase's Nervous System
103
+
104
+ Lives at `.brain/` in each repo. Auto-generated, optionally enriched.
105
+
106
+ - **Code graph** — Every function, class, import, and call chain mapped via Tree-sitter
107
+ - **Semantic search** — Natural language queries over your codebase (local embeddings, no API)
108
+ - **Intent layer** — Architectural decisions and constraints that travel with the repo
109
+ - **Health engine** — Dead code, circular deps, coupling hotspots, constraint violations
110
+ - **Impact analysis** — "What breaks if I change this?" with confidence-weighted blast radius
111
+
112
+ ---
113
+
114
+ ## DNA Learning System
115
+
116
+ Corrections don't just get recorded — they evolve. Symbiote tracks confidence across sessions and promotes patterns that hold up over time.
117
+
118
+ ```mermaid
119
+ stateDiagram-v2
120
+ [*] --> Detected: AI observes pattern
121
+ Detected --> Suggested: Confidence 0.3
122
+ Suggested --> Reinforced: Pattern holds (+0.05/session)
123
+ Reinforced --> Approved: 3+ sessions at ≥0.7
124
+ Approved --> Core: Auto-promoted
125
+
126
+ Detected --> Approved: Explicit correction (1.0)
127
+
128
+ Reinforced --> Decayed: 30+ days unseen
129
+ Suggested --> Decayed: 30+ days unseen
130
+ Decayed --> [*]: Fades away
131
+
132
+ Approved --> Replaced: Contradiction detected
133
+ Replaced --> [*]: Old pattern removed
134
+ ```
135
+
136
+ | Path | How it works |
137
+ | ----------------- | ------------------------------------------------------------------------------ |
138
+ | **Observed** | Symbiote detects a pattern in your code or corrections |
139
+ | **Reinforced** | Same pattern appears across multiple sessions (+0.05 confidence each time) |
140
+ | **Auto-promoted** | After 3+ sessions at ≥0.7 confidence, becomes an approved trait |
141
+ | **Explicit** | Direct corrections (_"don't use semicolons"_) skip straight to approved at 1.0 |
142
+ | **Decayed** | Patterns unseen for 30+ days gradually fade |
143
+ | **Contradicted** | New correction replaces the old pattern entirely |
144
+
145
+ ---
146
+
147
+ ## Session Intelligence
148
+
149
+ 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.
150
+
151
+ ```mermaid
152
+ sequenceDiagram
153
+ participant Dev as Developer
154
+ participant CC as Claude Code
155
+ participant Sym as Symbiote
156
+
157
+ Note over CC,Sym: Session starts
158
+ CC->>Sym: SessionStart
159
+ Sym-->>CC: DNA + constraints + project overview
160
+
161
+ Note over Dev,CC: Developer types a prompt
162
+ Dev->>CC: "refactor the auth module"
163
+ CC->>Sym: UserPromptSubmit
164
+ Sym->>Sym: Haiku detects corrections
165
+
166
+ Note over CC,Sym: AI reads a file
167
+ CC->>Sym: PreToolUse (Read)
168
+ Sym-->>CC: File context + dependencies + constraints
169
+ CC->>Sym: PostToolUse (Read)
170
+ Sym->>Sym: Update attention set
171
+
172
+ Note over CC,Sym: AI edits a file
173
+ CC->>Sym: PreToolUse (Edit)
174
+ Sym-->>CC: Impact warnings + dependents
175
+ CC->>Sym: PostToolUse (Edit)
176
+ Sym->>Sym: Re-index file + record observation
177
+
178
+ Note over CC,Sym: AI spawns subagent
179
+ CC->>Sym: SubagentStart
180
+ Sym-->>CC: DNA + constraints (~50 tokens)
181
+
182
+ Note over CC,Sym: Context compacts
183
+ CC->>Sym: PreCompact
184
+ Sym->>Sym: Snapshot session state
185
+
186
+ Note over CC,Sym: Session ends
187
+ CC->>Sym: SessionEnd
188
+ Sym->>Sym: Evolve DNA confidence
189
+ ```
190
+
191
+ 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.
192
+
193
+ Every tool call is observed and correlated with the code graph — not raw text logs, structured graph metadata. Over time, Symbiote learns:
194
+
195
+ - **Corrections** — detected in real-time via Haiku, recorded with evidence
196
+ - **Style patterns** — extracted from what you actually write, not what you say
197
+ - **Hotspots** — files edited 3+ times in a session get flagged
198
+ - **Failure patterns** — errors correlated with affected symbols across sessions
199
+
200
+ ---
201
+
202
+ ## The Living Brain
203
+
204
+ ```bash
205
+ symbiote serve
206
+ ```
207
+
208
+ Open `localhost:3333`. 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.
209
+
210
+ **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.
211
+
212
+ | View | What it shows |
213
+ | ---------------- | ------------------------------------------------ |
214
+ | **Brain Graph** | 3D neural visualization — the hero, always alive |
215
+ | **Health Pulse** | Code health score (0-100) with actionable issues |
216
+ | **DNA Lab** | Your traits — approve, reject, edit |
217
+
218
+ ---
219
+
220
+ ## Editor Support
221
+
222
+ Symbiote works with any MCP-compatible AI tool. `symbiote install` auto-detects your editors and configures everything.
223
+
224
+ | Host | MCP | Hooks (9 events) | Session Intelligence | Real-Time Brain |
225
+ | ------------------ | --- | ---------------- | -------------------- | --------------- |
226
+ | **Claude Code** | Yes | Yes | Yes | Yes |
227
+ | **Cursor** | Yes | — | — | — |
228
+ | **Windsurf** | Yes | — | — | — |
229
+ | **GitHub Copilot** | Yes | — | — | — |
230
+ | **OpenCode** | Yes | — | — | — |
231
+
232
+ 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.
233
+
234
+ ### Manual Setup
235
+
236
+ If you prefer to configure manually instead of `symbiote install`:
237
+
238
+ **Claude Code:**
239
+
240
+ ```bash
241
+ claude mcp add symbiote -- npx -y symbiote-cli mcp
242
+ ```
243
+
244
+ **Cursor** (`~/.cursor/mcp.json`):
245
+
246
+ ```json
247
+ {
248
+ "mcpServers": {
249
+ "symbiote": {
250
+ "command": "npx",
251
+ "args": ["-y", "symbiote-cli", "mcp"]
252
+ }
253
+ }
254
+ }
255
+ ```
256
+
257
+ **OpenCode** (`~/.config/opencode/.opencode.json`):
258
+
259
+ ```json
260
+ {
261
+ "mcpServers": {
262
+ "symbiote": {
263
+ "command": "npx",
264
+ "args": ["-y", "symbiote-cli", "mcp"]
265
+ }
266
+ }
267
+ }
268
+ ```
269
+
270
+ ---
271
+
272
+ ## What Your AI Gets
273
+
274
+ When bonded, your AI gains 17 tools via MCP:
275
+
276
+ | Tool | Purpose |
277
+ | ------------------------ | -------------------------------------------------- |
278
+ | `get_developer_dna` | Your style and preferences, filtered by relevance |
279
+ | `get_project_overview` | Tech stack, structure, modules, health summary |
280
+ | `get_context_for_file` | Dependencies, dependents, constraints for any file |
281
+ | `get_context_for_symbol` | Full context for a specific symbol |
282
+ | `query_graph` | Symbol search, call chains, dependency tracing |
283
+ | `semantic_search` | Natural language search over the codebase |
284
+ | `get_constraints` | Active project rules, scoped to file or module |
285
+ | `get_decisions` | Architectural decisions with rationale |
286
+ | `get_health` | Dead code, cycles, coupling, violations |
287
+ | `get_impact` | Blast radius analysis with confidence scores |
288
+ | `get_architecture` | Module boundaries, layering, entry points |
289
+ | `find_patterns` | Recurring code patterns across the codebase |
290
+ | `detect_changes` | Git diff mapped to affected graph nodes |
291
+ | `rename_symbol` | Graph-aware multi-file rename preview |
292
+ | `propose_decision` | AI writes back a discovered decision |
293
+ | `propose_constraint` | AI writes back an inferred constraint |
294
+ | `record_instruction` | Captures your corrections for DNA learning |
295
+
296
+ Plus 3 MCP resources: `symbiote://dna`, `symbiote://project/overview`, `symbiote://project/health`
297
+
298
+ ---
299
+
300
+ ## Project Health
301
+
302
+ ```bash
303
+ symbiote impact # What breaks from your uncommitted changes?
304
+ ```
305
+
306
+ The health engine scores your project 0-100 across four dimensions:
307
+
308
+ | Dimension | Weight | What it catches |
309
+ | --------------------- | ------ | ------------------------------------------- |
310
+ | Constraint violations | 40% | Your own rules being broken |
311
+ | Circular dependencies | 20% | Modules that shouldn't depend on each other |
312
+ | Dead code | 20% | Unused exports, orphan files |
313
+ | Coupling hotspots | 20% | Files that change together too often |
314
+
315
+ Every issue links to a file and line number. The Health Pulse view in the web UI makes them actionable.
316
+
317
+ ---
318
+
319
+ ## What Gets Created
320
+
321
+ ```
322
+ ~/.symbiote/ # Global — your coding identity
323
+ ├── config.json
324
+ └── dna/
325
+ ├── style/ # "Use early returns, not nested else"
326
+ ├── preferences/ # "Drizzle over Prisma"
327
+ ├── anti-patterns/ # "No nested ternaries"
328
+ └── decisions/ # "Composition over inheritance"
329
+
330
+ your-project/.brain/ # Per-project — the brain
331
+ ├── symbiote.db # Code graph + embeddings (gitignored)
332
+ └── intent/ # Committed to git — shared with team
333
+ ├── overview.md # Auto-generated project summary
334
+ ├── decisions/ # "Why we chose X over Y"
335
+ └── constraints/ # "No raw SQL in application code"
336
+ ```
337
+
338
+ 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.
339
+
340
+ ---
341
+
342
+ ## Language Support
343
+
344
+ 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.
345
+
346
+ | Language | Functions | Classes | Methods | Imports | Calls | Types | Enums |
347
+ | ---------- | --------- | ------- | ------- | ------- | ----- | ----- | ----- |
348
+ | TypeScript | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
349
+ | JavaScript | ✓ | ✓ | ✓ | ✓ | ✓ | — | — |
350
+ | TSX | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
351
+ | Python | ✓ | ✓ | ✓ | ✓ | ✓ | — | — |
352
+ | Go | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | — |
353
+ | Rust | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
354
+ | Java | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
355
+ | C | ✓ | ✓ | — | ✓ | ✓ | ✓ | ✓ |
356
+ | C++ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
357
+ | Ruby | ✓ | ✓ | ✓ | ✓ | ✓ | — | — |
358
+ | PHP | ✓ | ✓ | ✓ | ✓ | ✓ | — | — |
359
+
360
+ > **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.
361
+
362
+ ---
363
+
364
+ ## CLI Reference
365
+
366
+ | Command | What it does |
367
+ | ----------------------- | ---------------------------------------------- |
368
+ | `symbiote install` | One-time global setup for all detected editors |
369
+ | `symbiote scan` | Rescan codebase (incremental) |
370
+ | `symbiote scan --force` | Full rescan, ignore cache |
371
+ | `symbiote serve` | MCP server + web UI at localhost:3333 |
372
+ | `symbiote mcp` | MCP server only (stdio, for editors) |
373
+ | `symbiote dna` | View and manage developer DNA |
374
+ | `symbiote impact` | Analyze impact of working changes |
375
+ | `symbiote unbond` | Detach from all AI hosts |
376
+
377
+ ---
378
+
379
+ ## Tech Stack
380
+
381
+ | Layer | Technology |
382
+ | -------------- | ------------------------------------------------------------ |
383
+ | **Language** | TypeScript (strict mode) |
384
+ | **Monorepo** | Turborepo (packages/cli + packages/web) |
385
+ | **Parsing** | Tree-sitter (11 bundled languages) |
386
+ | **Database** | DuckDB + sqlite-vec (graph storage + vector search) |
387
+ | **MCP** | @modelcontextprotocol/sdk (stdio + HTTP) |
388
+ | **Embeddings** | Transformers.js (local, all-MiniLM-L6-v2) |
389
+ | **Graph** | Graphology (Louvain, PageRank, betweenness) |
390
+ | **Web UI** | Vite + React 19 + react-three-fiber + Three.js + custom GLSL |
391
+ | **Styling** | Tailwind CSS v4 (dark theme) |
392
+ | **Testing** | Vitest (799 tests across 85 files) |
393
+
394
+ ---
395
+
396
+ ## Privacy
397
+
398
+ 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.
399
+
400
+ ---
401
+
402
+ ## License
403
+
404
+ [MIT](LICENSE)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "symbiote-cli",
3
- "version": "0.1.0",
3
+ "version": "0.1.1",
4
4
  "description": "Symbiote bonds with your AI tools — giving them memory, context, and your coding DNA.",
5
5
  "type": "module",
6
6
  "imports": {
@@ -43,7 +43,7 @@
43
43
  "test": "vitest run",
44
44
  "test:watch": "vitest",
45
45
  "type-check": "tsc --noEmit",
46
- "prepublishOnly": "npm run build"
46
+ "prepublishOnly": "cp ../../README.md . && npm run build"
47
47
  },
48
48
  "dependencies": {
49
49
  "@clack/prompts": "^0.10.0",