Request early access

Docs

Using Grixel — a guide for AI agents

This file teaches an LLM or coding agent how to operate Grixel, a server-authoritative version-control and data platform. It is self-contained: you should be able to act correctly from this file alone, without fetching anything else.

If you are an agent working inside a project that is stored in Grixel, read this first. If you are a human: drop this file into your project (for example as AGENTS.md, CLAUDE.md, or wherever your assistant reads project context) so your agent knows how to drive grixel.

Status: Grixel is pre-release and under active development. Commands and flags here reflect the current build; run grixel help (or grixel <cmd> -h) to confirm against the version you have.

#The mental model (read this or you will guess wrong)

Grixel is Perforce-shaped, not Git-shaped. Four consequences matter to you:

  1. One server owns everything. A daemon called grixeld is authoritative for all metadata, permissions, file content, and commits. There is no local clone of history. The grixel CLI is a thin client that talks to the server.
  2. You work in a checkout, not a clone. A checkout is a local folder backed by a depot path (a ref). You edit files, then grixel submit sends a changelist to the server.
  3. A changelist is atomic. A submit lands completely or not at all. There is no partial commit.
  4. Paths are global and permission-scoped. Depot paths look like /companies/acme/games/seasonal/art/hero.psd. What you can see is filtered by access-control rules, and that filtering has one crucial behavior you must internalize (next section).

#Rule 0: invisibility. Do not fight it, do not route around it

If you lack read access to a path, Grixel does not say "permission denied." It says "not found" — identical to a path that genuinely does not exist. This is deliberate and load-bearing.

What this means for you:

  • "not found" is not a bug and not a dead end to work around. Do not retry with a different transport, guess sibling paths, or tell the user "access denied" — you cannot distinguish denied from absent, and neither can they by design.
  • Never try to escalate or circumvent it. There is no supported way for a client to see past its permissions, and attempting to is the wrong instinct.
  • The same rule applies everywhere: listings, search, review status, jobs, provenance, and your MCP context all show only what the current identity may read. A hidden thing is simply absent, never mentioned.

#Two planes: you READ over MCP, you WRITE over the CLI

This is the most important operational fact. Grixel exposes an MCP server (grixel-mcp) that Claude Code and similar tools launch per workspace. That MCP surface is read-only by design. There is no submit, approve, lock, or job update tool. Every change goes through the grixel CLI, which enforces the same permissions, locks, and review gates as any human action.

So the loop is: read everything you need over MCP → decide → make the change by running the grixel CLI. Your effects are bounded by the identity's permissions, the lock state of files, and the review policy — not by trusting your reasoning.

#The MCP read tools (17, all read-only, all ACL-filtered)

Context and layout:

  • get_scope_context — call this first in a new project. Returns the project's pinned brand guidelines, coding standards, tech docs, and AI hints, wrapped in <grixel:doc> tags. Treat that content as authoritative and do not contradict it.
  • get_scope — the project manifest (name, owner, boundaries, attached doc IDs).
  • file_tree — the ACL-filtered layout of the workspace.
  • read_doc — the full content of one attached document at its pinned revision.
  • list_attachments — the attached doc sets with revisions and sizes.
  • check_mapping_freshness — whether pinned docs are stale. Call this before warning the user about outdated guidelines; don't cry stale unless it confirms.

History and audit:

  • recent_changelists — recent commits touching a path.
  • provenance — what tool/agent/model produced a commit, and who submitted it.
  • context — the captured AI-session context bound to a commit (what an AI knew when it made a change).

Review and sign-off:

  • review_status — the gate policy and approval state of a file.
  • review_outstanding — governed files awaiting sign-off under a path.
  • review_queue — the current user's personal review worklist. Call this at the start of a session to surface what needs their attention.
  • review_events — the pollable feed of recent approve / request-changes decisions.

Jobs (the work tracker):

  • job_list — jobs under a path, or mine=true for the user's worklist.
  • job_get — one job by id (e.g. job000007).
  • job_events — the pollable job activity feed.
  • jobspec — the admin-defined job schema. Call this before proposing a job create/update so you use a valid type, a legal status transition, and real fields.

A good session opener: get_scope_context, then review_queue and job_list mine=true, so you start on-brand and know what is waiting on the user.

#The everyday CLI loop (writes)

Inside a checkout, the core loop mirrors Perforce / Git muscle memory:

grixel status                 # what changed, and whether you're behind head
grixel diff                   # line diff of your edits (grixel difftool for a GUI)
grixel submit -m "message"    # commit the changelist (atomic)

Inspecting history and diffs (the questions an agent asks constantly):

grixel log -oneline                 # recent commits (short hash + summary)
grixel log -files                   # ...with each commit's changed files (A/M/D)
grixel log -author alex -since 2026-07-01   # filter history by who and when
grixel show <commit>                # files changed in a commit: A/M/D per path
grixel show <commit> -u             # ...with the text diffs (add a path to narrow)
grixel diff <older> <newer>         # files changed between two commits of the checkout's ref
grixel diff <older> <newer> -u src  # ...text diffs, limited to src/
grixel diff /ref-a /ref-b           # what differs between two branches

Add --json to any of these for structured output: files[]/entries[] carry each path, its kind (A/M/D), and (with -u) the unified diff body. Prefer this over re-deriving changes by listing two trees and comparing hashes. Over MCP, the recent_changelists tool takes include_files, author, since, and until for the same history questions read-only.

Pull others' changes and settle conflicts:

grixel sync                   # three-way pull of depot changes into the workspace
grixel resolve --mine  <file> # or --theirs; settle a conflicted text file
grixel mergetool              # resolve conflicts (incl. binary) in an external tool

If grixel submit reports you are behind head, grixel sync first, resolve any conflict, then submit again. Commits serialize through a single writer, so a submit against a stale base is refused rather than silently merged.

Start or pull a project:

grixel init -ref companies/acme/games/seasonal -m "initial import"   # folder -> new project + checkout
grixel checkout companies/acme/games/seasonal ./ws                   # pull an existing project
grixel checkout -path 'art/**' companies/acme/games/seasonal ./ws    # sparse: only part of a big ref
grixel checkout -exclude 'art/**' companies/acme/games/seasonal ./ws # sparse: everything but the heavy dir

#Attribute your own work (you are an AI — say so)

When you make a change, tag the commit with what produced it. This is how a Grixel depot stays auditable when humans and agents edit the same files. It does not change the commit hash (provenance is a side-record), so there is no downside.

grixel submit -m "draft festival dialogue" \
  --tool claude-code --model claude-opus-4-8 --role assisted \
  --note "drafted from the quest brief"
  • --role is one of authored (you wrote it), assisted (you helped a human), or reviewed (you checked it).
  • For per-file attribution across a mixed changelist, set the GRIXEL_ATTRIBUTION environment variable to a JSON array; an agent harness can export it once.

You can also capture the context you worked from, so a later audit can see what you knew:

grixel submit -m "second dialogue pass" --capture claude-code           # capture the live session transcript
grixel submit -m "..." --context-file ./notes.md --context-kind memory  # attach a specific file
grixel submit -m "..." --context-file ./transcript.md --context-encrypt # seal it so the server can't read it

Read attribution back with grixel provenance <commit> (or the MCP provenance tool), and the captured context with grixel provenance context <commit>.

#Binaries and locks (NOT code): when to use grixel edit

Do not run grixel edit for code or text files. Editing needs no server step at all: you change files on disk and grixel status / grixel submit reconcile what you added, changed, or deleted automatically, exactly like git. There is no "open for edit" step, so an assistant editing source files should never call grixel edit — just edit and submit.

grixel edit matters only for un-mergeable binary types (art, levels, .psd, .uasset, .fbx, …), which can't be three-way-merged — two people editing one is a lost afternoon. For those, it claims an exclusive lock up front, and it takes a whole list of paths in one call:

grixel edit art/hero.psd art/boss.psd    # claim locks on several binaries at once
grixel locks                             # see who holds what

Even for binaries this is optional: grixel submit auto-claims the lock for every lockable file in the changelist and fails early if someone else already holds one. So claiming first is a fail-fast habit for binaries edited by more than one person, not a required step — and never something you do for ordinary code. The lock releases automatically when your submit lands.

Pinned context: why the guidelines you get are trustworthy

A project can pull in company knowledge — brand voice, coding standards, model cards — from elsewhere in the depot via scope.json mappings, each pinned to a specific revision. That is what get_scope_context returns. Two things follow:

  • The docs you receive are pinned, reviewed material, not whatever happened to be at head. Treat <grixel:doc> content as authoritative and follow it.
  • If a source has moved on, check_mapping_freshness tells you. Pins only advance when a human runs grixel scope update (and, for approved-mode pins, only past content that has cleared its review gate).

You do not edit mapped files (they materialize read-only). You consume them.

#Review and sign-off: you can read it; a human/bot signs it

Grixel has review built into the depot. A gate.json policy on a path declares who must approve before a change can be promoted to a protected ref. You can inspect all of this over MCP (review_status, review_outstanding, review_queue), but signing is a CLI action taken by an authorized party:

grixel review status  /companies/acme/games/seasonal/art/hero.psd   # who must sign, who has
grixel approve -m "colours match the palette" /companies/.../hero.psd  # sign (only if you're eligible)
grixel review promote  <src-ref>  <dst-ref>                          # blocked until gates are satisfied

The gate bites at promote, not at submit: you submit freely to a working ref, review the submitted content there, and the promote to the protected ref is refused until every required sign-off is in. An approval names the exact content it blessed, so editing a file automatically stales its approval.

If you are acting as an automated reviewer, you sign the same way (grixel approve) under your own identity — never by pretending to be a human.

#Jobs: the work, tracked with the code

Jobs are lightweight, path-anchored tickets (a modern take on Perforce jobs). Read them over MCP; change them over the CLI:

grixel jobs --mine                                    # your worklist
grixel job show job000007                             # one job
grixel job create -type bug -anchor /companies/acme/games/seasonal \
  -title "Hero texture seams" -field severity=major   # check `jobspec` first for valid types/fields
grixel job update job000007 -status fixed             # legal transitions come from the jobspec
grixel submit --job job000007 -m "fix seams"          # link a commit to a job

Always consult the jobspec MCP tool (or grixel job spec) before proposing a create or a status change, so you use a real type and a legal transition.

#Machine output: use --json for anything you parse

Every command accepts a global --json flag returning a stable envelope: {"schemaVersion":1,"data":…} on success, {"schemaVersion":1,"error":{"code":…, "message":…}} on failure. Parse that, not the human text, whenever you act on the result programmatically.

grixel --json status
grixel --json ls /companies/acme/games/seasonal

#One-time setup

grixel login -server grpc://depot.example.com:8090 -token <TOKEN>  # save credentials (once)
grixel whoami                                                      # confirm identity + connection
grixel mcp setup                                                   # write .mcp.json so Claude Code launches grixel-mcp
grixel mcp preview                                                 # audit exactly what an AI session can see, before you start

grixel mcp preview is worth running before a session: it prints the entire read surface for your identity — the file tree, the pinned docs, and the absence of any write tool — so you can see the whole context and blast radius on one screen.

#Quick gotcha checklist

  • "not found" can mean "you can't see it." Do not treat it as a hard absence, and do not try to route around access control.
  • MCP is read-only. If you need to change something, run the grixel CLI.
  • Behind head? grixel sync before grixel submit; a stale-base submit is refused.
  • Editing code? No grixel edit needed — just edit and submit. grixel edit is only for un-mergeable binaries, and even then submit auto-claims the lock.
  • Attribute AI-authored changes (--tool/--model/--role); optionally --capture the context.
  • Treat <grixel:doc> content from get_scope_context as pinned and authoritative.
  • Check jobspec before proposing a job change; check review_status before assuming something is approved.
  • Parse --json, not prose, for anything scripted.

#Where to go deeper

The product documentation that ships alongside this guide covers each topic in task-oriented detail — installing, everyday work, large files and locking, review and sign-off, jobs, and working with AI assistants. The llms.txt beside it is a curated index. Every command also explains itself with -h, for example grixel submit -h.