Getting Started

This guide takes a new user from installation to the first governed SPQ Cycle on Claude Code, Codex, or Cursor.

What you will set up

Synaptory has two required components:

1. A host plugin for Claude Code, Codex, or Cursor.
2. The synaptory CLI, shared across hosts and projects on the same laptop.

Runtime federation is optional and comes later. First establish a working SPQ project on one host.

1. Choose a host

Use a single host as the writer for an active governed stage. Sharing the same repository does not create a supported cross-host handoff workflow.

2. Install the CLI and sign in

Install once per laptop:

# macOS / Linux
curl -fsSL https://synaptory.h3t.co/cli/install.sh | bash

# Windows PowerShell
iwr -useb https://synaptory.h3t.co/cli/install.ps1 | iex

Then sign in with your organization identity:

synaptory login
synaptory whoami
synaptory projects list

For a machine without a browser, use synaptory login --device. See Install the CLI for PATH, update, checksum, and keychain details.

3. Install the host plugin

Claude Code

Run these commands inside Claude Code:

/plugin marketplace add https://github.com/h3tech-ai/marketplace
/plugin install synaptory@h3tech-ai

Restart Claude Code or reload the window. For automatic updates, open /plugin, select the h3tech-ai marketplace, and turn Auto-update on.

Verify with:

/synaptory doctor

Codex

Run these commands in a terminal:

codex plugin marketplace add https://github.com/h3tech-ai/marketplace
codex plugin add synaptory@synaptory-dev

Start a new Codex task and invoke $synaptory. On the first project run, Synaptory checks readiness and presents a bootstrap dry-run if the managed profiles or project configuration are missing. Review the planned files, confirm apply, and then start another new task so Codex discovers the nine profiles.

Codex refuses regulated baa_enforced projects on this standard path. Do not interpret a successful install as regulated certification.

Cursor IDE

An organization administrator imports GitHub repository h3tech-ai/marketplace into the Cursor Team marketplace and makes the synaptory plugin available. Install it from the team catalog, then run:

synaptory skills sync --host cursor

Reload Cursor and verify with /synaptory doctor.

Synaptory is not distributed through the public cursor.com marketplace because that marketplace requires open-source packages.

Cursor CLI or CI

The IDE convention ~/.cursor/plugins/local is not loaded by cursor-agent. For a licensed checkout, wire and verify the project MCP before every headless run:

python3 plugin-cursor/scripts/preflight.py --project <project> --write
cd <project>
cursor-agent mcp enable synaptory
python3 plugin-cursor/scripts/preflight.py --project <project>

The final command must print ready: and exit 0. For an explicit plugin path, use agent --plugin-dir ./plugin-cursor.

4. Bind the repository to a project

At the repository root, identify the Control Plane project and select SPQ explicitly:

# .synaptory.yaml
project_id: "my-project"
build_mode: "spq"
engagement_mode: "structured"

tracker:
  backend: "local"

You can ask the host to generate the file:

Initialize this project for governed SPQ delivery.

Review the proposed file before approving it. In particular, confirm project_id, build_mode: spq, repository paths, and tracker configuration.

Why explicit? SPQ is the recommended lifecycle, but the current compatibility default for an omitted build_mode is still Scrum. Explicit configuration prevents a new project from entering the legacy lifecycle.

5. Declare the source region and the trunk

A Cycle declares the repository paths it may address and the one shared branch it integrates into. There are no lanes to define and no parallelism to switch on -- concurrency is a consequence of the path scope each Work Unit declares.

spq:
  source_region:
    - "api/"
    - "web/"
  trunk_ref: "refs/heads/dev"

Overlapping source regions are refused at declaration. That refusal is what lets two Cycles run concurrently without either one inspecting what the other admits.

6. Start the first Cycle

Give Synaptory an outcome, not an instruction to mutate lifecycle files:

Use SPQ to deliver account sign-in with audit logging. Start Discovery and
show me the baseline before Commit.

The normal path is:

1. Discovery frames the outcome, the constraints, the source region and the evidence expectations.
2. Baseline approval is a human gate. It needs a measured calibration sample, not just a sha -- review and explicitly approve or request changes.
3. Commit admits a non-empty set of ready Work Units, each declaring its path scope, and seals the declaration. Nothing joins the Cycle afterwards.
4. The Cycle dispatches the exact next role for each Work Unit and validates its receipt. Disjoint units run concurrently with nothing to enable; intersecting ones run in the order they declared.
5. A cut, if the Cycle cannot finish its admitted set. Explicit reason, backlog return, and a key a later Commit can name. It never moves the baseline.
6. The barrier evaluates the admitted set minus the recorded cuts -- all of it or none -- and integrates the result to the shared trunk.
7. Checkpoint records the demonstration, the verdict, the integrated trunk revision and the cut list, and asks whether to open another Cycle or proceed to Acceptance.
8. Acceptance runs the release roles and stops for the human release decision. Only the final one closes the engagement.

There is no Sync to wait for. Sync records that one Cycle waited on another's published result and how it cleared; it has zero or more occurrences and blocks nothing. What blocks a Work Unit is an unsatisfied dependency, and /synaptory status says which one.

At any boundary, ask:

/synaptory status

On Codex, use $synaptory and ask for status in the same request. Do not run the lifecycle Python modules directly and never edit .synaptory/.orchestrator/pipeline-state.json.

7. Add runtime federation only when needed

The host-native path is enough for the first Cycle. To inspect the runtimes the machine can serve:

synaptory runtimes list
synaptory runtimes doctor

Runtime selection remains inert until an enabled runtimes: policy is present in an SPQ project. The selected delivery role maps to one of four capability profiles, and policy cannot select anything outside allowed_profiles. Capability profiles do not grant authority; the dispatch envelope does.

Read Hosts and Runtimes before enabling it.

8. One shape, and when to open a second Cycle

There is one delivery shape: a Cycle. Open a second concurrent Cycle when the work has its own cadence and a source region that does not overlap the first -- that is the whole condition, and no layer above them composes anything.

• Work that belongs to one increment: one Cycle. Continue with

SPQ Delivery.

• Work with its own cadence and a disjoint region: a second Cycle, with its own

Lead, Crew and Checkpoint. Neither waits for the other.

• Work that cannot be ordered -- a mutually dependent pair -- goes in one

Cycle. It cannot be split across two, and the declaration refuses the split and names the route.

• Existing Scrum, Kanban, or Multi-Spec project: follow

Migrating to SPQ.

Next reading

• SPQ Cycle Model
• SPQ Setup Runbook
• Enforcement
• Configuration Reference
• Troubleshooting

Install the synaptory CLI

The synaptory CLI handles sign-in, session state, governed skill/policy delivery, diagnostics, telemetry, and optional Runtime Bridge operations. Install it once per laptop — the same install works across Claude Code, Codex, Cursor, and every Synaptory project you can access.

The CLI is shipped separately from all host plugins. The download script detects your OS/architecture, verifies SHA-256, and places the binary on your $PATH.

---

macOS / Linux

curl -fsSL https://synaptory.h3t.co/cli/install.sh | bash

That's it. The script:

• Detects darwin-arm64, darwin-amd64, linux-amd64, or linux-arm64.
• Resolves latest.json, then downloads the versioned binary and sha256sums.txt from synaptory.h3t.co/cli/.
• Verifies the SHA-256 before installing.
• Installs to ~/.local/bin/synaptory.
• Tells you the line to add to ~/.zshrc / ~/.bashrc if ~/.local/bin isn't on your $PATH.

After install:

synaptory version           # confirm the CLI is on PATH
synaptory login             # sign in via Entra (browser opens)

The login step prints the projects you can see right after sign-in, so you'll know immediately whether the operator has provisioned you correctly.

Custom install location

Set SYNAPTORY_CLI_PREFIX if ~/.local isn't where you want it:

SYNAPTORY_CLI_PREFIX=$HOME/Tools curl -fsSL .../cli/install.sh | bash
# installs to $HOME/Tools/bin/synaptory

Updating the CLI

Re-run the same one-liner. The script is idempotent and overwrites with the latest version.

Uninstall

rm ~/.local/bin/synaptory
synaptory logout            # if you want the keychain cleared first

---

Windows

iwr -useb https://synaptory.h3t.co/cli/install.ps1 | iex

The script:

• Detects amd64 (the only Windows build we publish).
• Resolves latest.json, then downloads synaptory-windows-amd64.exe and sha256sums.txt from synaptory.h3t.co/cli/.
• Verifies the SHA-256.
• Installs to %USERPROFILE%\bin\synaptory.exe.
• Adds %USERPROFILE%\bin to your user PATH if it isn't already (no admin needed; survives reboot).

If the script added a directory to PATH, open a new PowerShell window so the updated PATH is loaded. Then:

synaptory version
synaptory login

Updating

Re-run the same one-liner.

Uninstall

Remove-Item "$env:USERPROFILE\bin\synaptory.exe"
synaptory logout            # not strictly required; the keychain entry is harmless

---

Commands every user should know

These are the commands you'll run directly. Hooks call the rest for you.

Less common, but good to know

Switching projects

You don't. The same session works across every project you're a member of. The CLI auto-detects which project you're in by walking up from your current directory looking for .synaptory.yaml:

# .synaptory.yaml
project_id: taskflow-pilot

Telemetry and skill fetches stamp that slug onto requests. The server checks your membership against project_members per request — if you've been removed from a project, the next call returns 403 and the CLI quarantines the event for the operator to review.

---

What happens behind the scenes

You won't normally run these operations. Claude Code uses native session hooks; Codex and Cursor obtain the same governance outcomes through their project bootstrap, supported hooks, and MCP integration:

1. The host integration checks CLI/session readiness. If the cached session cannot be refreshed, it stops governed mutation and asks you to sign in.
2. It refreshes the project's governed skill and policy cache.
3. It loads host-native instructions/rules and reads canonical lifecycle state.
4. It flushes durable telemetry when connectivity is available.

If any of those fail, you'll see a clear error message pointing at the fix.

---

Troubleshooting

For anything else, run synaptory status and include the output when you report the issue to ops.