Synapse.cpp

A lightweight, config-driven multi-agent AI framework built in modern C++. Define specialized agents, equip them with tools, and orchestrate complex workflows -- all from a single JSON config file.

Features

• Multi-Agent Orchestration -- Define multiple specialized agents that collaborate through handoffs and parallel execution
• Config-Driven -- Agents, tools, models, and behavior are all defined in a single config.json
• 8 Built-in Tools -- Filesystem I/O, shell execution, HTTP fetch, math, and agent-to-agent communication
• Persistent Memory -- Agents remember past conversations across sessions
• Provider Agnostic -- Works with any OpenAI-compatible API (Gemini, OpenAI, Ollama, etc.)
• Clean CLI -- Minimal output by default, --verbose for full debug traces

Quick Start

Prerequisites

• C++23 compiler (MSVC 17.5+, GCC 13+, or Clang 17+)
• CMake 3.14+

Build

git clone https://github.com/Mihaix/synapse.cpp.git
cd synapse.cpp
cmake -S . -B build
cmake --build build --config Release

Configure

1. Copy the environment template and add your API key:

cp .env.example .env
# Edit .env and set API_KEY=your_key_here

2. Edit config.json to set your workspace path and customize agents.

Run

cd build
./synapse                                   # Default config
./synapse ../examples/coding_assistant.json  # Use an example config
./synapse --verbose                         # Show internal debug logs
./synapse --new-session                     # Ignore saved memory

Configuration

config.json

{
  "model": "gemma-4-31b-it",
  "base_url": "https://generativelanguage.googleapis.com/v1beta/openai",
  "workspace": "/path/to/workspace",
  "starting_agent": "Athena",
  "agents": {
    "Athena": {
      "system_prompt": "You are a manager agent...",
      "persistent_memory": true,
      "tools": [
        "read_file",
        "write_file",
        "execute_command",
        "handoff:Hephaestus"
      ]
    },
    "Hephaestus": {
      "system_prompt": "You are a code specialist...",
      "tools": ["read_file", "write_file", "execute_command"]
    }
  }
}

Configuration Reference

Field	Required	Description
model	Yes	Default LLM model name for all agents
base_url	No	API endpoint base URL (defaults to Gemini)
workspace	Yes	Absolute path to the agent working directory
starting_agent	Yes	Name of the agent that receives user input
agents	Yes	Object containing agent definitions

Agent Configuration

Field	Required	Description
system_prompt	No	Instructions that define the agent's behavior
model	No	Override the global model for this agent
persistent_memory	No	Save conversation history across sessions (default: false)
tools	No	List of tool identifiers to equip

Available Tools

Tool	Identifier	Description
Read File	read_file	Read file contents from the workspace
Write File	write_file	Create or overwrite files in the workspace
List Directory	list_directory	List files and folders in the workspace
Shell Execution	execute_command	Run shell commands in the workspace directory
HTTP Fetch	http_fetch	Fetch content from a URL via HTTP GET
Calculator	calculator	Evaluate math expressions
Handoff	handoff:<agent>	Delegate a task to another agent and return the result
Parallel Handoff	parallel_handoff:<agent>	Run multiple sub-tasks on cloned agents in parallel

Switching Providers

Change base_url in config.json to point to any OpenAI-compatible API:

{ "model": "gpt-4o",       "base_url": "https://api.openai.com/v1" }
{ "model": "llama3",       "base_url": "http://localhost:11434/v1" }
{ "model": "gemma-4-31b-it", "base_url": "https://generativelanguage.googleapis.com/v1beta/openai" }

Environment Variables

Variable	Required	Description
API_KEY	Yes	Your LLM provider API key
CONFIG_PATH	No	Path to a config file (overridden by CLI argument)

Example Configs

Pre-built configurations for common use cases are available in the examples/ directory:

Config	Agent	Use Case
coding_assistant.json	Hephaestus	Read code, run builds, write fixes
research_agent.json	Hermes	Fetch web content, write reports
devops_bot.json	Apollo	Run commands, manage infrastructure

./synapse examples/coding_assistant.json

CLI Reference

Usage: synapse [options] [config_path]

Options:
  --help, -h       Show help message
  --new-session    Ignore saved memory and start fresh
  --verbose        Show detailed internal logs

Arguments:
  config_path      Path to a JSON config file (default: config.json)

License

MIT