synapse-context-cli 0.1.0

CLI for Synapse — push uncommitted code to the WIP cache so MCP-aware AI tools see your live editor state.

synapse-cli

synapse is the developer CLI for the Synapse Universal Memory Layer. It pushes your uncommitted, work-in-progress code into the Synapse WIP cache so MCP-aware AI tools (Claude Code, Cursor, etc.) get the current state of your editor — not just whatever was on main last night.

Install

pip install synapse-context-cli
# or, from a clone:    pip install -e .

The distribution name on PyPI is synapse-context-cli. The console-script it installs is still synapse — type synapse sync, not synapse-context-cli sync.

Authenticate

Two options. Use device-flow login on developer machines, tokens on CI/headless.

Device-flow login (recommended)

synapse login

Walks the GitHub device-authorization flow against the Synapse GitHub App, exchanges the resulting access token for a Synapse syn_live_* API token, and saves it to ~/.synapse/credentials.json. One-time setup per machine.

Make sure you've installed the Synapse GitHub App on your org first — the device-flow exchange checks org membership.

To log out: synapse logout.

Token mode (CI/headless)

export SYNAPSE_TOKEN=syn_live_...
export SYNAPSE_API_ENDPOINT=https://synapse.abhinavaditya.com   # optional, default

Generate the token from the dashboard at Settings → API Tokens.

Verify

synapse status        # ping /health, show auth state
synapse status -v     # also list live WIP entries with TTL countdown

You should see API Status: Connected.

Usage

One-shot diff sync

synapse sync

Walks git diff (staged + unstaged + untracked, deletes excluded), secret- scans every file, and POSTs the clean ones to /wip/sync. WIP entries live for 4 hours unless re-synced.

Full repo sync (first-time index from CLI)

synapse sync --full

Walks the entire working tree (respecting .gitignore) and syncs every tracked / untracked-not-ignored file. Mirrors the initial-install index that the GitHub App webhook would do — useful for a fresh clone before the webhook fires.

Watch mode (daily driver)

synapse sync --watch

Runs an initial sync, then watches the repo. Saves are debounced 1.5s and filtered against .gitignore and _IGNORED_DIRS (.git, node_modules, build outputs, IDE caches). Stop with Ctrl-C. Tune the debounce window with --debounce 0.8.

Want it to survive reboots? synapse install-service (see below).

Dry-run

synapse sync --dry-run

Shows what would sync (including secret-scan rejections) without uploading. Useful for sanity-checking before wiring up an automated hook.

Pre-commit hook

synapse sync --pre-commit

Scan-only mode: walks staged files, exits non-zero if any contain secrets. Doesn't upload anything (commits go through the GitHub-webhook → Temporal pipeline anyway). Wire into .pre-commit-config.yaml:

- repo: local
  hooks:
    - id: synapse-secret-scan
      name: synapse secret scan
      entry: synapse sync --pre-commit
      language: system
      pass_filenames: false

Background service

synapse install-service          # current dir, default label "dev.synapse.watch"
synapse install-service --repo ~/code/my-project --label dev.synapse.api
synapse uninstall-service --label dev.synapse.api

macOS → drops a launchd plist in ~/Library/LaunchAgents/ and launchctl load. Linux → drops a systemd user unit in ~/.config/systemd/user/ and systemctl --user enable --now. Logs land in /tmp/<label>.log.

Status

synapse status     # auth + /health
synapse status -v  # also list live WIP entries (file, TTL, repo, branch)

How it interacts with MCP

When an MCP client (Claude Code, etc.) queries Synapse, the server merges results from three tiers in priority order:

1. WIP — Redis, scoped to (org, user, repo, file_path), 4h TTL. This is what synapse sync writes. Multiple repos at once is supported — entries don't collide on overlapping paths.
2. Feature — Qdrant, scoped to feature/{branch}, 7-day TTL.
3. Global — Qdrant, scoped to global (= main), no TTL.

Higher tiers win on file_path collisions, so your in-flight edits override whatever's in main.

Troubleshooting

Symptom	Likely cause
Not logged in.	Run synapse login, or export SYNAPSE_TOKEN.
API Status: Unreachable	Wrong endpoint, or token revoked. Check synapse status.
⚠ Secret detected … skipped	Secret scanner found a credential. Remove it; file syncs next time.
Pre-commit failed: N file(s) contain secrets.	Same — but blocking your commit by design.
MCP tool returns stale code	Run synapse sync manually to confirm upload succeeds. Then check synapse status -v to see TTL.
Watcher fires constantly during builds	Build dirs (dist/, target/, .next/) are already skipped, but if your tool writes to a custom output dir, add it to .gitignore — the watcher honours it.

Development

make test               # unit tests (no infra)
make test-integration   # requires SYNAPSE_INTEGRATION=1 + live stack
make benchmark          # KPI: 10-file diff sync < 2s
make lint typecheck     # ruff + mypy --strict
make check              # lint + typecheck + unit