Building with AI agents

Xeer is designed so that a program can drive it as competently as a person: the app's entire shape lives in one declarative file, the API surface is small enough to describe exhaustively, and every failure carries a stable code and a suggested repair.

If you are pairing with an agent, this page is what to give it.

#Zero-config discovery

Every xeer new project includes a concise AGENTS.md, the canonical portable skill under .agents/skills/xeer/, a generated Claude-compatible projection, and a project-confined .mcp.json. Codex and compatible agents can discover the build loop from the checkout without a pasted link or a global install. The MCP command is pinned to the same version as the CLI that wrote the project and sets XEER_MCP_ROOT to ., so tools cannot escape the project.

Add or verify the same files in an existing project with:

xeer agent setup
xeer agent setup --check --json
xeer agent setup --target cursor

--check is non-writing and reports an exact create, update, keep, or conflict plan. Setup updates only files carrying Xeer's generated format and content hash. If any selected path is owned by the user or another tool, the whole write is refused; no partial setup is left behind. Targets are auto, agents, claude, codex, cursor, vscode, and mcp.

#Every command speaks JSON

Start discovery with one bounded read:

xeer agent context . --json

The xeer.agent-context.v0 result contains normalized manifest facts, client/server/shared source zones, operations, current diagnostics, test files, safe next actions, version-matched resource URIs, and a stable content hash. It is deterministic across checkout roots and does not create .xeer/generated.

xeer check --json
xeer build --json
xeer deploy --json

check, build, new, doctor, deploy, promote, rollback, link, env, deployments, and the rest print exactly one envelope:

{
  "protocol": "xeer.command.v0",
  "command": "check",
  "ok": false,
  "diagnostics": [
    {
      "code": "XE1002",
      "severity": "error",
      "message": "…",
      "file": "xeer.app.json",
      "span": { "line": 12, "column": 9, "length": 6 },
      "hint": "…"
    }
  ]
}

dev, preview, and test are long-lived, so they stream newline-delimited xeer.dev.v0 events instead. Wait for preview.ready rather than sleeping. After an edit, the URLs on server.restarted replace the discovery URLs: port-0 automation can move to another free port during a guarded restart, including a rollback. test.case.fail carries a Diagnostic-shaped failure.

#Diagnostics are the interface

interface Diagnostic {
  code: string;                 // XE####, stable
  severity: 'error' | 'warning' | 'info';
  message: string;              // human wording, free to change
  file?: string;                // project-relative POSIX path, never absolute
  span?: { line: number; column: number; length?: number };  // 1-based
  hint?: string;                // suggested edit
  primary?: true;               // this broke the generated contract — repair it first
  causedBy?: string;            // a consequence of that code, not an independent error
}

Dispatch on code, never on message. Codes are stable; wording is not. file and span locate the problem precisely enough to edit without searching, and hint is the platform's own suggestion for closing it.

Repair primary: true first, and leave causedBy alone until it is gone. A failure that invalidates the generated contract — a defineServer the compiler cannot read statically, a duplicate operation name, a handler result the platform cannot encode — makes every type derived from those operations wrong, so the files that consume the contract fill with XE1205 type errors their authors never caused. The compiler marks the failure primary and stamps each consequence with the causedBy code, so the repair is the one edit that broke it rather than the twenty files it poisoned. Such a run also prints its primaries first, so the diagnostic worth reading is the one at the top. Both fields are optional and appear only where the link is established; their absence means nothing was attributed.

Every code is catalogued in the diagnostics reference, generated from the same catalogue the compiler emits from.

xeer doctor --json reports the environment (Node version, platform, resolvable dependencies, generated config, local state) as structured checks — how an agent tells "your code is wrong" from "this machine is not set up".

#The MCP server

@impetik/xeer-mcp exposes the whole loop as Model Context Protocol tools:

// .mcp.json, or your harness's MCP configuration
{
  "mcpServers": {
    "xeer": {
      "command": "npx",
      "args": ["--package=@impetik/xeer-mcp@<XEER_VERSION>", "--", "xeer-mcp"],
      "env": { "XEER_MCP_ROOT": "." }
    }
  }
}

xeer agent setup --target mcp substitutes the installed CLI's exact version for <XEER_VERSION>; the placeholder is shown here so this page cannot become a stale compatibility pin.

Resource-capable clients can read xeer://project/context, xeer://project/manifest, xeer://project/operations, xeer://project/tests, and xeer://docs/index. Markdown pages are loaded on demand through xeer://docs/{+path}, and diagnostics through xeer://diagnostics/{code}. Clients without resource support use the equivalent xeer_agent_context and xeer_docs_search tools.

That configuration starts the safe author profile. xeer_deploy_preview always passes the preview environment, even if a caller invents another input, and the server registers no production-changing tool. Only a human-controlled server configuration can add "XEER_MCP_PROFILE": "operator"; that profile exposes xeer_promote, which requires an exact review receiptId. No tool argument can elevate the profile, and MCP has no artifact-id or current-preview bypass.

The registry-generated table is the complete MCP tool and exclusion surface:

MCP tools (15 total; 14 author, 15 operator). Inputs ending in ? are optional.

CLI actions intentionally excluded from MCP (36).

Every tool returns { protocol: "xeer.mcp-result.v0", action, ok, result?, error? } as both structured content and a JSON text block. Command tools preserve the CLI's xeer.command.v0 envelope at result.envelope; host argv, raw stderr, and absolute directories are omitted. When the CLI crashes without printing an envelope the server synthesizes XE0000. Tool-level refusals use a stable error.code without becoming MCP transport errors.

XEER_MCP_ROOT is a confinement root: a directory argument that escapes it is refused. For the complete policy surface, xeer actions --json returns xeer.actions.v0: every CLI and MCP action's effects, safety properties, human prerequisites, path policy, and any MCP exclusion reason. Use it instead of inferring approval needs from prose.

#Why dev is three tools

A tool call is request/response; xeer dev is a long-lived stream. So the session is owned by the server and addressed by a sessionId, with the protocol's own sequence number as a resumable cursor:

xeer_dev_start  → { result: { sessionId, cursor, status: 'ready', preview: { url, … }, events } }
   edit a file
xeer_dev_status → { result: { events: [compile.start, compile.diagnostic?, compile.ready?], openDiagnostics } }
xeer_dev_stop   → { result: { status: 'stopped' } }

No event is summarised away — the agent reads the same stream a terminal would show. Repairing diagnostics needs none of this, because xeer_check runs the same compiler; the session exists for when the running app matters.

Always stop a session you started: local state is leased per project, so a leaked session makes the next run fail with XE1812.

#The loop that works

xeer new  →  edit  →  xeer check  →  edit  →  xeer test  →  xeer build  →  xeer deploy
                          ↑___________|          ↑____________|

Two things make this reliable rather than hopeful:

• xeer check is fast and complete. It validates the manifest and analyses both source graphs without running anything, so the edit-check loop is tight and every failure is located.
• xeer test proves behaviour, not compilation. An agent that only checks has proved the code parses. An agent that tests has proved the app does what the tests say — including who is allowed to do what, because tests run as three different users.

The step most worth insisting on is the second one. Xeer ships a test runner precisely so that "it compiles" is never mistaken for "it works", and an agent with no human reviewing every diff needs that distinction more than a person does.

#Why the framework's shape helps

• One declarative manifest. An agent can read what an app is — its tables, its indexes, its capabilities — without inferring it from code. And it can change what an app is by editing one file, which the compiler then validates.
• Deny by default. ctx has three properties. There is no ambient resource an agent can reach for by accident, and no credential lying around to misuse.
• A closed, small API. Seven database methods, six input types, four matchers. It fits in a context window, which means an agent is choosing between options it can actually enumerate rather than guessing at an API surface.
• Authorization in the data layer. A table policy holds for every read and write of that table, so a handler an agent wrote cannot leak rows by forgetting a filter.
• Content-addressed builds. The same source produces the same artifact id, and promote and rollback act on that id — so "ship exactly what was reviewed" is mechanical rather than a matter of trust.

#These docs, as plain text

This site is not the only form the documentation comes in. Every page is also served as Markdown, so an agent never has to scrape HTML to read it:

The diagnostics reference in there is generated from the compiler's own catalogue, so the codes an agent reads cannot drift from the codes the platform emits.

/docs.json is the compact, versioned registry: every page's title, description, headings, Markdown URL, canonical URL, framework compatibility range, and SHA-256 content hash. The website, per-page Markdown, llms.txt, installed offline bundle, search, and MCP resources all derive from one page registry.

#Provider-specific projections

The repository keeps its canonical portable skill under .agents/skills/xeer/ and generates provider projections, including the generated diagnostics catalogue. Use xeer agent setup --target claude for the Claude-compatible project files; use the corresponding codex, cursor, or vscode target for those harnesses. The generated copies carry their source hash and should not be edited independently.

#Next

• Diagnostics reference — every code, what it means, how to repair it.
• CLI reference — every command and its --json shape.
• Testing — the step to insist on.