CLAUDE.md Generation

When you run synapses init, Synapses generates agent configuration files tailored to your project. These files tell Claude Code (and other MCP-compatible agents) how to work with Synapses — what tools to call, when, and in what order.

What Gets Generated

.claude/CLAUDE.md

The primary agent instruction file. Claude Code reads this at the start of every session.

# Project: my-service

## Synapses MCP Integration
This project uses Synapses for code intelligence. Always call `session_init`
at the start of each session.

## Scale: large (530 files, 240 packages)
For a project this size, use Synapses tools (get_context, search)
instead of raw file scanning. Direct grep/glob produces too much noise.

## Session Pattern
1. Call session_init() first — returns pending tasks, scale guidance, working state
2. Use get_context(mode="intent") for task-specific context
3. Call end_session() when done

## Key Patterns
- HTTP handlers in internal/handlers/
- Business logic in internal/service/
- Database access in internal/store/
...

The content is generated from the code graph analysis: project scale, package structure, key patterns, and high-caller functions.

.claude/settings.json

Editor settings including MCP server configuration:

{
  "mcpServers": {
    "synapses": {
      "command": "synapses",
      "args": ["start", "--project", "."],
      "env": {}
    }
  }
}

Hooks

Synapses configures hooks that trigger at specific points in the agent workflow.

SessionStart Hook

Automatically calls session_init when a new Claude Code session begins, so the agent has project context immediately:

{
  "hooks": {
    "SessionStart": [
      {
        "type": "mcp",
        "server": "synapses",
        "tool": "session_init",
        "arguments": {}
      }
    ]
  }
}

PostToolUse: validate(phase=“post”)

After the agent writes code, this hook nudges it to verify the implementation against architectural rules:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "write_file|edit_file",
        "type": "mcp",
        "server": "synapses",
        "tool": "validate",
        "arguments": {
          "phase": "post",
          "file": "{{file_path}}"
        }
      }
    ]
  }
}

The validate(phase="post") tool checks the modified file against active architectural rules and reports violations inline.

Per-Editor Configuration

Claude Code

Files are placed in .claude/:

.claude/
  CLAUDE.md          — agent instructions
  settings.json      — MCP server config + hooks

Cursor

For Cursor, Synapses generates equivalent configuration:

.cursor/
  rules/
    synapses.mdc    — agent instructions in Cursor format

Other MCP Clients

For generic MCP clients, Synapses generates a standard MCP configuration:

{
  "mcpServers": {
    "synapses": {
      "command": "synapses",
      "args": ["start", "--project", "."]
    }
  }
}

Scale-Aware Templates

The generated CLAUDE.md adapts to project size:

Micro (< 20 files):

## Scale: micro
This is a small project. You can read files directly or use Synapses tools —
both work well at this scale.

Small (20-100 files):

## Scale: small
Use Synapses tools for cross-file queries. Direct file reading is fine for
focused changes.

Medium (100-500 files):

## Scale: medium
Prefer Synapses tools (get_context, search) over raw file scanning.
Use get_context(mode="intent") for multi-file changes.

Large (500+ files):

## Scale: large
ALWAYS use Synapses tools instead of Glob/Grep. Direct scanning produces
too much noise at this scale. Use get_context(mode="intent") for task context.

Regenerating Configuration

To regenerate after the project has changed:

synapses init --force

This re-analyzes the codebase and updates CLAUDE.md with current patterns, scale, and structure. Existing customizations in CLAUDE.md are preserved in a ## Custom section if present.

Customizing the Generated Config

You can add a ## Custom section to CLAUDE.md that Synapses will not overwrite on regeneration:

## Custom

### Commit Style
- Use conventional commits (feat:, fix:, refactor:)
- No AI attribution in commits

### Testing
- Always run `make test` after changes
- Integration tests require `docker-compose up`

Everything above ## Custom is managed by Synapses. Everything below it is yours.