Synapse AI

Synapse AI is a terminal-based AI coding assistant designed for pair programming, codebase exploration, and automated code editing inside your workspace.

Built with Python 3.11+, Textual, Rich, and HTTPX.

Features

• Terminal TUI: Beautiful, responsive terminal user interface powered by Textual.
• Multi-Provider Support:
  • Native Anthropic Messages API (claude-3-7-sonnet, claude-3-5-sonnet, etc.)
  • OpenAI-compatible endpoints: OpenAI, Google Gemini, DeepSeek, Groq, Mistral AI, Together AI, Fireworks, Cerebras, SambaNova, Cohere, Perplexity, OpenRouter, Experiential Labs.
• Protected File Editing:
  • Unified diffs previewed before any changes are written.
  • Granular permission control: Allow once, Allow for Session, or Deny.
  • Safe path resolution preventing directory traversal outside the workspace.
• Granular Security Modes:
  • default: Ask confirmation for file edits and shell commands.
  • acceptEdits: Automatically apply file edits; confirm commands.
  • plan: Read-only mode; prevents any file or command execution.
  • bypass: Autonomous mode without interactive confirmation prompts.
• Transparent Execution: Live tool call logs (↳ read_file(...), ✓ completed) in the activity feed.
• Token Streaming: Real-time token streaming from LLM providers (OpenAI-compatible and Anthropic Messages API) directly in the terminal interface.
• Session Persistence: Automatic saving of conversations, with /sessions, /resume, and /export commands.
• Token & Cost Tracking: Built-in /usage and /context reporting.

Installation

From Source (Development)

git clone https://github.com/yourusername/synapse-ai.git
cd synapse-ai

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies in editable mode
pip install -e ".[dev]"

Quick Start

Launch Synapse in your current workspace:

synapse

Or open a specific workspace:

synapse -w /path/to/project

Check version or help:

synapse --version
synapse --help

Configuring API Keys

You can configure API keys in two ways:

1. Via Environment Variables (Recommended)

Synapse automatically detects standard environment variables:

export OPENAI_API_KEY="sk-..."
export ANTHROPIC_API_KEY="sk-ant-..."
export GEMINI_API_KEY="AIza..."
export DEEPSEEK_API_KEY="sk-..."
export GROQ_API_KEY="gsk_..."

2. In the TUI Interface

Type /keys inside the Synapse prompt, pick your provider from the list, enter your API key, and press Enter. Keys are securely stored in your OS keyring (with local fallback).

Commands

Permission Modes

Switch modes at any time with /mode <name>:

/mode plan         # Read-only exploration and architecture planning
/mode acceptEdits  # Fast coding without edit confirmations
/mode default      # Safe mode: confirm edits and commands
/mode bypass       # Full autonomous operation

Running Tests

Run the test suite with pytest:

pytest tests -v

Architecture

synapse/
├── agent/          # Agent loop, system prompt, context compaction
├── app/            # CLI entry point (argparse)
├── core/           # Data models (Message, Role, ToolCall, ChatResponse)
├── providers/      # LLM adapters (OpenAICompatible, Anthropic, Registry)
├── security/       # Permissions, Keyring/Env secrets, Config
├── session/        # Session manager & serialization
├── tools/          # Filesystem, Git, and Shell tools
├── ui/             # Textual TUI interface & Modal screens
└── usage.py        # Token counting, pricing, and context limits

License

MIT