Quickstart

This guide walks you through initializing Synapses on a project and using it with your AI agent. The whole process takes under five minutes.

Prerequisites: Install SynapsesOS first. The install gives you both the desktop app and the synapses CLI.

Step 1: Initialize Your Project

Navigate to your project directory and run the interactive setup:

cd your-project
synapses init

The init command walks you through:

1. Project scanning — detects languages, frameworks, and project structure
2. Indexing — parses your codebase into a code graph using AST-based parsers
3. Agent connection — detects your editor/agent and writes the appropriate MCP configuration

After initialization, you’ll have a synapses.json config file in your project root and a populated SQLite index.

Step 2: Manual Setup (Alternative)

If you prefer manual control, you can set things up step by step.

Create a Configuration File

Create synapses.json in your project root:

{
  "project": {
    "name": "my-project",
    "path": "."
  }
}

Synapses auto-detects most settings, so a minimal config is usually enough.

Build the Index

synapses index

This parses your codebase and builds the code graph. You’ll see progress output as each file is processed. For a medium-sized project (500-2,000 functions), indexing typically takes a few seconds.

Start the Server

Run Synapses as a foreground process:

synapses start

Or as a background daemon:

synapses daemon

The daemon mode keeps Synapses running and watches for file changes to keep the index current.

Step 3: Connect Your AI Agent

Once the server is running, your AI agent communicates with Synapses via MCP tools. The first thing any agent session should do is call session_init:

Tool: session_init

This single call returns everything the agent needs to get started:

• Project identity — name, scale, language breakdown, key architectural patterns
• Pending tasks — any incomplete tasks from previous sessions
• Working state — recent git changes, modified files, current branch

The session_init response gives the agent immediate situational awareness without needing to scan the filesystem.

Step 4: Retrieve Context

With a session established, agents use these primary tools to get code intelligence:

get_context

Retrieve the structural context around a specific entity:

Tool: get_context
Parameters: { "entity": "UserService.Create" }

This returns the function, its callers, callees, related types, and surrounding structural context — carved from the graph using BFS with a token budget.

You can also pass a file path:

Tool: get_context
Parameters: { "file": "internal/auth/handler.go" }

get_context(mode=“intent”)

For intent-driven context retrieval:

Tool: get_context
Parameters: {
  "mode": "intent",
  "entity": "UserService",
  "intent": "modify"
}

The intent (modify, debug, review, add, plan, understand) adjusts which edges and relationships are prioritized in the context slice.

Step 5: Explore the Codebase

Two tools are essential for navigating unfamiliar code:

search(mode=“exact”)

Look up a specific entity by name:

Tool: search
Parameters: { "mode": "exact", "name": "HandleLogin" }

Returns matching nodes with their type, package, file location, and relationship counts.

search

Full-text and structural search across the graph:

Tool: search
Parameters: { "query": "authentication middleware" }

Returns relevant entities, ranked by structural importance and textual relevance.

What Happens Next

With these tools — session_init, get_context, get_context(mode="intent"), search(mode="exact"), and search — an AI agent can navigate and understand your codebase structurally rather than relying on blind file searches.

As you work, Synapses keeps the index updated via its file watcher. Modified files are re-parsed incrementally, so the graph always reflects your current code.

Common Commands Reference

Next Steps

• Editor Setup — Detailed configuration for Claude Code, Cursor, Windsurf, and Zed
• Core Concepts — Understand the code graph, context carving, and brain tiers