Skip to main content
Glama

Trammel

License: MIT npm

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.

Trammel Plan & Explore Demo

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

start_plan / decompose

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 files) and the plan starts from them plus a few direct neighbours. Worth it for multi-file changes and handoffs; for a one-file edit, just edit.

verify_step

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. ref: "HEAD" tests a clean checkout of a commit instead (tracked files, line endings as a fresh checkout makes them). The reply says where the copy is and how long its deepest build path gets, what the run left behind (files created, changed, deleted, or with only their line endings changed), and each failed test's own message. plan_id and step_id store the outcome on a plan step. timeout_s (default 300, 600 per call); background: true plus job_status for longer runs. Output is capped at 4 KB.

get_plan / resume / add_note

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. resume also names the first step without a passing verify.

add_constraint / get_constraints

Rules and known-bad approaches that every later agent reads before editing.

claim_step / available_steps / record_steps

Several agents on one plan without doing the same step twice. Claims expire after 10 minutes.

complete_plan / get_recipe

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 installing

Without 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 mcp

Any 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

core (always on)

start_plan, decompose, get_plan, resume, complete_plan, status

plan

explore, list_plans, update_plan_status, merge_plans, export_plan, record_steps, history, estimate, list_strategies

verify

verify_step, verify_plan, job_status, cancel_job

Chisel start_job / job_status

recipes

save_recipe, get_recipe, list_recipes

constraints

add_constraint, get_constraints, deactivate_constraint, resolve_failure, failure_history

locks

claim_step, release_step, available_steps

Chisel locks, CoordinationHub leases

notes

add_note

wikifier journal notes

maintenance

prune_recipes, prune_plans, validate_recipes, usage_stats

  • TRAMMEL_TOOLS: comma-separated groups and/or tool names to expose (plus core); all means everything. When set, it replaces the TRAMMEL_MCP_SURFACE default listing.

  • TRAMMEL_DISABLE: comma-separated groups and/or tool names to hide, applied after TRAMMEL_TOOLS. core cannot be disabled.

  • Case and spaces are ignored. An unknown name (or core in TRAMMEL_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_TOOLS over the AGENTS.md tools line, TRAMMEL_DISABLE over the disable line, 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

core

start_plan, get_plan, resume, complete_plan, decompose, status

Never (always on).

plan

alternative orderings, plan lists, merging, export, estimates

You only start, read and complete plans.

verify

running the tests on a copy with your edits

You run the tests yourself every time.

recipes

reusing strategies that worked for similar goals

Work is one-off and nothing repeats.

constraints

rules and failure history every agent reads

The project keeps its rules elsewhere.

locks

claims so several agents don't take the same step

One agent works on the project, or CoordinationHub manages leases.

notes

handoff notes on a plan

One session does the whole job, or handoffs go through another tool (wikifier journal, CoordinationHub messages).

maintenance

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:

  1. get_constraints and get_recipe for anything learned earlier.

  2. start_plan with the goal. Keep the plan_id.

  3. For each step: edit, then verify_step with the changed files and the step's plan_id and step_id, so the outcome is stored on the step. Fix and repeat until it passes. Read left_behind and failed_tests in the reply.

  4. Before you push, verify_step with ref: "HEAD" runs the tests on a clean checkout of the commit, as CI will see it.

  5. complete_plan saves 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 ordering

trammel migrate imports an old Python trammel.db into .trammel/ and leaves the SQLite file in place.

How it works

  1. 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) or files is 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 unless expand_repo is false. Code comes before tests.

  2. 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.

  3. 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, and timed_out when the limit was hit. With ref, the copy is a clean checkout of that commit instead: git reads the commit into a temporary index and checkout-index writes it with .gitattributes and 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, 0 makes a fresh copy each time). copy.longest_path estimates 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 with path_too_long. After the run left_behind lists what the run created, changed or deleted in the copy (build output under target, node_modules and other generated folders does not count), and marks a change of line endings only; the next run restores the copy. A failed run lists failed_tests with each test's message (cargo, unittest, pytest, go test, Jest), up to 8 tests of 400 characters each.

  4. Constrain. Store rules and failures so later agents see them.

  5. Remember. Save a successful strategy; get_recipe matches 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 --version

78.1

87.19

0.70

CLI --help

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 true

321.1

356.13

28.44

MCP primary initialize

306.6

568.73

0.94

MCP primary tools/list

1.8

1.72

0.10

MCP all initialize

308.8

559.88

0.94

MCP all tools/list

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/trammel

CI 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

src/

Library and the trammel / trammel-mcp binaries

examples/

Repo checks and the benchmark gate

schemas/

Result schema per MCP tool

data/patterns.json

Implicit-edge rules, embedded at compile time

tests/, parity/fixtures/

Rust tests, sample projects, decompose golden

npm/

The npm wrapper and six platform packages

bench/

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…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Advanced 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
    • A
      license
      Not graded
      quality
      D
      maintenance
      An 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.
      1
      MIT