Metadata-Version: 2.4
Name: llmdojo
Version: 0.0.7
Summary: Scored tooling katas, habit rules, and pre-baked warm-start sessions for LLM coding agents
Author-email: Jeremy Howard <info@fast.ai>
License: Apache-2.0
Project-URL: Repository, https://github.com/AnswerDotAI/llmdojo
Project-URL: Documentation, https://AnswerDotAI.github.io/llmdojo/
Keywords: nbdev
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastcore>=2.1.10
Requires-Dist: clikernel>=0.2.9
Requires-Dist: pyskills>=0.0.28
Requires-Dist: llmsurgery>=0.0.16
Requires-Dist: aidialog>=0.0.11
Requires-Dist: fastclaude>=0.0.1
Requires-Dist: exhash>=0.4.15
Dynamic: license-file

# llmdojo


<!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->

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](https://github.com/AnswerDotAI/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

``` sh
pip install llmdojo
```

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

``` python
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:

``` sh
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:

``` sh
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:

``` sh
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:

``` sh
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:

``` python
from llmdojo.dojo import dojo_version
```

``` python
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.
