Synoptic — the local-first terminal coding agent

Synoptic is a terminal coding agent that runs on your machine: your sessions, settings, provider keys, and tools live here — there are no accounts, no tiers, no cloud sync. See AGENTS.md for the contributor guide.

Install

npm install -g synoptic

Requires Node.js 22+.

synoptic update upgrades in one unit against the static release channel (SYNOPTIC_RELEASES_URL, sessions + settings untouched).

Use

synoptic                        # interactive terminal agent
synoptic -p "explain this repo" # headless single-shot
synoptic --help                 # all options

One run, zero setup beyond provider keys: sign providers in with /login in the TUI and type. Sessions auto-save locally and can be resumed, forked, or exported to HTML — nothing leaves the machine except provider API calls.

Agent modes: build has full tool access, plan is read-only analysis, goal is objective-driven delivery tracked against a durable goal. Switch with /mode [name], cycle with Shift+Tab, start in one with synoptic --agent-mode plan. The current mode shows in the footer.

Autonomous mode: synoptic --yolo (or /yolo on) auto-allows permission asks — deny rules still stand and every auto-approval is logged. Revert anytime with /yolo off or synoptic --no-yolo.

Browser automation

Synoptic can drive your real, logged-in Chrome/Edge browser — for testing UIs, scraping data behind auth, filling forms, taking screenshots, or operating any site you're already signed into.

How it works:

• The browser CLI daemon is bundled with Synoptic and auto-installed on npm install (downloads the correct platform binary from GitHub Releases).
• The Chrome extension is a separate one-time install from the Chrome Web Store.
• Once both are in place, Synoptic registers 12 browser tools automatically.

Install the extension:

1. Go to Chrome Web Store → search "Synoptic Browser"
2. Click the extension icon → confirm it shows "Connected"
3. Ask Synoptic: "Open github.com and tell me what's on the page"

Security: ask-by-default at the permission gate. The agent never sees your cookies directly — it asks the local daemon to perform actions in a separate Agent Window. Tab borrowing requires your explicit approval in the extension popup.

See browser README for full details.

Team daemon

One process per host for local monitoring — and you never start it by hand: the first interactive run attaches or starts it (token minted, jail derived, loopback-bound). Bearer auth, audit log, quotas, live session streaming. Manual operation still uses env:

synoptic-daemon   # needs SYNOPTIC_DAEMON_TOKEN + SYNOPTIC_WORKSPACES in the environment
synoptic daemon status | stop   # escape hatch (ambient otherwise)

| Method | Route | Notes | |---|---|---| | GET | /health | public liveness | | GET | /daemon/status | sessions, quotas, workspace roots | | POST | /sessions {cwd} | cwd must be inside SYNOPTIC_WORKSPACES | | GET | /sessions/:id/events | SSE stream (replay last 200 + live) | | POST | /sessions/:id/prompt {message} | rate-limited per token | | POST | /sessions/:id/steer /follow_up {message} | queue steering (rate-limited) | | POST | /sessions/:id/abort | abort current run | | POST | /sessions/:id/clear_queue | drop queued prompts | | POST | /sessions/:id/compact {customInstructions?} | compact now | | POST | /sessions/:id/fork {entryId} /clone | branch session | | POST | /sessions/:id/switch {sessionPath} | switch backing session | | POST | /sessions/:id/name {name} | rename session | | GET | /sessions/:id/messages ?since= | entries | | GET | /sessions/:id/tree /stats | branch tree / usage stats | | GET/DELETE | /sessions/:id | state / close child |

Security notes: tokens live on the daemon host only (env), never in logs or audit rows (fingerprint prefix only). Extension dialogs auto-cancel (non-interactive runs must never hang on a TTY prompt).

Interfaces

• TUI — the primary interface (synoptic); works fully offline on cached models.
• Headless — synoptic -p "..." (print) and --json (event stream) for scripts and CI.
• Daemon — loopback HTTP + SSE API (table above) for local monitoring.
• Accounts — operator account on synoptic-be (Parse session, same handoff contract as the wallet tenants). synoptic signup creates one (the free personal account is provisioned server-side, uncapped); synoptic login signs in through the browser; synoptic status shows the profile and accounts; synoptic logout revokes the session and removes the local credential. Provider keys stay in the engine auth store on this machine.

License

Proprietary — © Synotech, all rights reserved. Third-party notices: see NOTICE.