Hexum

This page is the activity of a Hexum session: what you put in the repo, what the agent calls, what comes back, what you review. It does not describe how Hexum compresses or checks internally.

Hexum is MCP for coding agents. You keep Cursor, Claude, Antigravity, or any client that speaks MCP. You keep Git. Create a hexum_live_ key at /app, paste a snippet, and the agent discovers tools from tools/list.

What Hexum does

Agents dump the repository into the model, then ship a patch that crosses a layer you did not want crossed. Hexum sits on that path. Two jobs every turn; a third if you opt in.

1. Context. The model is sent this turn, not the whole tree. The agent calls hexum_shrink before it reads widely. When it needs a full function, it calls hexum_expand for that name only. When it writes, it calls hexum_splice on one symbol or one line.
2. Check. Before you trust the turn, the agent calls hexum_check. Hexum maps files to layers in architecture.hexum and reports forbidden imports. That check does not call a model.
3. Reply shape (optional). A skill line in architecture.hexum tells the agent to answer in Hexum (cause / fix / do / check). MCP returns a SKILL.md. The agent writes that file into its skills folder if it is missing.

You still review the diff. Hexum does not merge, commit, or push.

A session

First time you wire Hexum into a repo, the work is this order.

1. Turn on billing and mint a key

Open /app, sign in, turn usage billing on. Hexum will not serve MCP until that is on. There is no spend cap: usage is metered, not cut off at a dollar limit. Rates are on Pricing.

Create a key. The secret is shown once. It starts with hexum_live_. Store it like any API secret. Revoke it from /app if it leaks. Each person mints their own key; on a team, they still do — the invoice is shared, the secret is not.

2. Paste MCP into the agent

Cursor, Claude, Antigravity, or any MCP host. Reload MCP if the host requires it. The agent then lists tools.

{
  "mcpServers": {
    "hexum": {
      "serverUrl": "https://hexum.dev/mcp",
      "headers": { "Authorization": "Bearer hexum_live_…" }
    }
  }
}

If the host shows AUTH, the key is missing, invalid, or revoked. If it shows BILLING (HTTP 403), the key is valid but Usage billing is off — or, on a team, Teams billing is off. Turn billing on at /app, then retry. The error message says which of those it is.

3. Put a contract in the repo

Add architecture.hexum at the project root. Commit it. This is what hexum_check reads. The skill line is optional; without it, Hexum still shrinks and checks.

skill full

layer ui
  match src/ui/**
  match src/pages/**

layer services
  match src/services/**

layer data
  match src/data/**

rule no_ui_to_data
  from ui
  cannot use data
  severity high
  message UI must not import data access directly.
  hint Call services instead.

Other filenames Hexum will accept, in order: architecture.hexum, hexum.hexum, .hexum, then the first *.hexum in the root (alphabetical). If none of those exist, hexum_check returns ARCHITECTURE_CONFIG_MISSING — a status, not a crash.

4. Ask for a change as usual

Example: “Stop App.tsx importing from data.” The agent should run this loop. You do not type the tool names unless you want to.

agent

tools/call  hexum_skill
intensity from architecture.hexum

hexum

write  .claude/skills/hexum/SKILL.md
skill  full

agent

tools/call  hexum_shrink
files: src/ui/App.tsx · others this turn

hexum

smaller view of those files
token counts on the call

agent

tools/call  hexum_expand
file_path  src/ui/App.tsx
symbol_name  App

agent

tools/call  hexum_splice
replace the import

agent

tools/call  hexum_check

hexum_check

FAIL  ui → data
rule  no_ui_to_data
hint  call services instead

If check is healthy, the turn is allowed. If drift_detected, the agent uses hint and checks again. You review Git as you always do.

Connect

Every request to POST /mcp needs: Authorization: Bearer hexum_live_…

The agent must discover tools from tools/list — do not hard-code names in a prompt if the host already lists them. Snippet is also on Agents.

architecture.hexum

One file in the repo. Layers group files. Rules say a layer cannot use another. The check walks imports and reports violations. Comments start with #. Blank lines are ignored. Brace form is also accepted (layer ui { … }).

Field	What you are saying
skill	Reply dialect: lite, full, ultra, or off. Optional.
layer	A named group of files.
match	Glob (*, **, ?). Repeatable.
rule	A named forbid.
from	Source layer for that rule.
cannot use	Forbidden target layer. Repeatable. Also cannot_import.
severity	high / error, medium / warning, low.
message	What the agent should show when the rule fires.
hint	Optional fix. Show this next to the violation.

Relative imports inside the workspace are checked. Bare npm packages that do not resolve to a file in the workspace are ignored. Path aliases from tsconfig are a hole in v1 — prefer relative imports in gated layers, or add a match that covers the aliased folder.

Example: src/ui/App.tsx imports ../data/orders while layer ui cannot use data → drift_detected, rule no_ui_to_data. The agent should call services instead, then check again.

Tools

Five tools. The agent calls them; you watch the turn and the diff.

Tool	When	What comes back	What the agent does next
hexum_skill	First Hexum use this session if SKILL.md is missing, or when you change intensity.	Skill file body, write path, whether to also update architecture.hexum.	Write body to path if missing. Follow that file. If write_architecture, write the architecture file too.
hexum_shrink	Before reading a repo or a wide file set.	A smaller view of those files, plus token counts for the call.	Read that view. Do not dump the originals into the prompt.
hexum_expand	When one folded function, class, or method is the thing to patch.	The full source of that symbol.	Edit from that body. Do not expand the whole file “just in case.”
hexum_splice	When applying the patch.	The updated region, still valid source.	Keep the write small: one symbol (symbol_name + new_implementation) or one line (line + new_source). You keep Git.
hexum_check	Before claiming the turn is done.	healthy, drift_detected, or ARCHITECTURE_CONFIG_MISSING, plus violations and optional skill.	On drift, follow hint and check again. On missing config, add architecture.hexum. Do not ship a red check.

hexum_skill

Hosted Hexum cannot see the agent’s disk. The loop is: the agent looks for the skill file; if it is missing (or intensity changed), it calls this tool; it writes what comes back.

Intensity comes from skill lite|full|ultra|off in architecture.hexum, or from the intensity argument if you (or the agent) ask to switch. Passing intensity also upserts that line in the architecture file when MCP returns write_architecture.

agent is optional: claude, cursor, codex, or grok. It only chooses which path to prefer. The agent still writes the file.

Agent	Write path if that folder is the one in use
Claude Code	.claude/skills/hexum/SKILL.md
Cursor	.cursor/skills/hexum/SKILL.md
Codex	.codex/skills/hexum/SKILL.md
Grok	.grok/skills/hexum/SKILL.md

You do not copy SKILL.md by hand. Connect MCP, set skill full, let the agent call the tool. Dialect, modes, and examples: Skill.

hexum_shrink

Pass the files this turn needs: files as {path, content} blobs, and/or paths. Optional: user_prompt, active_file, stderr (so errors stay in view), max_token_budget.

What you get back is what the model should read: signatures and structure kept, bulk folded. Token counts come back on the call so /app can show usage. If a skill line is on and SKILL.md is not installed, the tool description tells the agent to call hexum_skill first.

hexum_expand

Arguments: file_path (relative workspace path), symbol_name (exact function, class, or method name). Returns that symbol’s full source. Call this only for the symbol you are about to change.

hexum_splice

Small write. Required: file_path. Then either:

• symbol_name + new_implementation — replace that function or class, including its signature.
• line (and optional column, node_kind) + new_source — replace the node at that line.

The workspace file is what Git sees. Hexum is not a second copy of the repo.

hexum_check

Pass the same files you care about, or workspace when the agent is reading from disk. Result:

Field	Meaning
status	healthy · drift_detected · ARCHITECTURE_CONFIG_MISSING
files_scanned	Source files examined.
rules_checked	Rules in the contract.
violations_count	How many hits.
violations[]	severity, rule, file, message, hint, line, target_layer, target_file.
skill	Present when architecture.hexum has a skill line. If the skill file is missing, call hexum_skill.

What you see in /app

Every tools/call records:

Field	Meaning
Tokens in	Estimated tokens of the request.
Tokens out	Estimated tokens of the response.
Calls	+1 per tool call.
Saved	Tokens in minus tokens out, when that is positive.

Stripe is billed on tokens saved. Calls that do not save tokens still increment calls and the in/out counters. There is no monthly cap on MCP. Cache hits are not billed as saved usage. Keys, usage, team, and account are one card at a time in /app.

Teams

Shared invoice, email invites, pooled usage. Each member mints their own MCP key. No per-seat fee. Cap 25 members. Early-access rates €0.55 / €0.45 / €0.35 per million saved (Usage stays €0.50 / €0.40 / €0.30). Full bands: Pricing.

Honest numbers

• Input. Measured context cuts on MBPP (~85%) and HumanEval (~89%) are from hexum_shrink, same tests passing. That is what the model was sent, not a provider invoice. Method: Benchmarks.
• Output. The skill makes replies shorter. No output-token study is published. Loading SKILL.md costs input tokens.
• Whole session. Savings depend on how often the agent would have dumped the repo. Already-tiny prompts can save little.

What Hexum is not

• Not an IDE. Not a customer CLI. Not a model.
• Not a store of your repo. Zero Data Retention is on Usage and Teams. Policy: ZDR.
• Not a spend cap. Billing is usage, not a hard stop.
• Not a writer of files on your laptop by itself. Hosted MCP returns text. The agent writes SKILL.md and patches in the workspace.
• Commits, PRs, comments, and docs other humans read stay normal English, even when the skill is on.

Get API key Skill