DEV Community: Andy Brummer

Setting up tman with a Vite project

Andy Brummer — Sat, 01 Aug 2026 03:12:17 +0000

If you let AI coding agents loose on a frontend repo, they run npm run build and npm run dev constantly — and often from several sessions at once. Nothing is broken, exactly. You just have four builds racing in one checkout, two dev servers fighting over a port, no way to tell them apart, and no record of what any of them did.

tman fixes the everyday version of that problem: it gives every run a name, a slot, and a record. The same suite never runs twice at once, excess runs queue instead of stampeding your cores, and every run leaves a JSON record you can query afterwards. Underneath sits a backstop that kills the rare run that genuinely hangs or leaks.

It's a single ~3.8 MB NativeAOT binary with zero runtime dependencies (Linux, macOS, Windows). This post walks through adopting it in a stock Vite project.

Install

npm install -g @standardbeagle/tman

Or the shell one-liner if you don't want it in your global node modules:

curl -fsSL https://raw.githubusercontent.com/standardbeagle/tman/main/install.sh | sh

A stock Vite project

Nothing special about the target project — this is the plain scaffold:

npm create vite@latest vite-demo -- --template react-ts
cd vite-demo
npm install

Which gives you the usual scripts in package.json:

"scripts": {
  "dev": "vite",
  "build": "tsc -b && vite build",
  "lint": "oxlint",
  "preview": "vite preview"
}

Step 1 — adopt tman

One command:

tman init --shims --gitignore

tman init reads package.json, detects the scripts worth supervising, and writes three things:

.tman.kdl — the per-project config with an alias per detected script
shims — tiny ./build and ./lint wrappers at the repo root, so existing muscle memory (and agents that just run ./build) go through tman transparently
.gitignore entries for the shims

Note what it did not scaffold: there's no test script in a fresh Vite app, so there's no ./test shim pretending otherwise. Aliases tman can't detect are left commented out — a missing suite fails loudly instead of faking a pass.

Step 2 — look at `.tman.kdl`

The defaults block is deliberately conservative:

stall "30m" — a hang backstop, not a runtime budget. It only fires when a run is silent and idle for 30 minutes. A cold tsc -b can legitimately think for a long while without printing; a stall sized like an expected runtime would kill healthy work.
max-parallel 2 — at most two runs per bucket at once; the rest queue instead of racing.
retain "24h" — how long finished run records stick around.
The memory/CPU/wall-clock ceilings are commented out because builds legitimately saturate cores and eat RAM. You opt in when a suite has actually misbehaved.

Each alias block maps a name to a command, so tman build (or the ./build shim) means npm run build — supervised.

Step 3 — run a supervised build

./build

Identical output to npm run build, because it is npm run build — plus a name, a dedup lock, a slot in the queue, and a run record. The supervision is invisible until the day you need it.

Step 4 — the dev server problem

Here's the case that sold me. Two agent sessions both decide the dev server should be running:

tman run --name dev -- npm run dev &
tman run --name dev -- npm run dev

The second invocation is refused immediately:

tman: run 'dev' already active (pid 2244513, id f281b5c2ad30); use --replace to kill it

No second Vite instance, no port fallback to 5174, no zombie server owning the port after the session that started it dies. If you want takeover semantics — a fresh server after a config change — that's --replace, which kills the old run and waits for it to hand the name back.

Locks bucket by name and directory, so a dev run in this repo never blocks a dev run in another checkout.

One tuning note for Vite specifically: never give a dev server --max-time. It's supposed to run forever. The wall-clock cap is for suites and builds, not servers.

Step 5 — what ran, and how did it go?

tman list --all
tman status

Every run leaves one JSON record: command, cwd, exit code, peak memory, start and finish, and the caps it ran under. tman status --json emits the same thing machine-readable, which is exactly what you want when an agent asks "did the build I started actually finish?" — or when you ask what your agents ran overnight.

Orphan reaping rides along for free: every tman command kills children whose runner died and prunes expired records. A crashed agent session doesn't leave a Vite server squatting on the port.

Step 6 — catch the runs that bypass the shims

Shims only catch commands that go through a shell lookup. An agent calling its Bash tool with a bare npm run build walks straight past them. For Claude Code, one hook applies the same policy a level up:

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

It rewrites bare test/build commands through tman run, leaves everything else untouched, and never blocks: every failure path (tman missing, malformed request, unreadable project) leaves the command exactly as written. There are equivalent guides for Codex CLI, Gemini CLI, Cursor, opencode, and others.

Wrap-up

Total setup cost for a Vite project: one npm install -g, one tman init. From then on:

duplicate builds and dev servers are refused, not raced
excess runs queue for a slot instead of saturating cores
every run leaves a record you (or your agents) can query
hangs and leaks get killed by a backstop that a healthy week never triggers

Docs: dev.standardbeagle.com/tman · Source: github.com/standardbeagle/tman · npm: @standardbeagle/tman

I can finally use MCPs without fear

Andy Brummer — Sun, 11 Jan 2026 06:03:02 +0000

MCP promised to make agentic coding fast and powerful, instead it overwhelmed the senses of the LLMs that we trusted to write code for us. Even Anthropic took notice that context is the modern day coding juice that we are all dependent on. Their solution farm the whole thing out to typescript and write a bunch of integration code to build the whole infrastructure from scratch. Instead, I had Claude write a custom programming language, the Simple Language for Orchestrating Prompts or SLOP and shoved it into an MCP Turducken to call and automate other MCPs.

Reading the Anthropic paper on the issue https://www.anthropic.com/engineering/code-execution-with-mcp and having written my own chat apps with the same architecture, I realized that making Javascript or Python safe for deployment anywhere was going to be a huge task that everyone is eventually going to bear the burden of. Instead I figured how about creating a simple language that solves this one problem and SLOP was born.

I quickly realized that the search and metadata services were the clear winners when Claude code just picked up searching for tools and calling them through the generic interface without a hitch.

Please give it a try: https://github.com/standardbeagle/slop-mcp

I've got 318 tools installed

and Claude Code is cranking along fine without issue.

Taming Windows Terminal's win32-input-mode in Go ConPTY Applications

Andy Brummer — Mon, 15 Dec 2025 08:16:29 +0000

When building agnt, a tool that gives AI coding agents browser superpowers, I hit a frustrating issue: my Ctrl+Y hotkey worked perfectly on macOS and Linux, but on Windows it produced garbage like [89;21;25;1;8;1_ instead of toggling my overlay menu.

This article documents the debugging journey and the solution - a Go 1.23+ iterator-based parser that correctly handles Windows Terminal's win32-input-mode escape sequences.

The Problem

I was wrapping AI coding tools (Claude, Gemini, etc.) in a pseudo-terminal to inject an overlay UI. The overlay listens for Ctrl+Y (byte 0x19) to toggle a menu. Simple enough:

if b == 0x19 { // Ctrl+Y
    overlay.Toggle()
}

On Unix, this worked immediately. On Windows with ConPTY, pressing Ctrl+Y produced:

[89;21;25;1;8;1_

What is this? It's a win32-input-mode escape sequence.

What is win32-input-mode?

Windows Terminal introduced win32-input-mode to provide richer keyboard input to ConPTY applications. Instead of sending raw bytes, it sends structured escape sequences:

ESC [ Vk ; Sc ; Uc ; Kd ; Cs ; Rc _

Where:

Vk - Virtual key code (89 = 'Y')
Sc - Scan code (21)
Uc - Unicode character (25 = Ctrl+Y)
Kd - Key down flag (1 = down, 0 = up)
Cs - Control key state (8 = Ctrl held)
Rc - Repeat count (1)

So [89;21;25;1;8;1_ decodes to: "Y key pressed with Ctrl held, unicode value 25".

The unicode value 25 (0x19) is exactly what I needed - but it's buried in an escape sequence!

The Debugging Journey

Step 1: Isolate the Trigger

First, I needed to understand when Windows Terminal enables win32-input-mode. I created a diagnostic tool:

// Direct stdin read - what bytes do we actually receive?
func main() {
    oldState, _ := term.MakeRaw(int(os.Stdin.Fd()))
    defer term.Restore(int(os.Stdin.Fd()), oldState)

    buf := make([]byte, 64)
    for {
        n, _ := os.Stdin.Read(buf)
        fmt.Printf("Read %d bytes: %q\n", n, buf[:n])
    }
}

Finding 1: Direct stdin reads showed raw bytes (0x19 for Ctrl+Y). Good.

Finding 2: When I created a ConPTY but didn't write its output anywhere, stdin still showed raw bytes.

Finding 3: When I wrote ConPTY output to stdout, suddenly stdin switched to win32-input-mode sequences!

The trigger: writing PTY output to stdout causes Windows Terminal to enable win32-input-mode for the session.

Step 2: Attempt to Disable It

ConPTY supports a sequence to disable win32-input-mode:

fmt.Fprint(os.Stdout, "\x1b[?9001l") // Disable win32-input-mode

This... didn't work reliably. Windows Terminal still sent the sequences in many scenarios.

Step 3: Parse the Sequences

If we can't disable it, we parse it. First attempt:

func parseWin32InputMode(data []byte) []byte {
    // Look for ESC [ ... _
    // Extract the Uc (unicode char) field
    // Return as raw bytes
}

This worked for single keypresses, but failed intermittently. The debug output revealed:

[win32] seq=89;21;25;1;8;1 -> byte 25 (0x19)  // First sequence parsed!
[win32] passthrough byte 27 (0x1b)            // Wait, why?
[win32] passthrough byte 91 (0x5b) '['        // This is another ESC[!

After parsing the first sequence correctly, subsequent sequences in the same buffer were passed through as raw bytes.

Step 4: The Buffer Boundary Bug

The culprit: os.Stdin.Read() returns arbitrary chunks. An escape sequence can be split across reads:

Read 1: ...25;1;8;1_\x1b     <- ends with ESC
Read 2: [17;29;0;0;0;1_...   <- starts with [

When Read 1 ends with \x1b, my parser checked data[i+1] for [, but there was no next byte - it was in the next read! The ESC got passed through as a raw byte.

The Solution: An Iterator with Remainder Handling

Go 1.23 introduced iter.Seq, which is perfect for this. The iterator:

Reads from stdin
Parses win32-input-mode sequences
Yields extracted bytes
Holds incomplete sequences for the next read

// ScanWin32Input returns an iterator that reads from r and yields parsed bytes.
// Buffer boundaries are handled internally - incomplete sequences at the end
// of a read are held and combined with the next read.
func ScanWin32Input(r io.Reader) iter.Seq[byte] {
    return func(yield func(byte) bool) {
        var pending []byte
        buf := make([]byte, 256)

        for {
            n, err := r.Read(buf)
            if n > 0 {
                // Combine pending bytes with new data
                var data []byte
                if len(pending) > 0 {
                    data = make([]byte, len(pending)+n)
                    copy(data, pending)
                    copy(data[len(pending):], buf[:n])
                    pending = nil
                } else {
                    data = buf[:n]
                }

                // Parse and yield bytes
                parsed, remainder := parseWin32Sequences(data)
                pending = remainder

                for _, b := range parsed {
                    if !yield(b) {
                        return
                    }
                }
            }

            if err != nil {
                return
            }
        }
    }
}

The key is parseWin32Sequences returning a remainder - any incomplete sequence at the end of the buffer:

func parseWin32Sequences(data []byte) (parsed []byte, remainder []byte) {
    var result []byte
    i := 0

    for i < len(data) {
        if data[i] == 0x1b {
            // ESC at end of buffer? Save as remainder
            if i+1 >= len(data) {
                return result, data[i:]
            }

            if data[i+1] == '[' {
                // Look for sequence terminator '_'
                end := findTerminator(data, i+2)

                if end > 0 {
                    // Complete sequence - parse it
                    b := extractUnicodeChar(data[i+2 : end])
                    if b > 0 {
                        result = append(result, b)
                    }
                    i = end + 1
                    continue
                }

                // No terminator found - might be incomplete
                if !hitInvalidChar {
                    return result, data[i:] // Save as remainder
                }
            }
        }

        // Regular byte - pass through
        result = append(result, data[i])
        i++
    }

    return result, nil
}

Usage

With the iterator, consuming parsed input is clean:

go func() {
    for b := range ScanWin32Input(os.Stdin) {
        inputCh <- b
    }
}()

// In main loop
for b := range inputCh {
    if b == 0x19 { // Ctrl+Y now works!
        overlay.Toggle()
    }
}

Key Takeaways

Windows Terminal enables win32-input-mode when you write PTY output to stdout. There's no reliable way to disable it.
Buffer boundaries will break naive parsers. Always handle the case where a sequence is split across reads.
Go 1.23+ iterators are perfect for streaming parsers. The iter.Seq pattern encapsulates state cleanly.
Build diagnostic tools. The keylog utility that tested different scenarios (direct read, PTY only, PTY + output) was essential for isolating the trigger.
Key-up events exist. Win32-input-mode sends both key-down (Kd=1) and key-up (Kd=0) events. Only emit bytes for key-down.

The Full Parser

The complete implementation handles:

Buffer boundary splitting
Key-down vs key-up filtering
Focus in/out sequences (ESC[I and ESC[O)
Invalid sequence recovery

You can find it in the agnt repository.

Resources

Win32 Input Mode Spec
ConPTY Documentation
agnt - Browser superpowers for AI coding agents
aymanbagabas/go-pty - Cross-platform PTY library for Go