A complete walkthrough — from nothing to a working project with an AI assistant pointed at it. The example is a solo game project on one machine (the case that exercises the most of Grixel: big files, locking, an assistant). Adaptation notes call out what to change for a different stack or a team.
You'll run your own server here. If someone already runs one for you, skip to step 3 and use the address and token they gave you.
#The shape
Account and access setup are offline commands (the server must be stopped), so the order is: set up your user and access → start the server → log in → import your project → work → wire in the assistant.
#1. One-time setup (server stopped)
Pick any namespace name for your work — this example uses
mystudio. Create your user, mint a token, and grant
yourself access in two commands:
DATA=~/grixel-data
# creates the data root, your user + token, and grants you read+write on /mystudio
grixeld user add -data-root $DATA -name me -grant /mystudio
# also give yourself admin on it (for locks and review sign-off)
grixeld acl grant -data-root $DATA me admin /mystudiouser add prints a token once — copy it
now; you'll need it in step 3.
Adapt: onboarding a teammate later is one command —
grixeld user add -data-root ~/grixel-data -name teammate -grant /mystudio.
#2. Start the server
grixeld serve -data-root ~/grixel-dataIt prints a banner with the exact command clients use to connect. Leave it running and open a new terminal for the rest.
Adapt (team): to let other machines connect, bind a reachable address and turn on TLS — see Hosting and backup. For solo on one machine the defaults (localhost, no TLS) are right.
#3. Log in
grixel login -server grpc://127.0.0.1:8090 -token <TOKEN>
grixel whoami # -> me (remote: grpc://127.0.0.1:8090)After this, every command uses your saved login automatically.
#4. Import your project
grixel init publishes the folder's files and turns it
into your working copy. Add ignore presets for your stack so build
artifacts never upload — combine them with commas. If your project is a
git checkout, add git so its .git/ history
doesn't get imported:
cd ~/path/to/mygame
grixel init -ref mystudio/games/mygame -m "initial import" -ignore godot,macos,gitPreview before you commit to it. A first import can
be thousands of files — check exactly what would go up (and catch any
folder you forgot to ignore) with the -n dry run, which
uploads nothing:
grixel init -ref mystudio/games/mygame -m "initial import" -ignore godot,macos,git -n
# Dry run — 312 file(s), 240 MiB would be submitted (with the godot+macos+git preset applied):
# art/ 180 file(s) 210 MiB
# scenes/ 44 file(s) 18 MiB
# ...
# Nothing was submitted. Add anything unwanted to .grixelignore and re-run — or drop -n to submit.It groups by top-level folder, largest first, so a stray
.git/, node_modules/, or build output is
obvious. To eyeball individual files instead of the folder summary, add
-v — it lists every file with its size (pipe it to a pager
or grep for a big import). Adjust the ignores, re-run to
re-check, then run the same command without
-n to actually import. Swap godot for
unity/unreal and add
xcode/vscode if you use them;
grixel ignore init lists all presets.
If a .grixelignore already exists, -ignore
merges the preset's missing rules into it (keeping your
own edits) rather than replacing it — so adding git on a
later run correctly excludes nested .git/ folders too.
Re-running is safe; nothing is duplicated.
grixel status works in this folder now.
#5. The everyday loop
grixel status # what changed; are you behind head
grixel diff # line diff for text (grixel difftool for a GUI)
grixel submit -m "tune spawn rates" # commit (atomic)
grixel sync # pull others' changes (matters once it's not just you)Binary assets get a lock. Code and text merge cleanly, but art, levels, and audio can't be merged. Claim an un-mergeable file before you open it so no one collides on it:
grixel edit art/characters/hero.psd # exclusive lock; auto-released when you submit
grixel submit -m "block out the hero"You never do this for code — just edit and submit. Even for binaries
submit auto-claims the lock; grixel edit up
front is the safe habit that surfaces a collision at the start instead
of after you've done the work. See Large files and locking.
#6. Point Claude Code at the project
grixel mcp setup # writes .mcp.json so the assistant can read the project (read-only)
grixel mcp preview # shows exactly what the assistant will be able to seeInstall the skill so Claude Code knows how to drive Grixel. The distribution ships a helper that does this for any assistant (Claude Code, Codex, opencode) and prints the connector wiring:
~/grixel-dist/skills/agent-setup.sh --tool claude .
# or, by hand:
mkdir -p .claude/skills && cp -R ~/grixel-dist/skills/claude-code/grixel .claude/skills/grixelThen run claude in the folder. The skill activates on
its own in a Grixel checkout and follows the rules — read over the
connector, change through the CLI, lock binaries first, and tag its own
commits as AI-assisted. grixel mcp preview is worth a look:
it shows the whole surface the assistant gets, and that it has no write
tools. More in Working with AI
assistants.
#7. Grow into it
- Branching — try changes on the side and merge them back: Branching.
- Review and sign-off — require approval before something reaches a protected area: Review and sign-off.
- Jobs — track the work next to the files: Jobs.
- Keep the server running and backed up: Hosting and backup.
#Things worth knowing
- Operator commands need the server stopped.
user add,acl grant, andbackuptake an exclusive lock on the data root, so run them beforeserve(orCtrl-C, run, restart). Client commands run against the live server. - "not found" means "no access", not a bug. If a user
can't see something, grant it:
grixeld acl grant -data-root ~/grixel-data <user> rw /mystudio. - Back up
~/grixel-data— it is your entire depot.