Supported and custom harnesses

Connect a supported coding agent, describe your own with one TOML file, or contribute a connector.

Supported harnesses

A harness is the coding agent you run. Synapse ships connectors for Claude Code (claude), Codex (codex), pi (pi), and Ainz (ainz). Claude Code, Codex, and Ainz connect through MCP. pi uses the synapse-pi extension.

Each connector declares shared guidance and skill locations, connection detection, and launch arguments. Claude Code and pi also have dedicated session integration. A custom descriptor does not acquire those hooks by declaring the same paths.

shell

synapse tool list
synapse tool show codex
synapse connect codex

Create a connector

Install your harness and make its executable available on PATH. From your repository root, run:

shell

synapse tool create mytool

Synapse opens a commented template using VISUAL, then EDITOR, or vi if neither is set. Use an editor executable that waits until you finish editing. Replace the sample paths and arguments with your harness's actual settings. Synapse checks the descriptor before saving it to .synapse/tools/mytool.toml; an invalid draft does not replace the saved file. Validation checks the descriptor structure, not whether your harness accepts its commands.

Use synapse tool create mytool --user to save under the tools/ folder in Synapse's data directory. Run synapse path to locate that directory. A project descriptor overrides a user descriptor with the same name, and a user descriptor overrides a built-in. Use a lowercase name such as mytool; it becomes the filename and the name passed to connection commands.

You can share a project descriptor in your repository. Run the commands here from that repository's root so creation, inspection, and connection use the same project layer. Harness descriptors live in .synapse/tools/; .synapse.yaml configures project credential scopes.

Descriptor example

This example assumes a fictional harness named mytool with an mcp add command and a JSON MCP registry. Adapt it to your harness before connecting.

toml

name = "My Tool"
command = "mytool"

[home]
default = ".mytool"

[paths]
instructions = "{home}/AGENTS.md"
settings = "{home}/settings.json"
integration = "{home}/settings.json"
skills = "{home}/skills"
projectskills = ".mytool/skills"

[connect]
add = ["mcp", "add", "synapse", "--", "{server}", "mcp"]
remove = ["mcp", "remove", "synapse"]

[detect]
format = "json"
at = ["mcpServers", "synapse"]
args = ["mcp"]

[launch]
prompt = ["{prompt}"]

command names the executable. Connection arguments are separate array entries passed to that executable.
home.default is relative to the user's home. Use {configdir}/mytool for the platform configuration directory, or set home.env if the harness supports a home-directory environment override.
{home} in paths refers to that resolved harness directory. projectskills is relative to the project root.
{server} expands to the Synapse executable. The harness must support the registration and removal commands you supply.
detect.format accepts json or toml. detect.at names the key path to the Synapse server entry, whose command and arguments Synapse checks.
Launch slots such as prompt, headless, config, and model are optional. Declare only flags your harness supports. A descriptor with an interactive prompt alone does not establish unattended mesh support.

Use synapse tool show <name> to inspect a built-in example. A harness with a different transport, configuration schema, or lifecycle hook may need a code adapter; a descriptor cannot implement a protocol.

Verify and update

shell

synapse tool show mytool
synapse connect mytool
synapse status
synapse launch mytool --print

Restart the harness. Confirm it exposes Synapse's memory tools, then save and recall a harmless project convention. Inspect its instruction file for the shared guidance pointer. If it supports Agent Skills, test installing a skill with synapse skill install <skill> --tool mytool.

To revise the descriptor, run synapse tool edit mytool, followed by synapse connect mytool --refresh. Add --user to the edit command for a personal descriptor. The show command reports the winning layer, which helps identify a project override.

Test cleanup with synapse disconnect mytool and check that unrelated configuration remains intact. Deleting a descriptor with synapse tool delete mytool does not disconnect the harness; disconnect first if you are removing the integration.

Contribute a harness

PRs for additional harnesses are welcome at wess/synapse. You can use your custom connector while the PR is under review.

Add the tested descriptor to crates/synapsecore/assets/tools/<name>.toml and add its embedded entry to BUILTINS in crates/synapsecore/src/agent/tool.rs.
Include tests for the resolved paths, connection detection, registration and removal. Cover launch arguments and skill installation for the features you declare. The custom-harness integration test in crates/synapsecore/tests/cli.rs demonstrates the full connection lifecycle with a fake executable.
State the harness version and operating systems tested. Check that setup and disconnect preserve unrelated settings and instructions.
Update the README support table and this guide. Document limitations or any adapter code needed for special behavior.

shell

cargo test --locked --manifest-path crates/synapsecore/Cargo.toml
bun run site
bun run sitecheck