Metadata-Version: 2.5
Name: synap-git
Version: 2.6.0
Summary: Persistent structural context infrastructure for AI coding agents.
Project-URL: Homepage, https://github.com/saahilpal/synapse
Project-URL: Repository, https://github.com/saahilpal/synapse
Project-URL: Issues, https://github.com/saahilpal/synapse/issues
Project-URL: Changelog, https://github.com/saahilpal/synapse/blob/main/CHANGELOG.md
Author: Synap contributors
License: Apache-2.0
License-File: LICENSE.md
Keywords: ai,context,developer-tools,git,mcp,repository-indexing
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Requires-Dist: click==8.1.8
Requires-Dist: fastapi==0.115.11
Requires-Dist: gitpython==3.1.44
Requires-Dist: httpx==0.28.1
Requires-Dist: keyring==25.6.0
Requires-Dist: mcp==1.3.0
Requires-Dist: msgpack==1.1.0
Requires-Dist: packaging>=24.0
Requires-Dist: prompt-toolkit<3.0.44
Requires-Dist: pydantic-settings==2.8.1
Requires-Dist: pydantic==2.10.6
Requires-Dist: questionary==2.1.0
Requires-Dist: rich>=13.7.0
Requires-Dist: structlog==25.1.0
Requires-Dist: tiktoken==0.9.0
Requires-Dist: tree-sitter-languages==1.10.2
Requires-Dist: tree-sitter==0.20.4
Requires-Dist: typer==0.15.1
Requires-Dist: uvicorn==0.34.0
Requires-Dist: watchdog>=6.0.0
Provides-Extra: dev
Requires-Dist: bandit==1.8.3; extra == 'dev'
Requires-Dist: mypy==1.15.0; extra == 'dev'
Requires-Dist: pre-commit==4.1.0; extra == 'dev'
Requires-Dist: pytest-asyncio==0.25.3; extra == 'dev'
Requires-Dist: pytest-cov==6.0.0; extra == 'dev'
Requires-Dist: pytest-timeout==2.3.1; extra == 'dev'
Requires-Dist: pytest==8.3.4; extra == 'dev'
Requires-Dist: ruff==0.9.9; extra == 'dev'
Description-Content-Type: text/markdown

# Synapse

> Fast, local, zero-cost structural context engine for AI coding agents.

[![CI Status](https://github.com/saahilpal/synapse/actions/workflows/ci.yml/badge.svg)](https://github.com/saahilpal/synapse/actions)
[![Version](https://img.shields.io/pypi/v/synap-git?color=3b82f6)](https://pypi.org/project/synap-git/)
[![Python Version](https://img.shields.io/pypi/pyversions/synap-git)](https://pypi.org/project/synap-git/)
[![License](https://img.shields.io/github/license/saahilpal/synapse?color=cbd5e1)](LICENSE.md)

---

## ⚡ 5-Second Quickstart

Install Synapse and automatically configure your IDE (Cursor, Claude Code, Cline, Windsurf):

```bash
pip install synap-git
synap install
```

Done. Synapse indexes your repository with Tree-sitter, installs zero-daemon Git hooks for automatic reindexing, and registers MCP server endpoints.

---

## Why Synapse?

| Feature | Synapse | Repomix | Aider | Cursor / Cline Default |
| :--- | :---: | :---: | :---: | :---: |
| **API Cost** | **100% Free (Zero)** | 100% Free | Burns Tokens | Cloud Token Usage |
| **Graph Intelligence** | **AST Symbol & Edge Graph** | None (Flat Dump) | Repo Map (CTags) | Vector Embeddings |
| **Code Skeletonization** | **85% Token Reduction** | None (Raw Code) | Line Truncation | Chunk Slicing |
| **Git Blast Radius** | **Instant Callers & Tests** | None | Diff Only | None |
| **Architectural Hubs** | **Personalized PageRank** | None | Static Frequency | None |
| **Working Memory** | **Persistent Checkpoints** | None | Ephemeral Chat | Ephemeral Session |
| **Runtime Footprint** | **Zero-Daemon Hook Mode** | CLI Only | CLI Process | Background Indexer |

---

## Architecture

```mermaid
flowchart TD
    A[AI Coding Agent / IDE<br>Cursor · Claude Code · Cline · Aider] -->|MCP stdio / CLI| B[Synapse Engine]
    B --> C[AST Skeletonizer<br>85% Token Reduction]
    B --> D[Git State & Blast Radius<br>Diff Line -> Callers -> Tests]
    B --> E[Graph Engine & PageRank<br>Architectural Hubs]
    B --> F[Working Memory & Lessons<br>Checkpoints & Anti-Regressions]
    C & D & E & F --> G[(Local SQLite WAL DB<br>.synap/synap.db)]
```

For database schemas and CTE traversal queries, see [Architecture Internals](docs/architecture.md).

---

## Essential CLI Commands

```bash
# Print token-bounded startup context (< 750 tokens)
synap context

# Check modified symbols, direct callers, and impacted tests
synap blast

# Run only tests impacted by dirty git blast radius
synap test

# Deep structural symbol inspection (callers, dependencies, tests)
synap explain my_function

# Export token-budgeted prompt pack with AST skeletons (< 8k tokens)
synap pack

# Inspect structural AST skeleton of any file (strips bodies, keeps types/docstrings)
synap skeleton src/my_module.py

# Discover top architectural hubs via PageRank
synap hubs

# Search repository with hybrid structural ranking
synap search "authentication flow"

# Verify environment and system health
synap doctor
```

Shorthand aliases supported: `synap ctx`, `synap blast`, `synap t`, `synap ex <sym>`, `synap sk <file>`, `synap hubs`, `synap doc`.

---

## MCP Tools for AI Agents

When registered via `synap install`, AI agents gain direct access to these MCP tools:

| MCP Tool | Purpose |
| :--- | :--- |
| `get_session_preamble()` | Token-optimized session startup context (< 750 tokens: active branch, dirty files, blast radius, hubs, lessons). |
| `get_skeleton(file_path)` | Extracts function signatures, types, and docstrings without function bodies (85% token savings). |
| `get_blast_radius()` | Computes impact radius of uncommitted git changes down to callers and test files. |
| `get_callers(symbol)` | Finds all functions and modules that call or depend upon a symbol. |
| `get_callees(symbol)` | Finds all functions and symbols called by a given symbol. |
| `read_symbol(symbol)` | Reads exact lines and code of a specific function or class without reading the entire file. |
| `get_diff()` | Unified git diff of uncommitted or staged changes. |
| `get_test_recommendations()` | Discovers impacted test suites and provides recommended `pytest` commands. |
| `create_checkpoint(doing)` | Saves thought process and dirty working state before complex refactors. |
| `restore_checkpoint(id)` | Restores past checkpoint context after agent context compaction or memory wipes. |
| `remember(key, content)` | Stores operational observations and environment facts in persistent memory. |

---

## License

MIT © Saahil Pal
