Executable compound practice loop. The terminal-side companion to Lodestone.
cma is the operator's tool for running the compound practice loop on the local machine. It captures failures, surfaces warnings at the moment of action, tracks decisions, and detects recurrence patterns. It is the executable instantiation of the practice defined in Lodestone.
The methodology lives in Lodestone. cma is what running that methodology looks like in a terminal.
cma 1.0 reference implementation. All seven primitives fully functional: cma miss, cma decision, cma reject, cma prevented, cma surface, cma distill (default + --review + --retire), and cma stats (default + --rejections + --preventions + --recurrence + --leaks + --behavior). Action-time injection (Claude Code hook + shell wrapper). Texture preservation on misses. Test suite (98 cases) covers functional paths, edge cases, JSON validity, the leak-detection join, hook integration, and shell wrapper modes.
The full surface is specified in DESIGN.md. Additive features (action-time injection, texture preservation, counterfactual capture, recurrence detection) layer on without changing the locked surface.
Requirements: bash 3.2 or newer (Linux, macOS native, and Windows-WSL all work; the cma binary uses no bash 4+ features so macOS's system /bin/bash is sufficient), and python3 (used only for JSON escaping). No package-manager dependencies.
Clone the repository and add the script to your PATH:
git clone https://github.com/Clarethium/cma.git
ln -s "$(pwd)/cma/cma" ~/.local/bin/cma # or copy to anywhere on PATH
cma init # create the data directory with a READMECapture a failure:
cma miss "fix removed the error message instead of addressing the defect" \
--surface infra --fm <failure-shape>For richer capture (texture preservation), add the situational fields:
cma miss "missed validation in middleware" \
--surface auth --fm <failure-shape> \
--intended "patch only the failing test" \
--corrected "trace upstream defect, fix at root" \
--excerpt-from /tmp/conversation-excerpt.txtThe texture fields (--excerpt, --intended, --corrected) preserve the conditions of the failure so future surfacing can match by situation, not just keywords.
The --fm value is an opaque string from the operator's perspective; cma stores it without interpretation. When using a methodology with a canonical failure-mode catalog (such as Lodestone), tag with the methodology's canonical names so analysis tooling can interpret them. cma is methodology-agnostic; the catalog and its meaning live in the methodology, not in cma.
Captures are written to ~/.cma/ as JSON Lines files (one record per line, append-only). The data directory can be overridden with CMA_DIR=/path/to/data cma .... The full schema, atomicity guarantees, and migration policy are documented in DATA.md.
Run cma --help for the full command surface.
cma surfaces relevant prior captures automatically when an operator (or AI assistant) is about to act. The five-stage architecture (interception, context extraction, query, injection, logging) is documented in ARCHITECTURE.md. Two reference integrations ship in this repository.
Two hooks for Claude Code: a PreToolUse hook for per-action surfacing and a SessionStart hook for session-priming context.
Per-action surfacing (hooks/claude-code-pre-tool-use.sh): when Claude is about to use a tool that touches a file or runs a command, the hook detects surface heuristically from the tool input, queries cma surface, and writes matched captures to stdout. Claude Code injects them as additional context. Silent for non-relevant tools (Read, etc.) and when no captures match.
Session-priming context (hooks/claude-code-session-start.sh): at the start of each session, surfaces recurring failure patterns and active rejections so the assistant has orientation before the first tool call. Configurable via CMA_SESSION_START_SECTIONS (default recurrence,rejections; set to all for recurrence,rejections,behavior).
Install both:
{
"hooks": {
"SessionStart": [
{
"hooks": [
{
"type": "command",
"command": "bash /path/to/cma/hooks/claude-code-session-start.sh"
}
]
}
],
"PreToolUse": [
{
"hooks": [
{
"type": "command",
"command": "bash /path/to/cma/hooks/claude-code-pre-tool-use.sh"
}
]
}
]
}
}Together the two hooks cover both ends of the action-time injection theme: priming context at session start, relevant captures at each action.
hooks/cma-pre is a wrapper for shell environments. Surface detection uses the same heuristics as the Claude Code hook, so behavior is consistent across integrations.
zsh (native preexec). Add to ~/.zshrc:
preexec() { /path/to/cma/hooks/cma-pre --check "$1"; }bash (requires bash-preexec):
source /path/to/bash-preexec.sh
preexec_functions+=("cma_pre_hook")
cma_pre_hook() { /path/to/cma/hooks/cma-pre --check "$1"; }Manual wrapping:
/path/to/cma/hooks/cma-pre git commit -m "fix auth bug"
# Surfaces relevant captures, then runs the commandTriggers fire on commands likely to warrant surfacing: editors (vim, nvim, emacs, code, subl), version control (git), language toolchains (npm, cargo, python, node), and build tools (make, gradle, mvn). Override the trigger list with CMA_PRE_TRIGGERS (space-separated).
Failure isolation: if cma is missing, errors, or times out (default 5 seconds), the wrapped command still runs cleanly. The wrapper never blocks an action on its own failure.
Both integrations log surface events to ~/.cma/surface_events.jsonl. cma stats --leaks later joins these events against subsequent misses to flag failures that occurred despite a relevant warning being surfaced — the validation evidence that the loop closes.
The bash CLI and shell hooks above cover Claude Code and any
shell-environment operator. For operators reaching the loop
through other MCP-compatible AI clients (Claude Desktop, Cursor,
Cline, Continue.dev), the same compound practice loop ships as a
Python MCP server at cma-mcp/. Subprocess wrapper
around this binary; methodology-agnostic substrate; three-section
payload discipline. PyPI publication of cma-mcp is pending;
install from source until then (see cma-mcp/README.md).
See cma-mcp/README.md for the MCP-specific
quickstart and tool surface. The architectural decisions governing
the wrapper are recorded in DECISIONS.md.
./test.shTests cover all capture verbs (normal and edge cases including special characters, missing arguments, unknown flags) and the operational-verb stubs.
cma sits alongside two open reference artifacts published by Clarethium:
- Touchstone validates work against quality standards.
- Lodestone orients practice.
cma is the executable companion to Lodestone. The doctrine is in Lodestone; the running code is here.
cma is methodology-agnostic. The --fm field on captures is an opaque string; cma stores it without interpretation. When using a methodology with a canonical failure-mode catalog (such as Lodestone), tag with the methodology's canonical names. The methodology owns the vocabulary and its meaning; cma owns the data substrate.
For automatic classification at capture time, set CMA_FM_CLASSIFIER to a command that reads the description on stdin and emits the failure-mode tag on stdout:
export CMA_FM_CLASSIFIER=/path/to/your-classifier
cma miss "the operator skipped verification before deploying"
# Classifier auto-tags the --fm value based on the description.The classifier is external to cma; you provide the command. It can be Lodestone-aware (mapping descriptions to Lodestone's canonical failure shapes), methodology-specific, or generic. cma invokes it as an opaque command. Failure-isolated: if the classifier errors, is missing, or times out (5s), the capture proceeds without an --fm value. See ARCHITECTURE.md Section 9 for the full integration pattern.
cma's action-time injection layer follows a five-stage architecture (interception, context extraction, query, injection, logging). The pattern, reference implementations, data contracts, and validation framework are specified in ARCHITECTURE.md. Read it before writing a new integration; conform to its contracts so downstream analysis tooling stays consistent.
ARCHITECTURE.md Section 6 specifies <50ms typical latency for action-time injection. Measured against a synthetic 100-capture data set (./bench.sh):
| Operation | Median | p95 |
|---|---|---|
cma-pre --check (no match) |
6ms | 10ms |
cma-pre --check (matched surface) |
36ms | 43ms |
cma surface --surface <s> |
27ms | 31ms |
cma stats --recurrence |
26ms | 31ms |
cma stats (default summary) |
8ms | 9ms |
All operations stay under the 50ms target at p95. Cold-start invocations (first call in a fresh shell) may run higher; the wrapper warms up after a few hooks fire.
The 1.0 surface is locked (see DESIGN.md) and all seven primitives are functional. Action-time injection ships for Claude Code (PreToolUse and SessionStart hooks) and for shell environments (zsh native preexec, bash via bash-preexec). Both follow the five-stage architecture in ARCHITECTURE.md.
Beyond 1.0: counterfactual capture analysis tooling, per-project data scoping, recency-weighted surface ranking. See CHANGELOG.md for the full pending list.
Apache 2.0. See LICENSE.
L. Lucic. Published under Clarethium.