Skip to content

Working with your agent

SpexCode is a tool your agent drives. This page explains the two ways an agent reaches it, how it learns to use it without you spelling everything out, and the configuration, artifacts, and modes you steer it with.

Two entry points

1. Your own agent, launched in the repo. You start a plain claude or codex yourself — there is no SpexCode process in that launch. It works because spex init / spex materialize folds the contract into CLAUDE.md (Claude) and AGENTS.md (Codex), which the harness auto-discovers on startup. So the rules — commit-before-declare, the spec-driven flow, where to find the file formats — arrive as ordinary context, with zero extra flags. This is the everyday path.

2. The dashboard. spex serve plus the board give you a place to dispatch worker agents against spec nodes, watch their lifecycle, review their diffs, and merge. The delivery underneath is the same: the dashboard materializes the contract into each worktree and launches the agent plainly. Reach for it when you want parallel workers and a bird's-eye view; use entry point 1 for a single agent at your side.

Either way, the human mostly talks and reviews while the agent runs the spex commands.

How the agent learns the tool: the guide

You do not paste file-format instructions into every prompt. The contract points the agent at spex guide, an on-demand manual it reads when it needs the detail:

  • spex guide — the setup workflow (install → adopt → serve → dashboard) plus configuration.
  • spex guide spec — the spec.md format: frontmatter, body-at-contract-altitude, and the rules lint enforces.
  • spex guide yatsu — the yatsu.md format: how a node's behaviour is measured and the result filed.
  • spex guide config — every spexcode.json / spexcode.local.json key, and the delivery modes below.

The design is deliberate: the prompt stays small and the manual carries the schema, so the agent pulls exactly the detail it needs, when it needs it. The Reference section of this site is that same contract, projected verbatim from SpexCode's own spec tree.

Configuration: two files

  • spexcode.json (committed) — portable, project-shaped policy: the lint budgets and governedRoots, the layout (mainBranch, branchPrefix), the dashboard identity, sessions.maxActive, the defaultLauncher name, and harness selection. Anything a teammate should share.
  • spexcode.local.json (gitignored) — machine-specific values that must never be committed: absolute launcher command paths, and the private mode toggle. It overlays spexcode.json per field.

See config for every key, or spex guide config.

Artifacts: what SpexCode plants

SpexCode is always a guest, and every artifact it plants is stamped, visible, and reversible (footprint):

  • .spec/ — the spec tree itself; the one thing that is data, and is committed.
  • CLAUDE.md / AGENTS.md — the materialized contract block the harness reads (generated, gitignored).
  • .claude/ · .codex/ — the hook shims plus any skills and sub-agents (generated, gitignored).
  • the git hooks — a pre-commit lint check and a commit-message stamp (per-clone, not committed).

spex uninstall removes every generated artifact by its stamp, leaving your .spec data and your own prose untouched.

Modes you steer

  • Harness selection (harnesses in spexcode.json) — which agents materialize delivers into: Claude, Codex, or a self-contained plugin bundle. Default: all native harnesses. See harness-select.
  • Launcher profiles (sessions.launchers) — a named { harness, cmd } a session picks at create time, persisted on the record so a resume reuses the same command and auth (a login wrapper, an API-key launcher, a bespoke script). See launcher-select.
  • Private overlay (private: true) — run SpexCode on a repo you share but don't own with zero trace in its tracked files: the ignore list moves to .git/info/exclude, and any already-tracked CLAUDE.md / AGENTS.md is marked skip-worktree, so git status stays clean and nothing enters shared history. It is reversible and cancels out cleanly with the default mode. See private-overlay.

You switch any of these by editing config and letting the agent re-materialize — or you just tell it, for example: "make this repo private so my team doesn't see SpexCode," or "add a Codex launcher called gpt5 and make it the default."