Code with the SynapseX terminal agent

This page gets the SynapseX AI agent working on your code. At the end you will have run it two ways — interactively inside a project, and as a single non-interactive command you can drop into a script or a CI job — and you will know how to pick a model, attach files and resume yesterday’s session.

Start the agent in your project

synapsex-code

Run with no arguments, the CLI opens its interactive terminal agent in the current directory. To open it somewhere else, pass the path:

synapsex-code ~/work/my-service

Run one turn non-interactively

For scripts, git hooks and CI, use run:

synapsex-code run "summarise what changed in src/ and flag anything risky"

Add --format json when something else has to read the output. Each line is a self-contained JSON object carrying at least type, timestamp and sessionID, plus that event’s own data:

synapsex-code run --format json "list the exported functions in src/index.ts"

Choose a model

synapsex-code run -m synapsex/synapsex-atlas-7b-v1 "explain this repo in three bullets"

Get the exact ids from the CLI itself rather than copying them from anywhere else — they are printed with the synapsex/ prefix that -m expects:

synapsex-code models

-m / --model works on both run and the interactive command.

Continue, fork and name sessions

# Pick up where you left off
synapsex-code run -c "now write the tests for that function"
 
# Branch off an old session without disturbing it
synapsex-code run -s SESSION_ID --fork "try the other approach instead"
 
# Ask about specific files
synapsex-code run -f src/auth.ts -f src/session.ts "do these two agree on token expiry?"

To list session ids, see Sessions, usage stats and portability.

Use a custom agent

The CLI ships with a built-in agent. List what is available, including its permission set:

synapsex-code agent list

build (primary)

Define your own:

synapsex-code agent create

agent create accepts --description, --mode (all, primary or subagent), --permissions, --model and --path. Once created, select it on any run:

synapsex-code run --agent my-reviewer "review the diff on this branch"

A copy-pasteable CI step

This runs one turn, keeps the machine-readable event stream, and fails the job if the turn did not complete.

#!/usr/bin/env bash
set -euo pipefail
 
export SYNAPSEX_API_KEY="$SYNAPSEX_API_KEY"   # provided by your CI secret store
 
synapsex-code run --format json \
  -m synapsex/synapsex-atlas-7b-v1 \
  --title "ci-review" \
  "review the staged changes and list any correctness risks" \
  | tee review-events.jsonl \
  | jq -c '{type, sessionID}'
 
echo "agent turn completed"

A non-zero exit status from synapsex-code run means the turn did not complete successfully — treat it as a failed step and read review-events.jsonl for the event that came last.

SYNAPSEX_API_KEY is the headless alternative to browser sign-in; see Sign the CLI in to your SynapseX account.

About --dangerously-skip-permissions

synapsex-code run --dangerously-skip-permissions "..."

This auto-approves every permission that is not explicitly denied. The CLI’s own help marks it (dangerous!).

Leave it off for normal work: you will be asked before anything consequential runs, which is the point.

Full flag list

Every command and flag: CLI commands.