Trammel: Instructions file for Codex

Trammel agent guide

Trammel 4.x is one std-only Rust binary (trammel, trammel-mcp) and the npm package @iron_adamant/trammel. npx -y @iron_adamant/trammel mcp starts the MCP server. The old Python version lives on the python-legacy branch. Do not tag or publish from a task branch.

Commands

cargo test
cargo build --release
cargo run --release --example bench_gate -- --self-test
cargo run --example check_zero_deps
cargo run --example check_no_todos
cargo run --example check_syntax_core

Those checks are std-only Rust in examples/, run from the repo root. No Python is needed to build, test, or check the repo. The migrate tests read tests/fixtures/trammel-3.15.3.db, written once by python-legacy's RecipeStore.

trammel doctor is JSON by default. --human prints indented JSON. --version prints {"version":"<Cargo.toml version>",...}. The version lives only in the manifests (Cargo.toml, Cargo.lock, npm/*/package.json, server.json); tests read CARGO_PKG_VERSION and fail if a manifest disagrees.

Module map

• src/syntax/, src/lang/python/, src/lang/python_symbols/, src/lang/json.rs, src/lang/kind.rs: stele-context parser core, commit 244561a491ac4002b2c4bc94a3884091870a6d11. scripts/syntax_core_manifest.txt is their digest. The only local change is a newline index in python_symbols so line numbers stay identical without scanning the file prefix per identifier. cargo run --example check_syntax_core -- --against DIR compares with a stele checkout and stops at the first file that differs (one of those two).
• src/lang/code.rs: lossless lexer for the other languages.
• src/lang/symbols.rs, src/lang/imports.rs: hand-written extractors.
• src/planner.rs, src/score.rs, src/strategies.rs, src/implicit.rs: decompose and the nine beams. Rules are data/patterns.json.
• src/store.rs: .trammel/store snapshot. src/migrate.rs reads an old trammel.db and its WAL, read-only.
• src/mcp.rs, src/cli.rs, src/tools.rs: one dispatch for both surfaces. src/catalogue.rs: tool descriptions and input schemas for tools/list. src/groups.rs: tool groups and the TRAMMEL_TOOLS / TRAMMEL_DISABLE switches.
• src/benchstat.rs: the regression rule.