llmdojo

LLM coding agents imitate what their context shows far more reliably than what it tells: instructions decay over a session, demonstrations don’t. llmdojo turns that observation into tooling, for kernels served by clikernel:

• llmdojo.rules: session rules, applied live to every kernel cell through clikernel’s inspector hook. Routing rules teach the designed tool for each job, string-safety rules catch quoting mistakes, gating rules block the genuinely dangerous, and the nodoc rule tracks per-conversation doc-state so tooling docs actually get read before first use.
• llmdojo.dojo: a short scored practice round (the katas) an agent completes at session start, so its first real tool calls follow a demonstrated clean pass rather than being produced cold. Clean rounds mint a completion id that later sessions can present instead of replaying.
• llmdojo.claudedojo: capture a clean round from a live Claude Code session, curate it into a deterministic template, and launch new sessions that resume it, so every session opens with the worked round already in context.
• llmdojo.codexdojo: the Codex mirror - the same canonical template compiled to native Responses items, launching and re-warming Codex threads through app-server.

Usage

Installation

$ pip install llmdojo

Activation is two lines of clikernel user config: register the rules in $XDG_CONFIG_HOME/clikernel/inspectors.py (from llmdojo.rules import make_inspector, RuleBlock; inspectors = [make_inspector()]), and have your startup file print the bootstrap instructions that tell the agent to run the dojo.

Start a session

dojo_start() deals a scored practice round inside a clikernel session. Pass the completion id from a clean round to skip replaying it while that receipt remains valid.

Claude Code and Codex can start with a reviewed round already in their history. Each launcher prepares a warm-start conversation and runs its tool on it: standing arguments such as system-prompt files come from the claude_args/codex_args list in $XDG_CONFIG_HOME/claudedojo/config.toml or $XDG_CONFIG_HOME/codexdojo/config.toml, unrecognized flags are forwarded (values in --flag=value form), and --sid prints the prepared id instead of launching:

$ claudedojo
$ codexdojo

After compaction, -r appends the worked round to the existing conversation instead of preparing a fresh one, and -c compacts the conversation offline first:

$ claudedojo -r
$ codexdojo -r

Update the templates

The templates ship inside the package - the canonical dialog plus the compiled per-host stores - so using fresh templates takes no action beyond updating llmdojo. Maintaining them is one command: when tooling docs or skills change, the baked round’s outputs go stale, and dojobuild regenerates them with no model spend - it replays the round’s cells through a fresh kernel, splices the current outputs into the canonical template dialog, and recompiles both stores, all in your checkout for review:

$ dojobuild

Only a change to the round itself - its cells, not their outputs - needs a fresh capture: claudedojo --capture plays a scripted round headlessly, codexdojo --capture does the same in a Codex child, and --current on either stores a clean round an existing session already played. After reviewing a captured dialog, dojobuild --claude and dojobuild --codex compile it into each store without re-replaying.

The bootstrap doc() reads (the cells before dojo_start()) live in two artifacts: dojo_data/capture_prompt.md, the script future captures replay, and the baked round in the canonical dialog itself. To change the set, update both, keeping each new doc(x) as its own cell placed after the doc(clik, pysk, edsk) one, then run dojobuild, which replays the new cell for a true output and recomputes the stored doced list. Updating only one leaves the demonstration and the capture script teaching different bootstraps.

State and templates

Doc-state records which tool documentation the agent has read for a conversation. Closing and resuming restores that record; compaction clears it because the corresponding documentation has left the model’s context. A warm-start template seeds both doc-state and its clean-round completion receipt before the agent resumes.

Completion receipts and templates carry the dojo tooling version. A version change invalidates old receipts and prevents an outdated template from launching. dojo_version() reports the installed version:

from llmdojo.dojo import dojo_version

dojo_version()

'0.0.1:3'

Limitations

A tooling rename does not change the dojo version automatically: run dojobuild whenever documentation or receipts the round shows have changed, and bump the round revision in dojo.py when the round itself must be replayed by every session.

Doc-state host detection has two conservative fallbacks. Two simultaneous Claude conversations in the same project can select the wrong transcript record. Codex’s MCP worker is keyed by parent process id, so compaction clears all numeric records; another live Codex session may receive extra documentation reminders. The reminders are harmless.