trammel
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
Trammel
Trammel helps coding agents plan, verify, and hand off multi-file changes.
Give it a goal and a project. It reads the imports and symbols, orders the files to change by dependency, checks edits by running the tests on a temporary copy of the project, and keeps plans, rules, failures, and successful strategies in .trammel/ so the next session or another agent can pick the work up. It is one std-only Rust binary (trammel, trammel-mcp) with no dependencies and no network access.
Trammel is a tool for LLMs, not a tool that calls LLMs. It does not write code; the agent does.

15 languages: Python, TypeScript, JavaScript, Go, Rust, C/C++, Java/Kotlin, C#, Ruby, PHP, Swift, Dart, Zig. The old Python version is on the python-legacy branch.
What an agent gets
Call | What it saves the agent |
| One call returns the files a goal touches, code in dependency order and then tests, each with a role and goal relevance. Name the files in the goal (or pass |
| Edits applied to a copy of the project, a syntax preflight, and the project's tests, without touching the working tree. The copy and its cargo target dir are kept, so a second run rebuilds only what changed. |
| A saved plan with step status, claims, each step's last verify outcome, and the previous agent's notes: how a new session or a sub-agent picks up work cold. |
| Rules and known-bad approaches that every later agent reads before editing. |
| Several agents on one plan without doing the same step twice. Claims expire after 10 minutes. |
| A strategy that worked, matched to later goals by text similarity. |
Related MCP server: MCP Shrimp Task Manager
Install
npm i -g @iron_adamant/trammel # puts trammel and trammel-mcp on PATH
npx -y @iron_adamant/trammel mcp # or run the MCP server without installingWithout npm, from a GitHub Release: sh install.sh (Linux or macOS, into ~/.local/bin) or install.ps1 (Windows, into %LOCALAPPDATA%\trammel\bin). From this checkout: cargo build --release, which builds target/release/trammel and target/release/trammel-mcp.
Use it from an MCP client
Claude Code:
claude mcp add trammel -- npx -y @iron_adamant/trammel mcpAny client with a JSON config (Cursor, Claude Desktop, and others):
{
"mcpServers": {
"trammel": {
"command": "npx",
"args": ["-y", "@iron_adamant/trammel", "mcp"]
}
}
}The server speaks stdio (protocols 2026-07-28, 2025-11-25, 2025-06-18, 2025-03-26, 2024-11-05) and works on the project in its working directory; every tool also takes project_root. tools/list shows 13 primary tools with full input schemas. Set TRAMMEL_MCP_SURFACE=all in the server's environment to list all 33, including the multi-agent tools.
Tool groups
Every tool is in one group. Agents choose a project's groups in its AGENTS.md (see Choosing groups below); an operator can override with two variables in the server's env. Either way, an agent running several suite tools keeps only the parts it uses. They shape the MCP listing only; the CLI is unchanged.
Group | Tools | Overlaps with |
|
| |
|
| |
|
| Chisel |
|
| |
|
| |
|
| Chisel locks, CoordinationHub leases |
|
| wikifier journal notes |
|
|
TRAMMEL_TOOLS: comma-separated groups and/or tool names to expose (pluscore);allmeans everything. When set, it replaces theTRAMMEL_MCP_SURFACEdefault listing.TRAMMEL_DISABLE: comma-separated groups and/or tool names to hide, applied afterTRAMMEL_TOOLS.corecannot be disabled.Case and spaces are ignored. An unknown name (or
coreinTRAMMEL_DISABLE) stops the server at startup with one line on stderr and exit code 2, so the client shows it as failed. A call to a hidden tool returns an error that says which variable or AGENTS.md line to change.Precedence, per key:
TRAMMEL_TOOLSover the AGENTS.mdtoolsline,TRAMMEL_DISABLEover thedisableline, then the built-in default.
{
"mcpServers": {
"trammel": {
"command": "npx",
"args": ["-y", "@iron_adamant/trammel", "mcp"],
"env": {"TRAMMEL_DISABLE": "locks,notes"}
}
}
}Choosing groups
Pick Trammel's groups for a project by adding a line to the project's own AGENTS.md (its root, next to .git). The server re-reads it on every request and tells the client the tool list changed, so no restart is needed.
```agent-tools
trammel: disable locks, notes
```Group | For | Turn it off when |
| start_plan, get_plan, resume, complete_plan, decompose, status | Never (always on). |
| alternative orderings, plan lists, merging, export, estimates | You only start, read and complete plans. |
| running the tests on a copy with your edits | You run the tests yourself every time. |
| reusing strategies that worked for similar goals | Work is one-off and nothing repeats. |
| rules and failure history every agent reads | The project keeps its rules elsewhere. |
| claims so several agents don't take the same step | One agent works on the project, or CoordinationHub manages leases. |
| handoff notes on a plan | One session does the whole job, or handoffs go through another tool (wikifier journal, CoordinationHub messages). |
| pruning old plans and recipes, usage counts | Almost always; turn it on to clean up a long-lived store. |
Use trammel: tools <groups> instead to keep only what you name (plus core). Lists take group or tool names, separated by commas or spaces. A wrong name is ignored with a warning in the initialize instructions and in status; it never stops the server. TRAMMEL_TOOLS / TRAMMEL_DISABLE in the server's env override the matching line.
tools/list sizes: default 15,605 bytes; with TRAMMEL_MCP_SURFACE=all 29,278, minus locks 27,240, minus notes 28,516, minus both 26,478; TRAMMEL_TOOLS=core 7,818.
A typical loop:
get_constraintsandget_recipefor anything learned earlier.start_planwith the goal. Keep theplan_id.For each step: edit, then
verify_stepwith the changed files and the step'splan_idandstep_id, so the outcome is stored on the step. Fix and repeat until it passes. Readleft_behindandfailed_testsin the reply.Before you push,
verify_stepwithref: "HEAD"runs the tests on a clean checkout of the commit, as CI will see it.complete_plansaves the strategy as a recipe.
To hand off, add_note what you did and what is left, and give the next agent the plan_id; it calls resume, reads the notes, and starts at next_step, the first step without a passing verify. SYSTEM_PROMPT.md is a fuller prompt for MCP clients. docs/LLM_CONTRACT.md is the JSON contract.
Use it from the command line
Every tool is also a subcommand. Output is one JSON object on stdout; --human indents it.
trammel doctor # store path, languages, next steps
trammel decompose --goal "add retries to the HTTP client" --project-root .
trammel start_plan --goal "add retries to the HTTP client" --summary_only true
trammel get_plan --plan_id 1
trammel "refactor auth module" --dry-run # plan only, nine orderings
trammel "fix tests" --test-cmd pytest -x -q # plan, then run the tests per orderingtrammel migrate imports an old Python trammel.db into .trammel/ and leaves the SQLite file in place.
How it works
Decompose. Parse the project's imports and symbols, add edges inferred from naming and shared-state rules (
data/patterns.json), sort files by dependency, and score each file's relevance to the goal. When the goal names files (paths,game.rs,`timeline`,app::sight) orfilesis passed, the plan is those files plus their direct dependencies, dependents and tests from real imports, capped and ranked below them. Otherwise a whole-repo plan keeps the 15 most relevant files unlessexpand_repois false. Code comes before tests.Explore. Nine orderings (bottom-up, top-down, risk-first, and others) of the same steps, for when the default order is not the one you want.
Verify. Bring a copy of the project (in a git repo, the files git would commit; ignored build output and data stay behind) up to date, rewriting only files that differ, apply the edits, check syntax, run the test command with the copy's own
CARGO_TARGET_DIR, and report pass or fail with capped output,elapsed_s, andtimed_outwhen the limit was hit. Withref, the copy is a clean checkout of that commit instead: git reads the commit into a temporary index andcheckout-indexwrites it with.gitattributesand this repository's line-ending settings, so the project's index, HEAD and worktree list are not touched. The copy lives at<temp>/trv/<8 hex>/<slot>/t, its build output at.../<slot>/b(TRAMMEL_VERIFY_CACHE=<dir>moves it,0makes a fresh copy each time).copy.longest_pathestimates the longest path a build creates there: the deepest copied file, or for a cargo project the target dir plus cargo's incremental files for the longest crate name (about 118 characters plus the name). On Windows the reply warns from 240 characters and refuses past 259 withpath_too_long. After the runleft_behindlists what the run created, changed or deleted in the copy (build output undertarget,node_modulesand other generated folders does not count), and marks a change of line endings only; the next run restores the copy. A failed run listsfailed_testswith each test's message (cargo, unittest, pytest, go test, Jest), up to 8 tests of 400 characters each.Constrain. Store rules and failures so later agents see them.
Remember. Save a successful strategy;
get_recipematches later goals by a text blend (trigram cosine, word Jaccard, substring).
State lives in .trammel/ in the project. Several processes can share it; writes take a file lock.
Configuration
Optional. .trammel.json in the project root (or [tool.trammel] in pyproject.toml):
{
"default_scope": "src/",
"focus_keywords": ["auth", "login"],
"max_files": 50,
"test_cmd": ["cargo", "test"],
"verify_timeout_s": 600
}verify_step takes its test command from the call's test_cmd, then this file, then the language default (python -m unittest, cargo test, npm test, go test ./..., and so on), and its time limit from timeout_s, then verify_timeout_s, then 300 seconds. A call that waits stops at 600 seconds; with background: true a job may run 3600. TRAMMEL_TELEMETRY=1 records local usage counts; nothing leaves the machine.
Benchmarks
Figures below were measured, not estimated. Rust is faster on every row than both the recorded baseline and a same-machine rerun of Python 3.15.3.
The recorded column is bench/python_baseline.json: Trammel 3.15.2, Python 3.13.5, mcp 1.30.0, Linux 6.12.94 x86_64, 8 vCPU Intel Xeon, 15.6 GB, 2026-11-04. That box is not the one that produced the other two columns.
The same-runner columns are bench/same_runner.json, measured 2026-11-03 on Linux 6.12.94 x86_64, 4 vCPU Intel Xeon, 15.6 GB, rustc 1.99.1, Python 3.12.3, Trammel 3.15.3, mcp 2.3.0. rich is the 13.9.4 git tag (190 .py files). flask is the 3.1.0 sdist (83 .py files). Startup and cold MCP rows are 10 runs. The flask full run is 3. Every other row is 7. Values are medians in milliseconds.
Benchmark | Recorded Python | Same-runner Python | Same-runner Rust |
CLI | 78.1 | 87.19 | 0.70 |
CLI | 78.7 | 91.88 | 0.71 |
CLI dry-run rich | 469.9 | 97.86 | 19.89 |
CLI dry-run flask | 253.7 | 318.88 | 10.41 |
CLI dry-run trammel-src | 332.4 | 109.34 | 11.87 |
CLI full flask, test command | 321.1 | 356.13 | 28.44 |
MCP primary | 306.6 | 568.73 | 0.94 |
MCP primary | 1.8 | 1.72 | 0.10 |
MCP all | 308.8 | 559.88 | 0.94 |
MCP all | 2.1 | 2.00 | 0.32 |
MCP status, empty store | 18.8 | 12.74 | 0.16 |
MCP estimate rich | 4.5 | 4.16 | 1.01 |
MCP decompose rich | 425.6 | 550.84 | 20.85 |
MCP decompose rich, summary only | 400.0 | 566.02 | 19.76 |
MCP decompose flask | 171.3 | 211.98 | 8.81 |
MCP explore rich, 3 beams | 427.7 | 538.33 | 20.29 |
MCP start_plan rich | 417.5 | 566.15 | 20.60 |
MCP get_plan | 5.9 | 3.61 | 0.54 |
MCP resume | 6.4 | 3.46 | 0.49 |
MCP verify_step, rich import | 183.3 | 172.86 | 135.34 |
MCP verify_step, Trammel unit tests | 3179.7 | 3417.21 | 2767.64 |
MCP record_steps | 7.6 | 5.65 | 1.65 |
MCP add_constraint | 6.4 | 2.69 | 0.94 |
MCP get_constraints | 3.9 | 2.96 | 0.24 |
MCP export_plan | 4.2 | 2.92 | 0.58 |
MCP complete_plan | 10.7 | 5.82 | 1.14 |
MCP get_recipe | 7.9 | 4.37 | 0.53 |
MCP list_plans | 5.2 | 2.76 | 0.34 |
MCP status after the flow | 4.3 | 2.44 | 0.26 |
MCP VmHWM after the flow (MB) | 66.6 | 75.30 | 8.09 |
tools/list payload, one measurement of the JSON line: Python primary 12,508 bytes and 12 tools, Python all 23,515 bytes and 33 tools, Rust primary 3,340 bytes and 12 tools, Rust all 8,777 bytes and 32 tools. This x86_64 release build is trammel 2,131,840 bytes and trammel-mcp 2,032,264 bytes. The CI floor in examples/bench_gate.rs fails a build whose --version, --help, or MCP initialize median is at or above the recorded Python median. The regression rule (an A/A run passes, an injected slowdown fails, no percentage tolerance) is cargo test --lib benchstat.
Since those runs, tools/list carries full input schemas, so its payload is larger; MIGRATION.md has the current sizes.
Coming from the Python version
Trammel 3.15.3 was the last Python release; it is on the python-legacy branch, and its release notes are in docs/PYTHON_CHANGELOG.md. The commands, the 12 primary tool names of 3.x (4.x adds add_note), the nine beam names, the 15 languages, .trammel.json, trammel.plan exports, and the 10 minute claim are unchanged. trammel migrate imports an old store. MIGRATION.md lists every difference, each marked as an intentional change, a bug fixed from Python, or not supported.
Development
cargo test --locked # library, CLI, MCP, and repo-check tests
cargo run --example check_zero_deps # Cargo.lock names only trammel
cargo run --example check_no_todos # no TODO or FIXME left in src/
cargo run --example check_syntax_core # vendored parser files match the manifest
cargo build --release
cargo run --release --example bench_gate -- target/release/trammelCI runs these on Linux, macOS, and Windows. The crate has no dependencies and [dependencies] stays empty; the repo checks are std-only Rust too. AGENTS.md maps the modules and explains how to add a language or a tool.
Path | Contents |
| Library and the |
| Repo checks and the benchmark gate |
| Result schema per MCP tool |
| Implicit-edge rules, embedded at compile time |
| Rust tests, sample projects, decompose golden |
| The npm wrapper and six platform packages |
| Recorded Python and Rust timings |
Releases: a v* tag runs .github/workflows/release.yml, which checks that the tag matches the version in Cargo.toml, the npm packages and server.json, builds six binaries (Linux musl, macOS, and Windows, each x64 and arm64), uploads them with SHA256SUMS, and publishes the npm packages. scripts/release.sh checks the version and prints the tag command; it does not publish. To cut a tag and a GitHub Release without publishing to npm, set the repository variable NPM_PUBLISH to false before tagging, then run the Release workflow by hand with that tag later (and remove the variable). server.json is the MCP Registry manifest for io.github.IronAdamant/trammel. Changes are in CHANGELOG.md.
Trammel works on its own. With Stele and Chisel the three meet at the MCP layer, with no code dependency between them.
License
MIT. See LICENSE.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Goal and task planning MCP for Codex and AI agents, with evidence-backed completion.
Adaptive plan/build/review cycles for AI coding assistants, persisted across sessions.
AI-powered spec-to-task decomposition and execution orchestration for coding agents.
AI work orchestration for plans, tasks, teams, and coding-agent dispatch.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceAdvanced task automation system that reads codebases, divides complex tasks into specific steps, and rigorously executes them with complete testing, documentation, validation and automatic correction.MIT
- AlicenseNot gradedqualityDmaintenanceAn intelligent task management system that provides structured workflows for AI Agents to plan, decompose, and execute complex programming tasks. It features a dedicated research mode for technical investigations and a task memory function to optimize workflows and avoid redundant coding work.1MIT
- AlicenseNot gradedqualityCmaintenanceAn autonomous task decomposition and execution agent that plans, executes, verifies, and commits code changes for engineering goals.MIT
- FlicenseBqualityDmaintenanceEnables AI coding assistants to run a machine-verified DESIGN→PLAN→EXECUTE→VERIFY→COMPLETE workflow with human approval gates, state integrity checks, and DAG task scheduling.7-