tman documentation

Reference for every command, flag, and file. For attaching tman to a specific AI coding agent see the setup guides; for recommended caps per test or lint tool see thetuning guides.

install

# npm
npm install -g @standardbeagle/tman

# or the shell one-liner
curl -fsSL https://raw.githubusercontent.com/standardbeagle/tman/main/install.sh | sh

commands

run flags

Durations accept ms, s, m, h (e.g. 90s, 10m). Cap precedence: CLI flags > alias block > defaults block > built-ins. A flag whose value cannot be read refuses the run with exit 127 and names the flag (bad --max-cpu); nothing is clamped or defaulted.

--max-time, --max-mem, and --max-cpu have no built-in default. A build is supposed to saturate cores and can legitimately want several GB, so culling it out of the box would break tman run -- vite build in a project with no config.

platform note

Every sample covers the whole process tree on all three platforms — /proc on Linux, libproc on macOS, a Toolhelp snapshot on Windows — so --stall, --max-mem and--max-cpu see a forked worker wherever it runs. Only Linux reads process states, so the kernel-io-wait (D) signal is Linux's alone; the io counter is rchar/wcharon Linux, disk bytes on macOS, and all io transfer bytes on Windows. A descendant that has left the tree — reparented to init or launchd, or orphaned on Windows — is not counted anywhere.

buckets

Dedup locks and parallel slots are scoped per bucket, not machine-wide. A bucket is<name>@<dir> for a named run and <command>@<dir> for an unnamed one, where <dir> is the .tman.kdl directory governing the run (or the cwd when there is none).

/repo-a  tman test          -> bucket  test@/repo-a
/repo-b  tman test          -> bucket  test@/repo-b   # independent of repo-a
/repo-a  tman run -- vite   -> bucket  vite@/repo-a   # independent of test@/repo-a

So max-parallel 2 means two of this thing here, and a long test run in one checkout never starves a build in another. A supervised process that re-enters tman — a PATH shim calling tman again — is recorded as a child of the run that launched it and does not claim a second slot.

A run is admitted by holding one of its bucket's slot files open exclusively, not by counting the live runs in the bucket. Only one runner can hold a given slot file, so runs launched at the same instant queue as configured; counting could not offer that, because every racer reads the count before any of them has a record to be counted. A slot is given up when the handle closes, which includes the runner dying and the kernel closing it.

housekeeping

There is no daemon and no cron entry. Every tman invocation — includingtman list — sweeps the run store (~/.tman/runs, override withTMAN_HOME) before doing its own work:

• Orphans are killed. If a recorded run's runner process is dead but its child is still alive — the classic agent-got-distracted or machine-suspended case — the child's entire process tree is killed and the record marked reaped. PID reuse is guarded by comparing process start times.
• Finished records past retain are deleted (24h by default), along with record files this tman cannot read, which nothing else would ever revisit.

Lock files are not part of the sweep. A lock is claimed by holding its file open exclusively, so a runner killed mid-run frees its bucket the moment the kernel drops its handle, and the next run of that bucket takes the lock over in place. Nothing in tman ever removes a lock file: ~/.tman/runs keeps one .lock per bucket it has seen for the name dedup, plus one per parallel slot that bucket has ever handed out.

The bound, stated plainly. Each lock file is ~50 bytes but occupies one filesystem block, so budget about 4 KB per bucket. A development machine reuses a handful of buckets and settles at a few dozen kilobytes. The one case that grows without limit is a host whose working directory changes every build — a CI runner whose workspace path carries a build number — which seeds a new bucket each time: on the order of 20 MB a year at twenty builds a day. If that is you, rm ~/.tman/runs/*.lock while no runs are live, from the same cleanup step that clears the workspace. tman deliberately does not do this for you: making it safe against a concurrent claim costs every tman run a store-wide lock, which is a poor trade for reclaiming a few megabytes a year.

tman clean runs the same sweep on demand and prints the counts. Records are canonical on disk — the command resolved to an absolute path, an absolute cwd, the caps the run actually ran under, and a schema version, so a record written by a different tman version is discarded rather than half-read.

.tman.kdl

Resolved from the current directory upward (like .git). An alias runs in the directory holding that .tman.kdl, so its args can be written relative to the config; a bare tman run -- cmd runs where you are standing. tman init auto-detects npm (test, e2e, lint, integration, build, typecheck), pytest, go, and make projects.

defaults {
    stall "30m"
    max-parallel 2
    retain "24h"      // how long finished run records are kept
    // opt-in ceilings; builds legitimately saturate cores and eat RAM
    // max-mem 8192
    // max-cpu 95
}

alias "test" {
    command "npm"
    args "run" "test"
    max-time "10m"
}

alias "e2e" {
    command "pytest"
    args "tests/e2e" "--tb=short"
    max-time "30m"
    max-mem 4096
}

alias "dev" {
    command "vite"
    service true      // a dev server never ends: booked, but never waited for; the tman <alias> door takes no flags
}

The parser reads a subset of KDL: nodes with string and number arguments, // and/* */ comments, and /- slashdash, which comments out the next node or value. Properties (max-parallel=4) are refused with a message naming themax-parallel 4 form to write instead.

shims

tman init --shims writes an executable per alias at the repo root (./test,./e2e, plus .ps1 and .cmd on Windows — the extensionless script covers bash/zsh/fish/sh everywhere including Git Bash) that simply exec tman run --alias …. Existing muscle memory and agent habits keep working; supervision is transparent.--gitignore appends the shims and /.tman/ to .gitignore, skipping any alias whose name is already a directory so /test never hides a test/ tree. If PowerShell refuses to run the .ps1 shims, allow local scripts once:Set-ExecutionPolicy RemoteSigned -Scope CurrentUser.

exit codes

claude code hook

Shims only catch commands that go through a shell lookup, in a project wheretman init --shims ran. An agent calling a Bash tool with npm test walks straight past them. tman hook pretooluse applies the same policy one level up: it reads the tool call on stdin and re-issues bare test and build commands through tman.

{
  "hooks": {
    "PreToolUse": [
      { "matcher": "Bash", "hooks": [{ "type": "command", "command": "tman hook pretooluse" }] }
    ]
  }
}

It never blocks a command. It also supervises exactly what was asked for (tman run -- <command>) and never the project's alias of the same name — an alias can point elsewhere, and silently running something other than the command in the transcript is worse than running it unsupervised.

scope

tman supervises one machine at a time — a developer's laptop, or a department-sized CI host with a handful of runners. At that size it does what it says: a rogue test runner does not sit in a loop on your battery, and a test server does not hold a port for the rest of the afternoon.

It is not a fleet scheduler. There is no cross-machine coordination, no central store, and nothing here is tuned for dozens of simultaneous runs or for hosts that accumulate work indefinitely. Under a build fleet's own scheduler tman is fine; it will not be the thing keeping that fleet in order.

building

# NativeAOT, zero external dependencies, .NET 10 SDK (and cc on Linux/macOS)
dotnet publish -c Release -r linux-x64   # win-x64, osx-arm64, linux-arm64