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.

#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.