Working with AI assistants

Grixel is built to work with AI coding assistants safely. An assistant can read your project's context — the files, the standards your team has pinned, what's waiting on you — but it can only change things by running the same commands you would, under your permissions. It can never see or do more than you can.

#How it fits together

There are two sides:

• Reading happens over a read-only connection (the grixel-mcp connector). Assistants that support it can pull in your project's layout, pinned guidelines, review queue, and jobs — all filtered to what you're allowed to see. There is no "write" on this side at all.
• Changing happens through the normal grixel commands. When your assistant makes a change, it submits it just like you would — so locks, review gates, and permissions all apply.

That separation is the safety model: an assistant's suggestions are bounded by what you can do, not by trusting the assistant.

#The fastest way: the setup script

The distribution ships a helper that installs the right files for your assistant and prints the exact connector wiring. Run it from the distribution's skills/ folder, pointing at your project:

# from the folder you installed Grixel from
./skills/agent-setup.sh /path/to/your/project

By default it sets up everything (the Claude Code skill and the AGENTS.md other tools read) and prints the MCP wiring for Claude Code, Codex, and opencode. Narrow it with --tool, and fill in your server so the printed hints are copy-paste ready:

./skills/agent-setup.sh --tool codex --mcp-server grpc://depot:8090 ~/games/mygame

--tool takes claude, codex, opencode, agents, or all. Add --docs to also drop the product docs into the project. It only writes local files — it never touches the server or your login.

#Keeping your own notes

agent-setup.sh writes the Grixel guide into AGENTS.md as a managed block between BEGIN GRIXEL AGENT GUIDE / END GRIXEL AGENT GUIDE markers. Re-running it refreshes only that block — anything you add outside the markers (your project's own conventions) is left untouched. So when a new Grixel version ships an updated guide, just re-run the script; you don't have to choose between stale instructions and losing your notes. Put project-specific notes outside the markers. (--force replaces the whole file — reach for it only if you want a clean slate.)

#The read-only connector

However you install the guide, the assistant reads your project over the grixel-mcp connector. Each tool wires MCP differently — this is the one place they diverge:

grixel mcp setup only writes Claude Code's .mcp.json — the other tools need their own MCP config pointed at the same grixel-mcp command (the setup script prints the exact snippet for each). Whichever you use, preview what the assistant will see first:

grixel mcp preview

It prints the whole picture on one screen — the visible file tree, the pinned guideline documents, and the fact that there are no write tools.

#Installing the guide by hand

If you'd rather not use the script:

• Claude Code skill — copy skills/claude-code/grixel into your project's .claude/skills/ folder (so it lands at .claude/skills/grixel/), or into ~/.claude/skills/ for all projects. It activates automatically in a Grixel project.
• AGENTS.md — copy skills/agents/AGENTS.md into your project root. Codex, opencode, and most other tools read it there (rename to CLAUDE.md or a rules file if that's what yours looks for).

The self-contained agent guide explains the same thing in full if you'd rather hand over a single document.

#A safety net for assistants: checkpoints

Assistants edit fast and sometimes wrongly. Checkpoints give them — and you — an undo that actually covers everything, including changes made by scripts the assistant ran, which editor-level undo history misses.

Before risky work, the assistant snapshots your changes:

grixel checkpoint -m "before refactoring the save system"

If the attempt goes wrong, it restores — and restoring is always reversible: Grixel saves the current state first and prints the undo command, so a restore can never lose work. The connector exposes checkpoint tools directly (create, list, diff, restore), each one local-only: they never touch the server. Deleting a checkpoint is deliberately not something an assistant can do over the connector — that stays a human command.

#Parallel assistants: workspaces

Running several assistants at once? Each gets its own disposable workspace — a separate folder with just the files its task needs, assembled from your local cache so the second one costs almost nothing to create:

grixel workspace create --ephemeral <project> -path code/**

If you use Claude Code, one command wires this in as its worktree mechanism:

grixel agent-setup --claude-code-worktrees
grixel agent-setup --check        # verify it took

From then on, parallel sub-agents each work in their own Grixel workspace, and every change they submit is automatically labelled with which assistant made it — attribution included, nothing extra to remember. Workspaces with unfinished work are never deleted automatically; clean ones tidy themselves up.

One more protection: locks are tied to the workspace that claimed them. An assistant submitting from its own workspace can never release a lock you hold from yours — your claim on that Photoshop file survives whatever the assistant does.

#Give assistants their own keys

An assistant should not run on your credential. Mint it one of its own:

grixel token delegate --tool claude-code --lane my-project/code --ttl 8h
grixel token list        # see what you've handed out
grixel token revoke <id> # kill one instantly

The new credential is named after you and the tool, sees only what you can see, writes only inside the lane you name, and expires on its own (the server caps how long it can live). The Claude Code setup does this automatically for each assistant workspace when your depot runs in server mode — scoping the key to just the folders that workspace checked out.

#What your assistant should know

When an assistant works in your project it should:

• Treat pinned guideline documents as authoritative and follow them.
• Read what it needs over the connector, but make every change with grixel.
• Claim a lock before editing a binary file.
• Sign its changes as AI-assisted so the history stays honest.

All of that is covered in the packages above.