Synapse Agent

中文文档

A self-growing AI agent framework built on a unified shell abstraction, with an interactive REPL, extensible tooling, and a reusable skill system.

Open Source Docs

• Contributing Guide
• Code of Conduct
• Changelog

Highlights

• Unified Shell Abstraction: three tool layers (Native Commands / Agent Shell / Extension Tools), so the LLM mainly learns one Bash-style interface
• Multi-Provider LLM Support: unified LLMProvider interface with built-in Anthropic, OpenAI, and Google adapters — switch providers at runtime without code changes
• Event-Driven Architecture: EventStream async iterable decouples Agent Core from UI, enabling flexible consumption patterns
• Modular Monolith: strict module boundaries enforced by dependency-cruiser fitness functions — core, providers, tools, skills, sub-agents each with clear dependency rules
• Pluggable Operations: FileOperations / BashOperations interfaces allow swapping execution environments (local, remote, sandbox)
• Two-Layer Message System: domain messages preserve full context; explicit convertToLlm() pure-function conversion for LLM API calls
• Interactive REPL: streaming output, tool execution status, and slash commands
• MCP and Skill Extensions: integrate external MCP tools and reusable local skills
• Session Persistence and Resume: manage and restore historical sessions
• Auto Skill Enhancement: distill reusable skills from completed tasks
• Sub-Agents: built-in explore, general, and skill sub-agents with independent EventStream and tool permission isolation

Core Architecture

┌──────────────────────────────────────────────────────────────┐
│                         cli (REPL)                           │
│                     consumes EventStream                     │
├──────────────┬───────────┬───────────────────────────────────┤
│    skills    │   tools   │                                   │
│ loader/gen/  │ BashRouter│                                   │
│ manager      │ 3-Layer   │                                   │
├──────────────┴─────┬─────┴───────────────────────────────────┤
│     core           │ providers                               │
│  Agent Loop        │ Anthropic / OpenAI / Google             │
│  Session/Context   │                                         │
│  Sub-Agents/Hooks  │                                         │
├────────────────────┴─────────────────────────────────────────┤
│                       shared                                  │
│              logger, errors, constants, config                │
├──────────────────────────────────────────────────────────────┤
│                       types                                   │
│         message, tool, events, provider, skill, usage         │
└──────────────────────────────────────────────────────────────┘

Module Dependency Rules

Dependency direction: types ← shared ← core ← providers ← tools ← skills ← cli

Module	Allowed Dependencies	Description
types	(none)	Shared type definitions (message, tool, events, provider)
shared	types	Logger, errors, constants, config, bash-session
core	types, shared	Agent loop, session, context, sub-agents, hooks
providers	types, shared	LLMProvider adapters (Anthropic/OpenAI/Google)
tools	types, shared, core, providers	Three-layer tool system, pluggable operations
skills	types, shared, tools	Skill loading, generation, and management
cli	all modules	Top-level consumer (REPL, terminal renderer)

Install and Setup

Local setup

bun install
cp .env.example .env

Global install (use synapse anywhere)

# 1) Install dependencies
bun install

# 2) Create global link
bun link

# 3) Ensure ~/.bun/bin is in PATH (e.g. ~/.zshrc or ~/.bashrc)
export PATH="$HOME/.bun/bin:$PATH"

# 4) Reload shell config
source ~/.zshrc  # or source ~/.bashrc

If bun link fails with package.json missing "name", run:

echo '{"name": "bun-global"}' > ~/.bun/install/global/package.json

LLM settings

LLM settings are stored in ~/.synapse/settings.json:

{
  "env": {
    "ANTHROPIC_API_KEY": "your_api_key_here",
    "ANTHROPIC_BASE_URL": "https://api.anthropic.com"
  },
  "model": "claude-sonnet-4-5",
  "skillEnhance": {
    "autoEnhance": false,
    "maxEnhanceContextChars": 50000
  }
}

Key	Description
ANTHROPIC_API_KEY	Required API key
ANTHROPIC_BASE_URL	Optional API endpoint
model	Model name (default: claude-sonnet-4-5)
skillEnhance.autoEnhance	Enable/disable auto skill enhancement
skillEnhance.maxEnhanceContextChars	Context size limit for enhancement analysis

Note: Synapse Agent supports multiple LLM providers through a unified LLMProvider interface. Built-in adapters: Anthropic, OpenAI, Google. You can also use Anthropic-compatible endpoints (e.g. MiniMax) via ANTHROPIC_BASE_URL.

MiniMax (Anthropic-compatible)

MiniMax can be used with Synapse Agent through an Anthropic-compatible API surface. In this setup:

• ANTHROPIC_API_KEY: use your MiniMax API key
• ANTHROPIC_BASE_URL: use the MiniMax-compatible endpoint
• model: use a MiniMax model name (the author commonly uses minimax-2.1)

Example:

{
  "env": {
    "ANTHROPIC_API_KEY": "<your-minimax-api-key>",
    "ANTHROPIC_BASE_URL": "https://api.minimaxi.chat/v1"
  },
  "model": "minimax-2.1"
}

References:

• MiniMax API Overview
• Anthropic API Overview

See .env.example for additional optional settings (logging, persistence, enhancement strategy, etc.).

Quick Start

# After global install
synapse chat

# Or from project directory
bun run chat

REPL Commands

Slash commands (/)

Command	Description
/help	Show help
/exit	Exit REPL
/clear	Clear conversation history
/cost	Show token/cost usage for current session
/context	Show context usage stats
/compact	Compact conversation history
/model	Show current model
/tools	List available tools
/resume	Show resumable sessions and choose one
/resume --latest	Resume latest session
/resume <id>	Resume by session ID

Skill commands

Command	Description
/skill:list	List installed skills
/skill:info <name>	Show skill details and versions
/skill:import <src>	Import skills from local directory or URL
/skill:rollback <name> [version]	Roll back a skill version
/skill:delete <name>	Delete a skill and its version history
/skill enhance	Show auto skill enhancement status
/skill enhance --on	Enable auto skill enhancement
/skill enhance --off	Disable auto skill enhancement
/skill enhance -h	Show skill enhancement help

Shell commands (!)

!ls -la
!git status

Tooling Model

Layer 2: Agent Shell

Command	Description
read <file>	Read file (supports offset and line limits)
write <file>	Create/overwrite file
edit <file>	Regex-based text replacement
bash <cmd>	Execute native shell command

For file discovery and content search, prefer native commands such as find, rg, and grep.

Layer 3: Extension Tools

Command	Description
tools search	Search tools (supports --type=mcp|skill)
skill search	Semantic skill search
mcp:*	Invoke MCP tools
skill:*	Invoke skill scripts
task:*	Run sub-agent tasks

Advanced Features

Session persistence and resume

• Session files are stored in ~/.synapse/sessions/ by default
• Session directory can be overridden with SYNAPSE_SESSIONS_DIR
• Use /resume or /resume --latest

Auto skill enhancement

• /skill enhance --on to enable
• /skill enhance --off to disable
• Setting is persisted in ~/.synapse/settings.json (skillEnhance.autoEnhance)

Sub-agents

• explore: repository exploration
• general: general task handling
• skill: skill generation

MCP Configuration

Default lookup paths:

• ./mcp_servers.json
• ~/.synapse/mcp/mcp_servers.json

Example:

{
  "mcpServers": {
    "server-name": {
      "command": "node",
      "args": ["server.js"]
    }
  }
}

Project Structure

├── src/
│   ├── types/               # Shared type definitions (message, tool, events, provider, skill)
│   ├── shared/              # Shared utilities (logger, errors, constants, config, bash-session)
│   ├── core/                # Agent core
│   │   ├── agent/           # Agent loop, runner, step execution
│   │   ├── session/         # Session management and persistence
│   │   ├── context/         # Context management and compaction
│   │   ├── sub-agents/      # Sub-agent lifecycle management
│   │   ├── hooks/           # Hook system (stop hooks, skill enhancement)
│   │   └── prompts/         # System prompt templates
│   ├── providers/           # LLM Provider adapters
│   │   ├── anthropic/
│   │   ├── openai/
│   │   └── google/
│   ├── tools/               # Three-layer tool system
│   │   ├── commands/        # Agent Shell command handlers (read, write, edit, bash, etc.)
│   │   ├── operations/      # Pluggable operations (FileOps/BashOps)
│   │   └── converters/      # MCP/Skill converters
│   ├── skills/              # Skill system
│   │   ├── loader/          # Skill loading and search
│   │   ├── generator/       # Skill generation and enhancement
│   │   ├── manager/         # Skill management (import, versioning, metadata)
│   │   └── schema/          # Skill document parsing and templates
│   ├── cli/                 # REPL and terminal UI
│   │   ├── commands/        # CLI command handlers
│   │   └── renderer/        # Terminal rendering components
│   └── resource/            # Resource files (meta-skill templates)
├── tests/
│   ├── unit/                # Unit tests (mirrors src/ structure)
│   ├── integration/         # Integration tests
│   ├── e2e/                 # End-to-end CLI tests
│   └── fixtures/            # Test fixtures
├── docs/
│   ├── requirements/        # PRD and requirements documents
│   ├── reports/             # Test and delivery reports
│   ├── plans/               # Development plans
│   └── archive/             # Archived documents
├── assets/
│   └── logo.png
├── README.md
├── README.zh-CN.md
├── CLAUDE.md
├── CONTRIBUTING.md
├── CODE_OF_CONDUCT.md
├── LICENSE
└── CHANGELOG.md

Development Commands

bun run lint          # ESLint (Flat Config, strict mode)
bun run typecheck     # TypeScript strict type checking
bun test              # Run all tests
bun test tests/unit/  # Unit tests only
bun test tests/integration/  # Integration tests only
bun run test:arch     # Architecture fitness tests (dependency-cruiser)
bun run test:cov      # Tests with coverage report
bun run test:e2e      # End-to-end tests
bun run validate      # Run all checks (lint + typecheck + tests + arch)

Tech Stack

• Runtime: Bun 1.3.9
• Language: TypeScript (strict mode)
• LLM SDKs: @anthropic-ai/sdk, openai, @google/genai
• MCP: @modelcontextprotocol/sdk
• Validation: Zod
• Logging: pino + pino-pretty
• Terminal UI: Ink + @inkjs/ui
• CLI: Commander.js
• Architecture Testing: dependency-cruiser

Acknowledgements

Inspired by:

• philschmid/mcp-cli
• shareAI-lab/learn-claude-code

Contact

• Email: wuwenjun19930614@gmail.com

License

MIT