Skip to content

Getting started

SpexCode fits around the agent workflow you already use. Install one command, adopt an existing Git repository, then keep speaking to your agent in plain language. The agent reads the contract it discovers in the repository and drives the detailed spex commands for you.

Install the CLI

SpexCode requires Node 22 and Git. Install the CLI once:

npm install -g spexcode

Adopt a repository

Inside the repository, choose the harnesses that should receive the workflow contract. The choice is explicit:

spex init --harness claude,codex

Use the IDs you actually run; --harness accepts one or more comma-separated harness IDs, and an existing harnesses setting also satisfies the requirement. init is additive: it seeds the starter .spec/ data, writes spexcode.json, installs per-clone Git hooks, and materializes the generated harness artifacts without overwriting your own prose.

Confirm the adoption before asking an agent to work:

spex doctor
spex spec lint

doctor checks that the contract reaches the selected harnesses. spec lint reports the graph's structural health and the adoption worklist; it is the command to run in CI as well as locally.

Start an ordinary agent

Launch claude or codex in the repository as usual. The materialized CLAUDE.md or AGENTS.md tells it where to find the governing spec, the manual, and the required review flow. You can now say things such as:

  • "Adopt SpexCode here and extract specs for src/auth."
  • "Change the session expiry policy; update the spec and the implementation together."
  • "Run spex spec lint, resolve the blocking errors, and explain the remaining warnings."
  • "Measure this bug through the product, file the failing eval, fix it, then file the matching pass."

You review the resulting diff and merge proposal, not a transcript of shell commands.

What the files mean

The tracked data is deliberately small:

  • .spec/ holds the spec nodes. A node's spec.md describes present intent and names the code it governs.
  • spexcode.json holds portable project policy such as harness selection, graph roots, and session settings.

The materialized CLAUDE.md, AGENTS.md, .claude/, .codex/, and Git hooks are per-clone derived artifacts. They are visible and removable, but never silently added to the project's tracked files. spex uninstall removes the generated footprint while preserving your spec data and prose.

Add the shared workspace only when you need it

For a single agent, the direct path above is the whole workflow. When several projects or workers need a common view, start the project backend and the host dashboard:

spex serve
spex dashboard

The backend serves this repository; one dashboard discovers and routes to every backend you run on the host. Read Working with your agent before dispatching managed sessions.