Authoring Kit: Claude Code & Codex

Agentum ships an authoring kit: the complete plugin contract, written to be handed to an AI. Inside the app you never have to think about it — the Improve hand-off drops a fresh copy beside your agent’s source every time it launches a coding session, which is why Claude Code and Codex seem to already know the platform.

This page is for the times that hand-off isn’t in the loop:

• you start claude or codex yourself, in a terminal, on an agent folder;
• you’re scaffolding a brand-new agent from scratch outside Agentum;
• you’re working in a folder that isn’t an installed agent at all — a scratch directory, a git repo where you keep several agents;
• you’re on a machine that doesn’t have Agentum installed, working from a shared bundle.

In all four cases you add the kit yourself, once, and every session in that folder starts with the contract in hand.

The fast way: paste a prompt

You don’t have to do any of the steps below by hand. Export the kit once (Step 1), then paste this into Claude Code or Codex, started in the folder you want set up. It does the rest.

Set this folder up for Agentum agent development.

1. Find the Agentum authoring kit. Look, in order, at:
   ~/Documents/Agentum/authoring-kit
   ~/Documents/Agentum/agents/*/AGENTS.md   (any agent already set up)
   If you cannot find it, stop and tell me to export it from
   Agentum: Settings > Advanced > General > Export authoring kit.

2. Copy the kit into ./.agentum-kit/ (create it). The kit is
   AGENTS.md, ctx.d.ts, manifest.schema.json, agentum-selfcheck.cjs
   and example-plugin/. Do not copy it to the folder root - a
   200KB AGENTS.md at the root becomes an auto-loaded instructions
   file, which is not what it is for.

3. Write BOTH ./CLAUDE.md and ./AGENTS.md as SHORT pointer files
   (Claude Code reads the first, Codex reads the second, neither
   reads the other's). Each should: say this folder is for Agentum
   agents; list the four kit files with one line each; say to search
   AGENTS.md by its "How to read this file" heading table rather
   than reading it end to end; and give the definition of done as
   "run node .agentum-kit/agentum-selfcheck.cjs and fix every mark".
   If either file already exists, add a section instead of
   overwriting it.

4. Write ./jsconfig.json so editors pick up .agentum-kit/ctx.d.ts
   for autocomplete over plain JavaScript.

5. Verify: run node .agentum-kit/agentum-selfcheck.cjs against
   .agentum-kit/example-plugin and show me the result. If node is
   missing, use "$AGENTUM_NODE" or
   "$HOME/Library/Application Support/Agentum/bin/node" - do not
   install Node, Homebrew, nvm, or any package manager.

Then tell me, in two lines, what you created and what to do next.

To set up an existing agent instead, start your assistant in the agent’s own folder (~/Documents/Agentum/agents/<name>/) and add this line to the top of the prompt:

This folder is a live, installed Agentum agent. Do not change its
behaviour - only add the authoring-kit context. Do not touch data/,
state/ or .history/.

To make it machine-wide (every project, not just this folder), paste this instead:

Set up my machine for Agentum agent development, globally.

The Agentum authoring kit is at ~/Documents/Agentum/authoring-kit
(if it isn't, stop and tell me to export it from Agentum:
Settings > Advanced > General > Export authoring kit).

Append a short section - 15 lines at most, absolute paths, and
opening with a condition like "When working on an Agentum agent:"
so it stays inert in unrelated projects - to BOTH of these,
creating them if they don't exist:
  ~/.claude/CLAUDE.md    (Claude Code reads this)
  ~/.codex/AGENTS.md     (Codex reads this)

The section should point at the kit's files by absolute path and
say to search AGENTS.md by heading rather than read it whole.
Never inline or @-import AGENTS.md itself - it is ~200KB and would
load into every session I ever start.

Show me both files afterwards.

The rest of this page is the same thing done by hand, plus the reasoning — worth reading once so you can tell whether your assistant got it right.

What’s in the kit

File	What it is	Size
AGENTS.md	The full plugin-authoring contract — manifest fields, lifecycle, ctx surfaces, panel rules, gotchas.	~4,400 lines
ctx.d.ts	TypeScript declarations for the runtime ctx object. Gives you autocomplete in plain JavaScript.	~2,300 lines
manifest.schema.json	JSON Schema for manifest.json. Validate manifest edits against it.	~1,200 lines
agentum-selfcheck.cjs	Offline checks your assistant runs before claiming a change is done.	—
example-plugin/	A minimal, runnable agent — manifest, index.js, lib/, a store schema, a panel, tests, docs.	—

The one rule: point at the kit, don’t paste it

AGENTS.md is about 200 KB. It is a reference manual, not a preamble — its own opening section tells an LLM “don’t read this file end-to-end” and gives it a table mapping a task to the exact ## heading to search for.

So the thing you add to Claude Code or Codex is a short instructions file that points at the kit, with the kit’s files sitting nearby to be opened on demand. That’s exactly what Agentum’s own hand-off writes. Pasting the whole contract into your always-loaded instructions is the one setup that reliably goes wrong: in Claude Code it burns a large slice of every session’s context before you’ve said anything, and in Codex it gets silently truncated (see Gotchas).

Step 1 — Export the kit

In Agentum: Settings → Advanced → General → Author agents in your editor → Export authoring kit…

Pick a folder and Agentum writes all five items straight into it. A good permanent home:

~/Documents/Agentum/authoring-kit/

Beside the export button is Copy AGENTS.md, which puts the contract on your clipboard — handy for a one-off paste into a web chat, but not what you want for a real editor setup.

Step 2 — Pick a scope

A. One agent (recommended)

Your own agents live in ~/Documents/Agentum/agents/<agent-id>/. Put the kit in a subfolder of the agent, and run your assistant from the agent folder:

cd ~/Documents/Agentum/agents/my-agent
mkdir -p .agentum-kit
cp -R ~/Documents/Agentum/authoring-kit/. .agentum-kit/
claude          # or: codex

Edits here are edits to the live agent — Agentum’s source watcher reloads it about a second after you save, so there’s nothing to click afterwards.

If you’ve ever used the Improve hand-off on this agent, Agentum has already injected AGENTS.md, ctx.d.ts, manifest.schema.json, agentum-selfcheck.cjs, a tailored CLAUDE.md and a jsconfig.json at the agent’s root, and refreshes them on every hand-off. In that case you’re done — skip to Verify it worked.

B. One project folder

If you keep several agents in one directory (a git repo, a scratch workspace), put a single copy of the kit at the top of it and add one instructions file there. Everything below inherits it.

C. Every folder on the machine

Keep exactly one copy of the kit at ~/Documents/Agentum/authoring-kit/ and add a few lines to your personal instructions file, which both tools load in every project:

• Claude Code — ~/.claude/CLAUDE.md
• Codex — ~/.codex/AGENTS.md

Use absolute paths, and open with a condition (“when you’re working on an Agentum agent…”) so the pointer stays inert in unrelated projects.

Step 3 — Write the pointer file

Claude Code reads CLAUDE.md. Codex reads AGENTS.md. Neither reads the other’s file, so if you use both tools, write both — same text, two names.

Create it at the root of whatever folder you chose in Step 2:

# Agentum agent development

This folder is (or contains) an Agentum agent. The plugin contract lives
in `.agentum-kit/`. Read those files on demand — do NOT read `AGENTS.md`
end-to-end (~4,400 lines). Its "How to read this file" table at the top
maps a task to a `##` heading; search for that heading and read only
that section.

- `.agentum-kit/AGENTS.md` — the full authoring contract. Highest-value
  sections: "Anatomy of a mature agent", "Storage and persistence
  (REQUIRED)", "Common gotchas".
- `.agentum-kit/ctx.d.ts` — types for the runtime `ctx` surface.
- `.agentum-kit/manifest.schema.json` — JSON Schema for `manifest.json`.
- `.agentum-kit/example-plugin/` — a minimal runnable agent.

Rules that are easy to get wrong:

- A service called via `ctx.services.<x>` must be listed in
  `manifest.uses`. The `permissions` array is unrelated.
- Everything the agent persists goes through a host surface: `ctx.store`
  for rows, `ctx.pluginConfig` for settings, `ctx.dataDir` for raw files.
  Never write outside `ctx.dataDir` and never open your own database.
- Credentials belong in the agent's `manifest.config`, never hard-coded.
- Don't touch `data/`, `state/` or `.history/` — the host owns those.

## Definition of done

Before saying a change is finished, run the selfcheck from the agent
folder and fix every ✗ it reports:

    node .agentum-kit/agentum-selfcheck.cjs

Agent code is plain CommonJS. There is no `package.json` and no
`npm install` step — shared dependencies come from the Agentum
workspace at runtime.

For the machine-wide setup (Step 2C), swap .agentum-kit/ for the absolute path ~/Documents/Agentum/authoring-kit/ and keep the file to roughly this length — it loads in every project you open.

Step 4 — Turn on autocomplete

Drop a jsconfig.json next to your agent’s manifest.json and your editor will offer completions for ctx.* in plain JavaScript:

{
  "compilerOptions": {
    "allowJs": true,
    "checkJs": false,
    "module": "commonjs",
    "target": "ES2022",
    "moduleResolution": "node",
    "lib": ["ES2022"]
  },
  "include": ["**/*.js", ".agentum-kit/ctx.d.ts"],
  "exclude": ["node_modules", "data", "state", ".history"]
}

(If the kit sits at the agent root rather than in .agentum-kit/, use "ctx.d.ts" instead.)

Verify it worked

Three checks, in increasing strength:

1. The instructions file is in a place the tool looks. In Claude Code, run /memory — your CLAUDE.md should be listed. Codex looks for AGENTS.md at the root of the folder you launched it from, plus ~/.codex/AGENTS.md, and nowhere else — so confirm the file is at one of those two paths.
2. The assistant can reach the contract. Ask something only the kit answers: “What does manifest.uses control, and which section of AGENTS.md documents it?” A correct answer names the uses service-family section. A vague answer means it’s guessing.

3. The selfcheck runs. From the example plugin:

   cd ~/Documents/Agentum/authoring-kit/example-plugin
   node ../agentum-selfcheck.cjs
   

   You should see a list of ticks and a summary line:

   ✓ manifest.json parses with the required fields
   ✓ index.js loads without throwing
   ✓ every ctx.services.* call is declared in manifest.needs / uses / usesOptional (chat, jobs, telegram)
   ✓ store tables referenced in code are all declared in store/schema.js
   ✓ node --test __tests__/ passes
   ✓ control-ui scripts parse and panel.js registers "example-counter"
   ...
   selfcheck: OK (10 checks passed, 1 warning(s)).
   

   Warnings are advice; ✗ marks are the ones to fix.

No Node installed? You already have one

The selfcheck and the agent tests need a node binary, and plenty of Macs don’t have one. Don’t install Homebrew, nvm or a package manager for this — Agentum is an Electron app, so it already contains a complete Node runtime, and it writes a small shim you can use directly:

~/Library/Application Support/Agentum/bin/node

Add that directory to your PATH (append it, so your own Node still wins if you have one):

export PATH="$PATH:$HOME/Library/Application Support/Agentum/bin"

Sessions launched by Agentum’s own hand-off get this automatically, and also expose it as $AGENTUM_NODE — which is why the injected instructions say to run "$AGENTUM_NODE" agentum-selfcheck.cjs if a bare node isn’t found.

Gotchas

• Don’t let the kit’s AGENTS.md become your project instructions file. Codex auto-loads the AGENTS.md at a folder’s root and reads only the first project_doc_max_bytes of it (32 KiB unless you raise it in ~/.codex/config.toml) — so a root-level copy of the 200 KB contract loads as a truncated fragment, with no warning that the rest is missing. Keeping the kit in .agentum-kit/ and writing your own short AGENTS.md at the root avoids this entirely. Claude Code loads CLAUDE.md, not AGENTS.md — which is the other half of why the pointer file has to exist.
• Don’t @-import AGENTS.md into CLAUDE.md. Claude Code inlines imported files into context, so a one-line import quietly becomes 200 KB of preamble in every session. Reference it by path and let the assistant open what it needs.
• Don’t rename the kit files. agentum-selfcheck.cjs and the injected instructions refer to each other by name, and ctx.d.ts is what jsconfig.json points at.
• The kit is context, not agent code. It’s excluded from marketplace publishes and from Share Agent bundles automatically, so it can sit in the agent folder without shipping. Just don’t put it under data/, state/, or store/.
• A hand-off refreshes reference files but respects your edits. Agentum overwrites AGENTS.md, ctx.d.ts, manifest.schema.json and agentum-selfcheck.cjs on every hand-off so they track the current contract — but once you’ve edited the generated CLAUDE.md or jsconfig.json, it leaves them alone.

Two more prompts worth keeping

Once the kit is in place, these two save the most time.

Start a new agent from scratch:

Build me a new Agentum agent in this folder.

What it should do: <describe it in a sentence or two>

Read .agentum-kit/AGENTS.md first - just the sections
"Quick start: minimal agent" and "Storage and persistence
(REQUIRED)", found via its heading table, not the whole file.
Copy .agentum-kit/example-plugin/ as your starting shape.

Rules I care about:
- Anything the agent saves goes through ctx.store, never a file
  you pick yourself and never your own database.
- Never guard messaging me with isReady() - it is permanently
  false, and a guarded send is silent for everyone.
- Credentials go in the manifest's config block, never in code.

Done means: node .agentum-kit/agentum-selfcheck.cjs passes with
no failures. Then tell me what to do to see it running.

Check an agent you already have:

Review this Agentum agent against .agentum-kit/AGENTS.md and tell
me what is wrong with it - do not change anything yet.

Start by running node .agentum-kit/agentum-selfcheck.cjs. Then
check specifically for: sends guarded behind isReady(); anything
written outside ctx.store or ctx.dataDir; credentials in code;
services called but not declared. Give me a short list worst
first, then ask which to fix.

Both assume the kit is at .agentum-kit/. If you put it at the agent root instead, drop that prefix.

Keeping it current

The kit describes the plugin contract of the Agentum version that exported it. When you update the app, re-export and replace your copy — new ctx.services surfaces, new manifest fields and new panel primitives arrive there. A stale kit doesn’t error; it just quietly teaches your assistant last month’s platform.

Sharing an agent with someone else

You don’t need any of the above to hand an agent to a collaborator. An agent’s ⋯ menu → Share Agent writes a single .zip containing the agent’s source plus a fresh kit and a tailored CLAUDE.md, with runtime state and secrets stripped. They unzip it, open the folder in Claude Code or Codex, and everything on this page is already done.

---

Next: the format itself in Authoring Agents, and working patterns in Agent Recipes.