Working with coding agents

Cell is designed so that a coding agent (Claude Code, Codex, Cursor, CodeBuddy, pi, ...) can use it correctly on the first try: one way to write each thing, structured errors with fixes, machine-readable commands and documentation that matches the installed version. This page is for the people who set agents up; the guide the agents themselves read is AGENTS.md.

What a project gets

cell init writes these files, and npx cell agent sync rewrites the Cell part of them after you upgrade Cell or add a component:

File	For
AGENTS.md	The Cell guide of the installed @celljs/cli version, followed by the guide snippets of installed components. Cell only rewrites the part between <!-- cell:begin --> and <!-- cell:end -->; write project rules outside it
CLAUDE.md	@AGENTS.md, for Claude Code
.agents/skills/cell/SKILL.md	The same guide as an agent skill
.mcp.json	Starts npx cell mcp

Add npx cell agent sync to your upgrade routine, or run it in a postinstall script.

MCP

npx cell mcp is a stdio MCP server for the project. Its tools return the same JSON as the commands:

Tool	Command	Side effects
info	cell info	none
check	cell check	none
config_get	cell config get	none
docs_search	cell docs	none
build	cell build	writes the output directory
deploy_plan	cell deploy --dry-run	writes the output directory; may reach the network

There is deliberately no deploy tool: deploying stays with a person running cell deploy.

// .mcp.json (Claude Code, Cursor, CodeBuddy) or .cursor/mcp.json
{ "mcpServers": { "cell": { "command": "npx", "args": ["cell", "mcp"] } } }

# Codex: ~/.codex/config.toml
[mcp_servers.cell]
command = "npx"
args = ["cell", "mcp"]

While cell dev runs, http://127.0.0.1:<port>/_cell/mcp is a second MCP server (HTTP) for the running application: get_errors, list_routes, list_bindings, get_config, recent_requests and logs. It only accepts requests from the local machine.

Commands agents use

Command	Gives
npx cell check --json	Every type, configuration, decorator and DI problem with code, file, line and hint
npx cell info --json	Preset, components, DI modules, entries, hooks, output state
npx cell config get <key> --why	A merged configuration value and where each layer came from
npx cell docs <words>	Sections of the docs shipped with the installed packages (their READMEs, these guides and the CLI reference)
npx cell build --json, npx cell deploy --dry-run --json	One-line results instead of progress output

Every command accepts --json (one document with schemaVersion on stdout, everything else on stderr), never prompts when not on a terminal, and side-effecting commands have --dry-run. Exit codes: 0 success, 1 failure, 2 usage error.

Errors

Every toolchain and runtime error has a stable code, a message, a one-sentence fix and a docs link:

[CELL_DI_NO_BINDING] No binding for Symbol(Mailer), needed by Signup.mailer (TodoController → Signup → Symbol(Mailer)).
  fix: Bind the identifier in a DI module (@Component(<id>) in a file the module imports), or mark the injection @Optional().
  docs: https://cell.cellbang.com/errors/cell-di-no-binding

The error code list has a page per code. Codes and --json fields stay stable within 4.x.

Documentation for models

The docs site publishes llms.txt (an index of every page) and llms-full.txt (the guides, the CLI reference and the package references in one file) for agents that read the web. Inside a project, cell docs is better: it searches the version you have installed.

Habits that work

• Ask the agent to run npx cell check and the tests after every change; both are fast and their output is made for it.
• Keep project rules in AGENTS.md outside the Cell markers.
• Let the agent use cell deploy --dry-run freely; keep cell deploy itself, and the credentials it needs, for people.