llmdojo

llmdojo helps LLM coding agents use Python tooling through scored practice rounds, worked examples in conversation history, and live checks on kernel cells. It integrates with kernels served by clikernel.

Coding agents often imitate worked examples more reliably than they follow written instructions. A worked round shows the tool calls, their outputs, and a successful result. llmdojo supplies that context in two ways: an agent can complete a short practice round at session start, or start a conversation containing a reviewed round. Live rules continue to check subsequent cells.

The modules provide the following parts of that workflow:

• llmdojo.rules installs checks through clikernel’s inspector hook. Routing rules direct the agent to the intended tools, string-safety rules catch quoting mistakes, and gating rules reject specified dangerous operations.
• llmdojo.dojo runs scored practice exercises, called katas. A successful round issues a completion id that later sessions can present while it remains valid.
• llmdojo.claudedojo captures a successful Claude Code round, supports curating it into a template, and launches conversations that resume the reviewed example.
• llmdojo.codexdojo compiles the same canonical template into native Responses items and prepares or refreshes Codex threads through app-server.
• llmdojo.claudesub starts a headless Claude child with the current conversation’s compacted history and a separate kernel.

Usage

Installation

pip install llmdojo

Register the rules in $XDG_CONFIG_HOME/clikernel/inspectors.py:

from llmdojo.rules import make_inspector, RuleBlock
inspectors = [make_inspector()]

Have clikernel’s startup.py print the bootstrap instructions that tell the agent to run the dojo.

Start a session

dojo_start() starts a scored practice round inside a clikernel session. Pass a valid completion id from a successful round to skip repeating it.

Claude Code and Codex can instead start with a reviewed round already in their conversation history:

claudedojo
codexdojo

Each launcher prepares the conversation and starts its host tool. Configure standing arguments, such as system-prompt files, in the claude_args or codex_args list in $XDG_CONFIG_HOME/claudedojo/config.toml or $XDG_CONFIG_HOME/codexdojo/config.toml. Unrecognized flags pass through to the host; supply values as --flag=value. Use --sid to print the prepared conversation id without launching.

After compaction, -r appends the worked round to the existing conversation. Add -c to compact the conversation offline first:

claudedojo -r
codexdojo -r

Spawn a subagent

From a Claude Code session, claudesub starts a headless child with a directive and only the current conversation’s compacted history. The child has its own kernel. Its text streams to stdout, followed by its session id. Run it as a background Bash call, or under a Monitor to receive progress as events:

claudesub 'directive'
claudesub -r <child-session-id> 'answer'

The second form continues the child’s conversation, retaining its context when answering a question it asked. Use --cwd=<dir> from another project directory. Unrecognized --flag=value arguments pass through to claude.

Update the templates

The package includes the canonical template dialog and the compiled stores for each host. Updating llmdojo installs those templates; users do not need to rebuild them.

For maintainers, dojobuild refreshes outputs after tooling documentation or skills change. It runs the round’s cells in a fresh kernel, updates their outputs in the canonical dialog, and recompiles both host stores in the checkout for review. This replay does not call an LLM:

dojobuild

Changing the round’s cells requires a fresh capture. claudedojo --capture runs the scripted round in a headless Claude session; codexdojo --capture uses a Codex child. With --current, either launcher captures a successful round from an existing session. Review the captured dialog, then use dojobuild --claude and dojobuild --codex to compile it into the host stores without replaying it.

The bootstrap doc() calls before dojo_start() appear in both dojo_data/capture_prompt.md and the canonical template dialog. When changing those calls, update both artifacts. Keep each new doc(x) in its own cell after doc(clik, pysk, edsk), then run dojobuild to generate its output. The capture script and stored demonstration must teach the same bootstrap sequence.

State and templates

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

Renaming a tool does not automatically change the dojo version. Run dojobuild when documentation or receipts shown in the round change. Bump the round revision in dojo.py when every session must repeat the round.

Host detection can select the wrong transcript record when two Claude conversations run in the same project. For Codex, the MCP worker is identified by its parent process id. Compaction clears all numeric documentation records, so another live Codex session can receive extra documentation reminders.