Symapse

Architectural awareness engine for AI coding agents

<p align="center"> <img alt="npm version" src="https://img.shields.io/npm/v/symapse?color=blue"> <img alt="license" src="https://img.shields.io/npm/l/symapse"> <img alt="node" src="https://img.shields.io/node/v/symapse"> </p>

Benchmarks

Same prompt, same codebase. One agent uses Symapse, one reads files directly.

Repo	Language	Symapse	Control	Reduction
Django	Python	57k	310k	−81%
React	JavaScript	40k	80k	−50%
Prettier	JavaScript	49k	90k	−46%
Fzf	Go	38k	68k	−44%
FastAPI	Python	51k	70k	−27%
SQLite	C	44k	44k	0%

Average: 50% token reduction. Plan quality: consistently 4/5 vs 5/5.

<p align="center"><img src="docs/benchmarks.png" alt="Symapse Benchmarks" width="720"></p>

---

Install

npm install -g symapse

Requires Node.js 22+. No dependencies. Zero config.

---

Quick Start

# Index your project
symapse index /path/to/repo

# Start the MCP server (for OpenCode/Cursor/Claude integration)
symapse mcp /path/to/repo

# Query from the terminal
symapse architecture
symapse impact "login"
symapse deadcode 10
symapse where "add notification system"
symapse context "direct login after payment"

---

OpenCode Integration

Install Symapse first:

npm install -g symapse

Add to your project's opencode.json:

{
  "mcp": {
    "symapse": {
      "type": "local",
      "command": ["npx", "symapse", "mcp", "."],
      "enabled": true
    }
  }
}

Create an AGENTS.md in your project root with:

## RULE 1: First action — symapse_clarify

Before ANYTHING else, call `symapse_clarify "<request>"`. If it returns questions, ASK them. Do not guess.

## RULE 2: Always check Symapse before reading files

| Instead of... | Use... |
|---|---|
| Reading files to understand repo | `symapse_architecture` |
| Grepping for symbols | `symapse_search` |
| Tracing callers | `symapse_impact` |
| Guessing where code goes | `symapse_where` |
| Checking for duplicates | `symapse_overlap` |
| Finding dead code | `symapse_deadcode` |
| Finding must-read files | `symapse_context` |

If Symapse doesn't answer your question, read files. But check Symapse first.

---

Tools

Tool	Question it answers
symapse_architecture	Explain this repo
symapse_clarify	What am I assuming?
symapse_search	Where does this thing live?
symapse_impact	What breaks if I change this?
symapse_deadcode	What can I safely delete?
symapse_overlap	Did we build this already?
symapse_where	Where should this new thing go?
symapse_context	Which files must I read?
symapse_conventions	What patterns should I follow?
symapse_changes	What changed?

---

Supported Languages

JavaScript, TypeScript, Python, Go, Rust, C#, PHP, Ruby, Lua, and C.

---

How It Works

1. Index — walks the repo, extracts functions/classes/methods with regex parsers, builds call and import edges
2. Store — normalized SQLite schema, incremental by mtime + engine version
3. Expose — CLI, REST API, and MCP over stdio. All share the same engine.

---

Self-Improving

Symapse learns from agent behavior across sessions without any user involvement:

• Session coherence — biases context toward the subsystem the agent is already exploring
• Usage signals — logs which symbols agents actually drill into
• Workflow memory — auto-detects repeated symbol sequences across sessions
• Intent classification — routes config/docs questions away from source code exploration

---

Architecture

packages/
  engine/   — regex-based parser, call graph, all analysis tools
  db/       — SQLite persistence with incremental indexing
  mcp/      — MCP protocol server (JSON-RPC over stdio)
apps/
  cli/      — command-line entry point
  api/      — HTTP API server + web dashboard
  web/      — terminal-style web UI

---

License

AGPL-3.0