This is a failure mode specific to agents that can write their own skills. If yours does (OMP’s autolearn, or any equivalent that persists SKILL.md files), you are probably accumulating the same debt without seeing it.

What a skill is, and why duplication hurts

A “skill” here is a small markdown file with frontmatter — a name, a one-line description: that says when to use it, and a body with the actual procedure. The agent loads every skill’s name + description into context on every turn, then picks the relevant one when a task matches.

That description line is the whole game. It’s how the agent decides which skill fires. And it’s always in context, whether or not you use the skill that session.

So duplication costs you twice:

1. Context tax — every description is always-loaded. My 108 skills were ~5.6k tokens of descriptions alone, paid on every single turn.
2. Selection tax — this is the subtle one. When five skills all say “use me for parsing that report,” the agent has to disambiguate between near-identical options. More overlapping choices means worse picks. This is the same “too many tools degrades tool-use accuracy” effect documented for MCP tool sprawl — skills are just tools by another name.

The second tax is why this matters more than “some wasted tokens.” The feature designed to make the agent smarter over time was quietly making it worse at choosing.

How it happens

Auto-learn is greedy and has no memory of what it already knows. Each time the agent solves a fiddly problem, it may decide “this is worth codifying” and write a new skill. It does not check whether a skill covering that ground already exists. So over weeks you get clusters like:

report-parse
report-parse-fix
report-parsing
report-truncation-fix
report-triage

Five files. One actual topic. ~90% identical bodies, each written on a different day when the agent forgot it had already learned this.

The tell is the naming. Cluster your skills by name prefix — any prefix with two or more entries is a duplication suspect.

import glob, os
from collections import defaultdict

skills = [os.path.basename(os.path.dirname(f))
          for f in glob.glob(os.path.expanduser("~/.omp/agent/managed-skills/*/SKILL.md"))]

clusters = defaultdict(list)
for name in skills:
    clusters["-".join(name.split("-")[:2])].append(name)

for prefix, members in sorted(clusters.items(), key=lambda x: -len(x[1])):
    if len(members) >= 2:
        print(f"[{len(members)}] {prefix}")
        for m in sorted(members):
            print("    ", m)

Prefix collision is a heuristic, not proof — but it turns “I have 100+ skills and no idea which overlap” into a ranked worklist in one pass.

The consolidation protocol

Not every same-prefix cluster is a duplicate, and this is where a careless cleanup destroys knowledge. The rule that kept it lossless:

A cluster is one of two things.

Near-duplicates (≈80%+ shared body, same trigger). Collapse to one:

1. Pick the superset skill as the keeper — the one that already covers the most ground.
2. Read the others and extract any unique one-liner — a caveat, a gotcha, a distinct step — that the keeper is missing.
3. Fold those gems into the keeper.
4. Only then delete the redundant skills.

The ordering is the whole discipline: never delete until the unique content is preserved somewhere. Merging is lossy by default; you make it lossless by hand.

Genuinely distinct siblings that happen to share a prefix. Keep them all — but fix the descriptions:

Same-prefix ≠ duplicate. Four skills about four different facets of one subsystem should stay four skills — but each description needs a unique trigger and, ideally, an explicit “NOT for X — see sibling” pointer so they stop competing.

Parallelize the judgement

The assessment (“is this cluster a merge or a keep-distinct?”) is real work, and it’s embarrassingly parallel: each cluster is independent, and if you shard by name prefix, no two workers touch the same files.

I handed each prefix cluster to a separate subagent with one shared instruction set (the protocol above) and let them run concurrently. One pass took the library from 110 skills to 95 with zero content loss — and the subagents caught two bugs inside the surviving skills along the way (a reference to a script that no longer existed, and a stale command superseded months ago). Fresh eyes on skills you stopped reading are a bonus dividend.

A caution worth stating: run the judgement in parallel, but keep the decomposition — which clusters exist, how to shard them — as your own job. Sharding is the prerequisite every worker depends on; it can’t itself be parallelized away.

The part I can’t fix yet

Nothing stops recurrence. Auto-learn keeps minting, so this is a periodic pass, not a one-time cleanup — the same way a memory store needs occasional compaction, not a single dedup.

The industry direction that would actually fix it is retrieval-based loading: instead of putting all N skill descriptions in context every turn, embed them and retrieve only the top-k relevant to the current task. That caps both the context tax and the selection tax regardless of library size. The Toolshed paper works through exactly this for tool-equipped agents. Until agent frameworks ship dedup-on-write or retrieval-on-demand, a scheduled consolidation pass is the pragmatic stopgap.

The broader lesson is one worth internalizing about any self-improving system: a feature that accumulates without ever consolidating will eventually degrade the thing it was meant to improve. Measure it, or it compounds against you.

Source

• Toolshed: Scale Tool-Equipped Agents with Advanced RAG-Tool Fusion — retrieval-based tool/skill loading
• Anthropic — Writing effective tools for agents — why tool/skill descriptions are the selection surface
• Anthropic — Effective context engineering for AI agents — the always-loaded-context cost model

Two mechanisms, one visual result

There are exactly two ways a path becomes clickable in a terminal, and they are not the same thing:

That last row is the whole game. OSC 8 declares. Regex guesses.

My coding agent (OMP) uses OSC 8: it knows the exact path it’s printing, so it wraps it in an OSC 8 hyperlink escape sequence before the bytes ever hit the terminal. Node’s url.pathToFileURL(p).href does the encoding. Raw shell output (ls, git, find, build logs) emits no such thing — a path there is just plain text bytes. For those, the terminal’s only route to clickability is hyperlink_rules: regexes it runs over the screen to auto-detect links.

WezTerm’s default hyperlink_rules match URLs (http, mailto, …) but never bare file paths. That’s the gap.

Fix part 1: hyperlink_rules for any command

hyperlink_rules is the universal lever precisely because it doesn’t need the program to cooperate — it works on whatever is already on screen. Start from the defaults (so URLs keep working) and add file-path rules:

config.hyperlink_rules = wezterm.default_hyperlink_rules()
table.insert(config.hyperlink_rules, {
  regex  = [[[A-Za-z]:[\\/][^\s"'<>|]*]],   -- C:\Users\... or C:/Users/...
  format = 'file://$0',
})

This works — until a path has a space. The [^\s…] stops at the first whitespace, so C:\OneDrive - AMD Inc\file.md links only as far as C:\OneDrive.

Test the regex against the same engine the terminal uses

Before editing the live config, you can test WezTerm regexes for free: WezTerm uses the Rust regex crate, and so does ripgrep. So rg -o shows you the exact span WezTerm will linkify:

rg -o -N -e '[A-Za-z]:[\\/][^\s"'"'"'<>|]*' paths.txt

-o prints only the matched span — which is exactly the clickable region. This turns “edit config, reload, squint at the screen” into a tight unit-test loop. One caveat it also surfaces: the Rust crate has no lookahead, so any pattern you design has to live within that.

Handling spaces: anchor on the extension, not on whitespace

The insight that beats the space problem: a file path runs until its extension, not until the next space. Anchor the regex on .ext at a word boundary and interior spaces become legal:

config.hyperlink_rules = wezterm.default_hyperlink_rules()
-- Rule 1: extension-anchored — interior spaces allowed.
table.insert(config.hyperlink_rules, {
  regex  = [[(?:[A-Za-z]:|~)[\\/][^\r\n"'<>|]*\.[A-Za-z0-9]{1,8}\b]],
  format = 'file://$0',
})
-- Rule 2: whitespace-stop fallback — extensionless dirs.
table.insert(config.hyperlink_rules, {
  regex  = [[(?:[A-Za-z]:|~)[\\/][^\s"'<>|]*]],
  format = 'file://$0',
})

Verified with rg -o against a corpus:

Rule 1 must come first: on an overlap, WezTerm takes the earlier rule, so spaced files win over the whitespace-stop fallback.

The click needs somewhere to go. A single open-uri handler routes any file:// link to the editor:

wezterm.on('open-uri', function(_w, _p, uri)
  local path = uri:match('^file:///?(.+)$')
  if not path then return end                    -- not a file link → default handler
  path = path:gsub('%%(%x%x)', function(h) return string.char(tonumber(h,16)) end)
  if path:match('^~') then path = home .. path:sub(2) end
  path = path:gsub('/', '\\')
  wezterm.background_child_process({ 'cmd.exe', '/c', 'code', path })
  return true
end)

The residual, and why regex can’t fix it

One case stays broken: a spaced, extensionless directory — the exact thing your prompt shows, PS C:\Users\me\Process Dashboard>. Rule 1 needs an extension; rule 2 stops at the space. And no regex can fix this, because in raw text C:\Users\me\Process Dashboard and then... is genuinely ambiguous — there is no signal for where the directory name ends and the prose begins. The terminal is guessing, and it has nothing to guess with.

This is the wall that separates “guess” from “declare.” To get past it you have to stop guessing.

Fix part 2: declare the prompt’s path with OSC 8

The prompt is output you control — so emit OSC 8 there, the same way the coding agent does. .NET’s [uri] gives you pathToFileURL-equivalent encoding (spaces → %20):

function prompt {
    $gt = '>' * ($nestedPromptLevel + 1)
    $p  = $executionContext.SessionState.Path.CurrentLocation
    if ($env:WEZTERM_PANE -and $p.Provider.Name -eq 'FileSystem') {
        $e   = [char]27
        $uri = ([uri]$p.ProviderPath).AbsoluteUri   # file:///C:/Users/me/Process%20Dashboard
        return "PS $e]8;;$uri$e\$p$e]8;;$e\$gt "
    }
    return "PS $p$gt "
}

Two guards matter. $env:WEZTERM_PANE (set only inside WezTerm) means other terminals get a plain prompt with no stray escape bytes. $p.Provider.Name -eq 'FileSystem' skips non-filesystem locations like HKLM:\ where a file:// URI makes no sense. Now the whole Process Dashboard cwd is one clickable link — spaces and all — because the producer declared the exact target instead of leaving the terminal to guess.

The model worth keeping

hyperlink_rules = universal but space-blind. OSC 8 = per-command but exact.

Regex works on any command’s output without cooperation, but must infer boundaries — so it fumbles spaces and extensionless directories. OSC 8 is flawless — spaces, directories, survives pipes and ssh — but only for output whose producer you can make emit it.

Use the regex as the always-on baseline for the whole terminal; reach for OSC 8 on the specific surfaces you own (your prompt, a wrapper around a command you run constantly).

Don’t reinvent it where you don’t have to

If you want OSC 8 for an arbitrary command without writing a wrapper, mash/osc8wrap is a pipe filter: somecmd | osc8wrap. I skipped it here because the two surfaces I actually cared about — every command’s output (regex) and my prompt (a function I already control) — needed no new dependency. But for a one-off “make this command’s paths exact,” it’s the boring, correct tool.

Source

• WezTerm hyperlink_rules and the open-uri event
• OSC 8 hyperlink spec (Egmont Koblinger)
• Rust regex crate — the engine behind both WezTerm and ripgrep
• mash/osc8wrap — OSC 8 pipe filter

The naive fix — show cost-per-turn in the status line — doesn’t work. Raw per-turn cost ÷ per-turn context growth is a ratio with a denominator that is often near zero and sometimes negative (context shrinks after compaction), so the number swings 40x between adjacent turns for no behavioral reason. A fixed time window (say, “cost over the last 10 minutes”) is stable but laggy — it keeps a stale cheap turn from three minutes ago averaged into a number that’s supposed to tell you what’s happening now.

The metric

The thing that actually works is an exponentially-weighted moving average of the numerator and denominator separately, not of the ratio:

rate = ewma(turn_cost) / ewma(net_context_growth)   [× 1e6, reported as $/1M]

Each new turn moves both EWMAs toward its own values with weight alpha (0.4 here) — so the newest turn has real influence (the number is live) while the denominator stays a smoothed aggregate rather than division-by-near-zero noise (the number isn’t chaotic). This is the standard rate-smoothing pattern from systems monitoring, applied to something monitoring dashboards don’t usually track: the marginal cost of an LLM agent’s own memory.

Alongside the smoothed rate, the exact cost of the last completed turn is shown with zero smoothing — the ground truth, next to the trend.

Rendered in the status line, it looks like:

⛁141K  Δ$4.72  🟡$308/M

• ⛁141K — live absolute context size
• Δ$4.72 — exact cost of the last turn, no smoothing
• 🟡$308/M — EWMA $/1M-ctx-growth, with a severity glyph

The bands (derived first-principles from a representative model’s per-token pricing and cache economics — not a published benchmark, and deliberately made configurable since they’re pricing-dependent):

The peak that motivated this whole thing was $924.67/M in a session that had ballooned to a large context and then hit a cache miss on a turn that added almost nothing — full-price resend of the whole window, for close to zero retained value. That’s the number a glance at the status line should catch before it happens three more times in the same session.

The bug that made this a real debugging story, not just a formula

The obvious way to compute “current context size” from an OMP/Pi-style agent’s session state is to walk the assistant message history and sum two fields every message carries:

message.contextSnapshot = { promptTokens, nonMessageTokens }

nonMessageTokens looks like exactly what its name says: tokens outside the message history — system prompt, tool definitions, injected memory. The natural instinct is total = promptTokens + nonMessageTokens. I built it that way first. It showed 187k on a session OMP’s own native footer reported as 141k.

Tracing it across every turn of a live session confirmed the actual relationship: promptTokens === usage.input + usage.cacheRead + usage.cacheWrite exactly, on every single turn. promptTokens is the full billed context for that turn. nonMessageTokens (a near-constant ~45k — system prompt + tool schemas + memory, in this setup) is a subset of promptTokens, not an addend. Adding them double-counts the constant term.

The interesting part is why this bug is invisible in the sibling extension it was copied from. That extension only ever computes deltas between turns (this_turn_ctx - previous_turn_ctx) to drive a cost-per-growth ratio. A near-constant offset cancels perfectly in a delta — (promptTokens_a + K) - (promptTokens_b + K) = promptTokens_a - promptTokens_b. So the formula is correct for the thing it’s used for there, and wrong the moment you reuse it to render an absolute gauge instead of a difference. Same code, same field names, one consumer where the bug can’t show and one where it’s off by 33%. The fix was one line: drop + nonMessageTokens, use promptTokens alone — which is also exactly what the platform’s own built-in context-percentage indicator does.

Lesson, generalized past this one extension: a formula validated against one use of a shared value is not validated against every use of that value. If you lift a computation for a new purpose, re-derive from the field semantics, don’t just trust that it already worked somewhere else.

The counter-intuitive part

After restarting a session (resume, not fresh start), the rate drops — even though the agent is, in some naive sense, “carrying the same context” it had before. This looks backwards until you remember what the metric actually measures: growth-efficiency, not context volume. A resumed session’s initial context arrives via cache reads, which are nearly free and add ~zero net new tokens relative to what was already established. The denominator (growth) stays near zero and the numerator (cost) stays low too — cheap turn, little growth, unremarkable ratio. The number was never telling you how much context you’re carrying (that’s what the absolute ⛁141K gauge is for); it’s telling you how expensively you’re currently adding to that pile. Those are different questions, and conflating them is exactly the trap the naive “show me cost per turn” version falls into.

Design notes

• Standalone, not a patch to existing code. This lives as its own extension rather than modifying the retro tool it borrows the branch-walking pattern from — that tool was stable and I didn’t want a display feature risking a regression in something unrelated. It replays the session’s message history read-only, so it’s stateless: no baseline to seed, safe across restarts and resumes by construction.
• Configurable bands, not hardcoded. Cost thresholds are a function of model pricing, which changes. Hardcoding $30/$150/$400 as constants would have quietly gone wrong the next time the underlying model’s per-token cost shifted. They’re read from a small config file, with strict validation and a safe fallback to the derived defaults on anything malformed.
• Minimal display, no verbs. The first version had color-coded action hints (“consider branching”). Cut in favor of just the number and a glyph — the point was a glanceable gauge, not another thing telling you what to do.

Source

• Public prior art on the underlying cost curve: Expensively Quadratic, “Context Tax: Step 12 Costs 42x Step 1”, tianpan.co on quadratic agent cost
• Earlier post in this series on the same context-cost-visibility thread: /ai/agents/productivity/tools/2026/07/20/omp-pause-extension-and-feature-discovery.html

</content> </invoke>

Here’s the whole rabbit hole: the tool that looks right (nircmd) places windows in the wrong coordinate space on a scaled display, the fix is a DPI-awareness flag most examples omit, and there’s a second gotcha where a cross-monitor move rescales the window mid-flight.

First attempt: nircmd, the boring choice

nircmd (NirSoft, ~2003) is the Lindy-effect answer for scripting Windows from the command line. It moves and sizes a window by title:

nircmd win setsize stitle "ssh-server" 0 0 957 597

I computed a two-up-plus-bottom layout from the monitor’s work area and fired three of these. On the laptop panel (100% scale) it was perfect. On the external 4K at 150% scale, the windows flew above the visible area. But nircmd returned success for every call.

Diagnosis: read back where the window actually landed

Rule I keep relearning: when a placement tool “succeeds” but the result is wrong, stop guessing and read back the actual geometry. GetWindowRect tells you exactly where the window is:

import ctypes
from ctypes import wintypes
user32 = ctypes.windll.user32

def rect_of(hwnd):
    r = wintypes.RECT()
    user32.GetWindowRect(hwnd, ctypes.byref(r))
    return r.left, r.top, r.right - r.left, r.bottom - r.top

Requested top-left (-1234, -2700); actual (-1403, -3069). Off by 169px horizontally, 369px vertically — and the offset scaled with the monitor’s 150%. That ratio is the tell: this is a DPI-scaling mismatch, not a bug in the coordinates I computed.

Root cause: two processes, two coordinate spaces

Windows has per-process DPI awareness. What GetMonitorInfo reports for a monitor’s rectangle depends on the calling process’s awareness mode:

• System-DPI-aware (SetProcessDPIAware(), the one every old example calls) — you get logical coordinates, scaled by the primary monitor’s factor. On a mixed-DPI setup these do not match physical pixels on the secondary monitors.
• Per-monitor-aware v2 — you get true physical pixels for every monitor.

My script called SetProcessDPIAware() and computed logical coordinates. nircmd is a separate process with its own (different) awareness, so it interpreted my numbers in a different space. Cross-process coordinate hand-off across a DPI boundary is the trap. No amount of coordinate math on my side fixes it reliably, because the two processes never agree on what (-1234, -2700) means.

Fix: do everything in one process, per-monitor-aware v2

The clean fix is to drop the external tool and place windows in-process with SetWindowPos, under the per-monitor-v2 context — so enumerate, place, and verify all share one physical-pixel space:

import ctypes
from ctypes import wintypes
user32 = ctypes.windll.user32

# DPI_AWARENESS_CONTEXT_PER_MONITOR_AWARE_V2 = -4
user32.SetProcessDpiAwarenessContext(ctypes.c_void_p(-4))

SWP_NOZORDER, SWP_NOACTIVATE = 0x0004, 0x0010

def find_hwnd(substr):
    out = []
    proc = ctypes.WINFUNCTYPE(ctypes.c_bool, wintypes.HWND, wintypes.LPARAM)
    def cb(hwnd, _):
        if not user32.IsWindowVisible(hwnd):
            return True
        n = user32.GetWindowTextLengthW(hwnd)
        if n:
            b = ctypes.create_unicode_buffer(n + 1)
            user32.GetWindowTextW(hwnd, b, n + 1)
            if substr.lower() in b.value.lower():
                out.append(hwnd)
        return True
    user32.EnumWindows(proc(cb), 0)
    return out[0] if out else None

def place(substr, x, y, w, h):
    hwnd = find_hwnd(substr)
    if not hwnd:
        return
    user32.ShowWindow(hwnd, 9)  # SW_RESTORE (un-maximize first)
    user32.SetWindowPos(hwnd, 0, x, y, w, h, SWP_NOZORDER | SWP_NOACTIVATE)

Requested (-1234, -2700) → actual (-1234, -2700). Pixel-exact, because there is no longer a coordinate hand-off between two differently-aware processes.

Under v2, the 4K monitor also finally reports its real 3840x2160 from GetMonitorInfo. Under system-DPI-aware it had been reporting a scaled-down 2743x1543 — the same lie that had thrown off the layout math in the first place.

Second gotcha: cross-monitor moves rescale mid-flight

Moving a window from a 100% monitor to a 150% monitor fires WM_DPICHANGED, and well-behaved apps resize themselves in response. So a single SetWindowPos that crosses a DPI boundary sets the position, then the window rescales out from under you — the read-back comes back the wrong size.

The fix is a self-correcting retry: after the move, verify, and if it’s off, place once more. The second call has no DPI transition (the window is already on the target monitor), so it sticks:

def place(substr, x, y, w, h):
    hwnd = find_hwnd(substr)
    if not hwnd:
        return
    user32.ShowWindow(hwnd, 9)
    r = wintypes.RECT()
    for _ in range(2):
        user32.SetWindowPos(hwnd, 0, x, y, w, h, SWP_NOZORDER | SWP_NOACTIVATE)
        user32.GetWindowRect(hwnd, ctypes.byref(r))
        if abs(r.left - x) <= 2 and abs(r.right - r.left - w) <= 2:
            break

Bonus: matching a monitor by name

I wanted --monitor acer to target a specific physical display, not an index that reshuffles when I dock. The intuitive call returns nothing useful:

# DeviceString here is "Generic PnP Monitor" — useless
user32.EnumDisplayDevicesW(adapter, 0, dd, 0)

The EDID vendor code lives in the device interface path, which you only get by passing EDD_GET_DEVICE_INTERFACE_NAME (flag 1) as the last argument:

import re
user32.EnumDisplayDevicesW(adapter, 0, dd, 1)   # flag 1, not 0
m = re.search(r"DISPLAY#([A-Z]{3})", dd.DeviceID or "")
code = m.group(1) if m else None   # e.g. "ACR", "DEL", "CMN"

Those three-letter codes are the PNP vendor IDs — ACR = Acer, DEL = Dell, CMN = Chi Mei / Innolux (common laptop panels). Map them to friendly names and you can select a monitor by manufacturer.

Don’t-reinvent-the-wheel check: why a script at all?

Before writing any of this I checked the established options, because a general tiling manager would beat a bespoke script if one fit:

For a handful of specific named windows, the script is the genuine structural fit. If I wanted general zone-snapping for every app, FancyZones would win. The point of the exercise wasn’t to build — it was to confirm building was correct, and it was for this narrow case.

Ergonomic aside

Since the script picks a monitor and a layout, it’s worth encoding the ergonomics too: put the two peer windows (server and client, which you diff row-against-row) side by side at eye level, so comparison is a horizontal glance and your neck stays neutral. Stacking is better for a single long log, ideally on a portrait monitor. The eye-level display — not the laptop panel you look down at — is where the windows you watch for long stretches belong.

Takeaways

• On multi-monitor Windows, DPI awareness is a coordinate contract. A window-placement tool that runs in a different process with different awareness will land windows in the wrong space, and report success doing it.
• SetProcessDpiAwarenessContext(-4) (per-monitor v2) + in-process SetWindowPos keeps enumerate/place/verify in one space.
• Cross-monitor moves fire WM_DPICHANGED; place twice.
• EnumDisplayDevices needs flag 1 to expose the EDID vendor code for name matching.
• Always read back geometry — a placement tool’s exit code is not evidence the window went where you asked.

Source

• nircmd — NirSoft command-line Windows utility
• SetProcessDpiAwarenessContext / DPI_AWARENESS_CONTEXT
• WM_DPICHANGED
• EnumDisplayDevices (note the EDD_GET_DEVICE_INTERFACE_NAME flag)
• PNP vendor ID list
• komorebi · FancyZones

wu 'cd ~/repo && git show SHA:path/file | grep "one|two"'

…and WSL greets you with rtr: command not found or unexpected EOF while looking for matching quote. The command is fine. The quoting died three shells ago.

An earlier post covered the mechanical fix for multi-line scripts in this same wu wrapper. This one is about the underlying why — the layered-quoting model that explains the whole class of failures, and the one principle that dissolves it.

Why this breaks

When you invoke a Linux command from a Windows wrapper, the string you typed is re-parsed by three different parsers before a single byte reaches your program:

graph LR
  A[MSYS / git-bash] --> B[cmd.exe]
  B --> C[wsl.exe arg split]
  C --> D[bash -lc]

Each layer has its own idea of what a quote and a pipe mean:

The classic failure: grep "one|two" — cmd.exe sees the | outside any quoting it recognizes (it doesn’t honor single quotes), interprets it as a pipe, and tries to run two as a separate program. Hence two: command not found. Your carefully-quoted regex never survived layer two.

This is not a bug in any one tool — it is the unavoidable result of stacking parsers with incompatible quoting rules. Microsoft’s own WSL issue tracker has years of threads on it (#3284, #11635, #1625). There is no combination of escaping that is robust across all of them.

The fix: send the command as bytes, not as arguments

Arguments get parsed. stdin does not. If you pipe your command into bash over stdin, none of the intermediate layers get to tokenize it — they only see an opaque byte stream. bash reads it as a script and runs it verbatim.

A tiny wrapper makes this ergonomic. Here is the whole thing (wu.cmd):

@echo off
if not defined WU_TIMEOUT set WU_TIMEOUT=180
if "%~1"=="" (
    rem no args: read the command from stdin
    wsl -- timeout -k 5 %WU_TIMEOUT% bash -l -s
) else (
    rem args: run them directly (fine for SIMPLE commands only)
    wsl -- timeout -k 5 %WU_TIMEOUT% bash -lc %*
)

Two modes fall out of this:

Simple command → arg mode, double quotes:

wu "echo hi; whoami"

Anything with pipes, quotes, $vars, or colon:paths → stdin mode:

printf '%s\n' 'cd ~/repo && git show SHA:path | grep "one|two"' | wu

The printf '%s\n' '…' hands one literal line to wu’s stdin. bash -l -s reads it as a script. The |, the "quotes", the $vars all survive because nothing between you and bash was allowed to parse them.

Heredocs work too, which is lovely for multi-line scripts:

wu <<'EOF'
cd ~/repo
for f in *.log; do
  grep -c ERROR "$f" | sed "s/^/$f: /"
done
EOF

The 'EOF' (quoted) means even $f passes through untouched — the remote bash expands it, not your local shell.

The rule of thumb

• Reaching for a pipe, a nested quote, a $var, or a path:with:colons? Use stdin: printf '%s\n' '…' | wu.
• Just a plain command or two? wu "cmd; cmd" is fine.

Once you internalize “arguments get re-parsed, stdin doesn’t,” the whole class of Windows↔WSL quoting bugs disappears. The same principle applies well beyond WSL: any time you’re shipping a command across a boundary that re-tokenizes (SSH, docker exec, kubectl exec, CI YAML), prefer a stdin/heredoc channel over cramming it into arguments.

Source

• Microsoft WSL quoting threads: #3284, #11635, #1625
• A Guide to Invoking WSL — Microsoft Command Line blog
• bash -s reads the script from stdin; bash -lc parses its argument — the whole trick is choosing the former for anything non-trivial.

First attempt: reinventing something that already existed

My first instinct was to write an extension from scratch: hook before_agent_start and tool_call, hold an unresolved promise until a /resume command released it. Textbook cooperative pause gate. I built it, wired it into config, and mid-smoke-test a full-screen “P A U S E D” splash appeared that I hadn’t written.

OMP already ships a native /pause. It freezes the main agent, every subagent, and the advisor via a process-global gate (agentPauseGate, exported from @oh-my-pi/pi-agent-core), polled at the two safe boundaries every agent loop passes through: before a model call, and before a tool call starts. My hand-rolled version only guarded the current session’s own two events — it didn’t touch subagents or the advisor at all. Strictly worse, and redundant.

Lesson, not for the first time: grep the tool’s own source for the feature name before building it.

node -e "
const fs=require('fs'), path=require('path');
function walk(dir){
  for (const f of fs.readdirSync(dir, {withFileTypes:true})) {
    const p = path.join(dir, f.name);
    if (f.isDirectory()) walk(p);
    else if (f.name.endsWith('.js') && fs.readFileSync(p,'utf8').includes('PAUSED')) console.log(p);
  }
}
walk('node_modules/@oh-my-pi/pi-coding-agent');
"

I deleted the extension, the config file, and the log. Total loss: about twenty minutes and some context.

The actual gap: fullscreen only

Native /pause does exactly two things in its handler: agentPauseGate.pause(), then await runPauseScreen(ctx) — and runPauseScreen is a hardcoded fullscreen overlay (fullscreen: true, anchor: "top-left", maxHeight: "100%"). No flag, no config key, no seam. If you want the freeze without losing sight of your terminal — say, you’re mid-read of a long diff or log output and just want to stop the agent from touching anything for a minute — there’s no way to ask for that from the outside.

That’s a real gap, and it’s not something I can fix by forking OMP’s source. So two things, in order:

1. File the actual feature request upstream, with exact file/line references, so it doesn’t get lost as “works for me, closing.”
2. Build the workaround I actually needed in the meantime — reusing the same gate the native command drives, just with a different display.

Reuse the primitive, replace the display

agentPauseGate is a plain exported singleton with a small surface:

export class AgentPauseGate {
  get paused(): boolean;
  get pausedAt(): number | undefined;
  pause(): boolean;                          // false if already paused
  resume(): number | undefined;              // pause duration in ms, or undefined
  onChange(listener: (paused: boolean) => void): () => void;
  async waitUntilResumed(signal?: AbortSignal): Promise<void>;
}
export const agentPauseGate = new AgentPauseGate();

Since it’s importable from @oh-my-pi/pi-agent-core — the same package the native command imports it from — an extension can drive it directly. Freeze semantics become identical to the builtin (main + subagents + advisor, parked at the next safe boundary) without touching a single line of OMP’s own source. I named the commands /hold / /unhold / /hold-status rather than /pause//resume — OMP’s extension loader silently skips (with a warning) any extension command whose name collides with a builtin, so there’s no “override” path; different names are the only option.

The display side is a setWidget call instead of the fullscreen component — a persistent, ticking status line above the editor instead of a takeover screen:

function widgetLines(): string[] {
  const heldMs = agentPauseGate.pausedAt !== undefined
    ? Date.now() - agentPauseGate.pausedAt : 0;
  return [`⏸ held for ${formatClock(heldMs)} — /unhold to continue (transcript stays visible)`];
}

pi.registerCommand("hold", {
  description: "Pause the agent without covering the screen",
  handler: (_args, ctx) => {
    if (!agentPauseGate.pause()) {
      ctx.ui.notify("[hold] already held", "info");
      return;
    }
    startTicking(ctx); // ctx.setInterval(...) updating the widget every second
    ctx.ui.notify("[hold] agent held — use /unhold to continue", "info");
  },
});

The bug that mattered: a race at the turn boundary

First live test looked right — the widget appeared, ticked, no fullscreen takeover. Then I typed a prompt while held: say the word banana. It answered anyway.

agentPauseGate is polled only inside agent-loop.ts, at its own internal checkpoints:

// before each model call within a turn
if (agentPauseGate.paused) await agentPauseGate.waitUntilResumed(signal);
...
// before each tool call
if (agentPauseGate.paused) await agentPauseGate.waitUntilResumed(record.signal);

Sending /hold and then immediately submitting a plain-text prompt can race the loop’s first checkpoint — if the loop already grabbed its “not paused” read before pause() landed, a text-only turn (no tool calls, so the second checkpoint never fires) sails straight through. The fix was a second, earlier gate — the extension’s own before_agent_start hook, which fires before the agent is dispatched at all:

pi.on("before_agent_start", async (_event, ctx) => {
  if (!agentPauseGate.paused) return;
  await agentPauseGate.waitUntilResumed();
});

Verified in a live session afterward: /hold → say the word mango → the “Working…” spinner sat there indefinitely, no output — until /unhold, at which point the queued prompt executed and “mango” printed. Belt and suspenders, but the belt was load-bearing.

Finding the rest of the iceberg

Chasing down /pause meant reading OMP’s entire builtin command registry, and it turned up a lot I’d never used in months of daily driving:

None of these were hidden exactly — they’re all in --help and /hotkeys — but I’d never gone looking. The /pause rabbit hole is what forced the read.

Takeaways

• Grep before you build. A five-minute search of the tool’s own source would have saved the first scrapped extension entirely.
• A missing feature and a missing config knob are different bugs. /pause’s freeze mechanism was exactly right; only its display was inflexible. Filing an upstream issue for the display, and building a stopgap against the real shared primitive, beat reimplementing the whole thing badly.
• Cooperative gates race at boundaries you don’t own. If a shared pause/cancel primitive is polled only inside someone else’s loop, don’t assume your own trigger point is inside that loop too — verify with an actual concurrent test, not a single happy-path try.

Source

• Extension: agent-pause-omp (personal, unpublished) — commands /hold / /unhold / /hold-status
• Upstream feature request: oh-my-pi#6101 — decouple agentPauseGate engagement from the fullscreen runPauseScreen display
• Prior post in this series: /ai/agents/productivity/2026/05/11/slowmo-for-ai-coding-agents.html

I couldn’t find an existing extension that did this, so I built one: session-reminder-omp.

What it does

It’s a small OMP extension that fires arbitrary wall-clock-timed nudges — a notification plus a brief status-bar flash — on whatever cadence you configure, for as long as a session is open. Each reminder is independent: its own name, message, interval, icon, and flash duration. Nothing about it is specific to /shake; that’s just the first thing I needed a nudge for.

Reminders live in a plain JSON config file, ~/.omp/agent/session-reminder.json:

{
	"reminders": [
		{ "name": "shake", "message": "Context has been growing for 10min — consider running /shake to reclaim tokens.", "intervalMs": 600000, "icon": "⏰" },
		{ "name": "stretch", "message": "You've been at this an hour — stand up and stretch.", "intervalMs": 3600000, "icon": "🧘" },
		{ "name": "eyes", "message": "20-20-20: look at something 20 feet away for 20 seconds.", "intervalMs": 1200000, "icon": "👀" },
		{ "name": "hydrate", "message": "Drink some water.", "intervalMs": 2700000, "icon": "💧" },
		{ "name": "posture", "message": "Posture check — shoulders back, feet flat, screen at eye level.", "intervalMs": 1800000, "icon": "🧍" }
	]
}

Once I had the mechanism, the obvious move was to stop thinking of it as a shake-nudge tool and use it for what it actually is: a generic “tell me things periodically while I’m sitting here” utility. So alongside the shake reminder, my own config now nudges me to stretch, blink/rest my eyes, drink water, and check my posture — all things I already know I should do and reliably forget to, because nothing in my environment was timed to a session’s actual duration.

Each entry arms its own timer on session start and clears it on session end:

function arm(entry: ReminderConfig, ctx: ExtensionContext): Timer {
	return setInterval(() => {
		try {
			ctx.ui.notify(entry.message, "info");
			ctx.ui.setStatus(entry.name, `${entry.icon ?? "⏰"} ${entry.name}`);
			setTimeout(() => ctx.ui.setStatus(entry.name, undefined), entry.flashMs ?? 15_000);
		} catch (e) {
			// one bad reminder logs and skips — it doesn't take the others down
		}
	}, entry.intervalMs);
}

Malformed config entries — missing intervalMs, a non-positive interval, a missing message — are skipped individually with a logged reason rather than failing the whole extension. One bad reminder shouldn’t cost you the other four.

The one gap worth naming

The extension nudges; it doesn’t act. There’s currently no supported way for an OMP extension to actually invoke the underlying /shake operation programmatically — only the built-in command controller can call that directly, so even the shake reminder above is a “go run this yourself” message, not an auto-triggered one. I filed that as a feature request upstream (can1357/oh-my-pi#5661) rather than reach for something uglier like monkeypatching the session internals. If an extension API doesn’t expose something, asking for the API beats routing around the boundary.

A bug that taught me something about extension crash isolation

Worth a specific callout since it surprised me: my first version called ctx.notify(...) and ctx.setStatus(...) directly — except those methods don’t exist at that path; they live under ctx.ui.notify/ctx.ui.setStatus. Every timer tick threw a TypeError, and because that throw happened inside a setInterval callback I’d scheduled myself — not inside the extension’s session_start handler invocation, which OMP does wrap in try/catch — it escaped all containment and crashed the entire session, not just the misbehaving extension.

That’s a sharper edge than it sounds: any extension that schedules its own timers or async work (which the SDK explicitly supports, and which this exact use case requires) can currently take the whole harness down on a runtime error in that code. I fixed my own extension (correct API path, defensive try/catch around every fire callback) and filed the underlying gap separately (can1357/oh-my-pi#5664) since it’s a real isolation hole, not something specific to my mistake.

Whether the reminders are even good advice

Before shipping the wellness set as defaults, I checked whether “everyone knows” habits like the 20-20-20 rule actually hold up. Turns out it’s more mixed than folklore suggests: recent ophthalmology literature shows it measurably helps accommodative eye fatigue (the focusing muscles) but does little for the dry-eye/reduced-blink-rate symptoms that dominate actual digital eye strain complaints (PubMed 35963776, 36473088). Separately, a 2025 comparison of break-taking techniques found structured Pomodoro/Flowtime cadences outperform unstructured self-regulated breaks for sustained focus. None of that changes what I shipped — 20-20-20 is still cheap and better than nothing — but “everyone knows you should do X every 20 minutes” was worth five minutes of verification before it became a default in my own tooling.

Source

• session-reminder-omp — the extension
• can1357/oh-my-pi#5661 — feature request: expose shake() to extensions
• can1357/oh-my-pi#5664 — bug: extension-scheduled callbacks aren’t crash-isolated

</content>

“We fixed this before” is a dangerous sentence to trust literally. It usually means one of two things: the same bug came back, or a similar-looking bug has a different cause this time. This one was the second kind, and finding that out took a longer road than it should have — mostly because I kept re-verifying an old fix instead of asking what had changed since it was applied.

First wrong turn: assuming the fix from last time still fits

There’s an OMP extension in this setup called agent-hora-omp that swaps color themes based on time-of-day (built around Vedic hora / planetary-hour timing — a previous post covered it). It had caused a theme bug before, tied to forcing a dark palette during certain hours regardless of the configured setting. Given “we fixed this before,” it was the obvious first suspect.

It wasn’t. A quick check of its log file showed the last entry was ten days old. The extension hadn’t run today at all. Zero evidence, but I’d already spent several tool calls reading its source before checking the log timestamp — which should have been the first thing I looked at, not the third.

Lesson: when a system has multiple moving parts capable of producing the same symptom, check activity recency before plausibility. A component that hasn’t executed today cannot be today’s root cause, no matter how good its prior track record as a suspect.

Second wrong turn: matching on symptom text instead of terminal

A GitHub issue search turned up something that looked promising: #2365 — TUI output renders with unexpected black background blocks in Ghostty. Same visual symptom — a black box appearing in an otherwise-correctly-themed terminal. Before chasing the fix in that thread, the terminal in the screenshot needed a second look: it wasn’t Ghostty, it was WezTerm. Different terminal, different rendering pipeline, different bug — a coincidence of symptom, not cause.

Lesson: “the same bug in another terminal” is a red herring until you’ve confirmed you’re looking at the same terminal. Visual symptoms (black boxes, missing colors, garbled glyphs) are terminal-agnostic descriptions of what could be several unrelated root causes underneath.

The actual mechanism

Once both false leads were eliminated, tracing the OMP source directly (rather than searching issue trackers for prior art) turned up the real chain:

1. OMP determines whether to render light or dark by calling a detectTerminalBackground() function with three tiers: an async OSC 11 terminal query, a COLORFGBG environment variable check, and a macOS-only system-appearance check.
2. On Windows, tier 3 doesn’t apply. Tier 1 (OSC 11) is asynchronous — it sends an escape sequence and waits for the terminal to answer. If the response hasn’t arrived by the time OMP needs an answer, that tier is skipped.
3. If COLORFGBG isn’t set, all three tiers come up empty and the function silently falls back to "dark".
4. Most UI elements (banner text, tips) don’t paint an explicit background — they render on whatever the terminal already shows, which in this case was WezTerm’s actual light GruvboxLight scheme. They looked correctly themed by accident.
5. The bash tool’s result box explicitly sets a background color from the resolved theme’s toolErrorBg token. Resolved theme: dark-volcanic. Its toolErrorBg is a dark maroon. That’s the box in the screenshot.

So the terminal was light. OMP’s theme resolution was dark. Nothing was actually broken in the sense of a crash or a config typo — it was a startup race that sometimes loses, which is exactly the kind of bug that “gets fixed” and then reappears months later under slightly different circumstances, because the underlying race was never removed, just avoided.

Why the previous fix didn’t cover this

There already was a COLORFGBG auto-detection block in the PowerShell profile — added specifically to give tools like OMP a deterministic signal instead of relying on the OSC 11 race. It worked. It also only checked Windows Terminal’s settings file:

$_wtCfg = "$env:LOCALAPPDATA\Packages\Microsoft.WindowsTerminal_8wekyb3d8bbwe\LocalState\settings.json"
if (!$env:COLORFGBG -and (Test-Path $_wtCfg)) {
    $_scheme = (Get-Content $_wtCfg -Raw | ConvertFrom-Json).profiles.defaults.colorScheme
    $env:COLORFGBG = if ($_scheme -match 'light') { '0;15' } else { '15;0' }
}

The primary terminal had since moved to WezTerm. This block was still technically working — for a terminal that wasn’t being used anymore. It never errored, never warned, just quietly detected nothing useful and let COLORFGBG stay unset, which is exactly the condition that lets the race matter again.

Compounding it: theme switching had also moved to a pair of shell functions, tlight / tdark, that hot-edit .wezterm.lua directly and rely on WezTerm’s live config reload:

function Set-WeztermColorScheme {
    param([Parameter(Mandatory=$true)][string]$Scheme)
    $cfg = "$HOME\.wezterm.lua"
    $content = Get-Content $cfg -Raw
    $updated = $content -replace "config\.color_scheme\s*=\s*'[^']*'", "config.color_scheme  = '$Scheme'"
    Set-Content $cfg $updated -Encoding utf8 -NoNewline
}

This function changes what the terminal looks like. It never touched COLORFGBG, so it had zero effect on what OMP (or anything else reading that variable) believes the appearance is. Two systems, both individually correct, silently disagreeing.

The fix

Two changes, both small:

1. Make Set-WeztermColorScheme export COLORFGBG when it switches schemes, so future shells and tools spawned after a tlight/tdark call get a deterministic signal instead of relying on the race:

function Set-WeztermColorScheme {
    param([Parameter(Mandatory=$true)][string]$Scheme)
    $cfg = "$HOME\.wezterm.lua"
    $content = Get-Content $cfg -Raw
    $updated = $content -replace "config\.color_scheme\s*=\s*'[^']*'", "config.color_scheme  = '$Scheme'"
    if ($updated -eq $content) { Write-Warning "No color_scheme line found in $cfg"; return }
    Set-Content $cfg $updated -Encoding utf8 -NoNewline
    # Bypass OMP's terminal-background auto-detect (OSC 11 races on Windows) entirely.
    $env:COLORFGBG = if ($Scheme -match 'Light') { '0;15' } else { '15;0' }
    "OK: WezTerm color scheme set to '$Scheme'. COLORFGBG=$env:COLORFGBG"
}

2. Make the profile’s startup detection check WezTerm’s live config first, falling back to Windows Terminal only if that’s absent:

if (!$env:COLORFGBG) {
    $_wtLua = "$HOME\.wezterm.lua"
    $_wtCfg = "$env:LOCALAPPDATA\Packages\Microsoft.WindowsTerminal_8wekyb3d8bbwe\LocalState\settings.json"
    if (Test-Path $_wtLua) {
        $_m = Select-String -Path $_wtLua -Pattern "config\.color_scheme\s*=\s*'([^']*)'" | Select-Object -First 1
        if ($_m) { $_scheme = $_m.Matches[0].Groups[1].Value }
    }
    if (!$_scheme -and (Test-Path $_wtCfg)) {
        $_scheme = (Get-Content $_wtCfg -Raw | ConvertFrom-Json).profiles.defaults.colorScheme
    }
    if ($_scheme) {
        $env:COLORFGBG = if ($_scheme -match 'light') { '0;15' } else { '15;0' }
    }
}

Verified with an isolated test script against the live .wezterm.lua — GruvboxLight correctly resolves to COLORFGBG=0;15 before OMP ever gets a chance to race its own detection.

The unglamorous part

Committing the fix surfaced a second, unrelated problem: the file containing Set-WeztermColorScheme wasn’t tracked in the dotfiles repo at all. It existed only as a plain file in Documents, born from a refactor that split shared aliases out of the main profile — a split that never got committed. On top of that, the profile file itself carried 89 lines of accumulated, working-but-uncommitted changes from earlier sessions. And a pre-commit secret scanner blocked the push over a hardcoded personal path in an unrelated Bash helper function, twice, because the same hardcoded path existed in two copies of that function in two different files.

None of that was the bug. All of it had to get cleared before the bug fix could actually land somewhere durable. This is the part that doesn’t show up in “here’s the one-line fix” writeups: half the actual time went to making sure the fix wouldn’t just evaporate the next time a file got regenerated from a stale, unversioned copy.

Takeaways

• A working detection mechanism for terminal A is not a working detection mechanism for terminal B. If a fix reads a specific application’s config file, it silently stops applying the moment the environment moves to a different application — with no error, just quiet non-coverage.
• Env vars set by a switcher function only help processes started after the switch. If you want a live-editing theme switcher to actually inform other tools, it has to touch the same signal those tools read, not just the thing it visually changes.
• “We fixed this before” is a hypothesis, not a fact. Check what changed in the environment since that fix landed before assuming it still covers the current case.
• Untracked “helper” files accumulate real, working logic with zero backup. If a refactor moves code into a new file, that file needs to enter version control in the same breath — not after the next person trips over it being unrecoverable.

Source

• Fix committed to ankitg12/dotfiles (Microsoft.PowerShell_profile.ps1, ps-shared-aliases.ps1)
• OMP theme resolution: packages/coding-agent/src/modes/theme/theme.ts in can1357/oh-my-pi
• Related prior post: /ai/agents/productivity/2026/07/03/hora-aware-ai-agent-omp.html

@echo off
wsl -d Ubuntu-26.04 -- bash -lc %*

It works fine for wu "cd ~/repo && ls". It falls apart the moment the payload is a multi-line script — a heredoc, or a file piped in with nested quotes and $ interpolation. %* round-trips the whole thing through cmd.exe’s argument expansion, which mangles line breaks and quoting before bash ever sees it. The known workaround was: write the script to a Windows scratch path, cp it into WSL, run it, delete it. Three steps for something that should be one.

First instinct: reach for Python

My first move was to rewrite the shim as a Python script that would base64-encode the payload, or write it to a WSL temp file via mktemp and cat, then execute that file with bash. I got partway into building this — argument parsing, a -f/--file flag, a two-step “write then exec” subprocess dance — before testing it against a real multi-line payload.

It didn’t work, and debugging it burned time chasing the wrong thing. mktemp inside a bash -c '...' invocation kept returning empty when I called it through my coding agent’s bash tool, which made me suspect a WSL interop quirk with stdin redirection. It wasn’t WSL. It was the tool: that particular bash tool pre-expands literal $NAME patterns in the command string itself, before any real shell sees it — even inside single quotes. $f and $y were silently evaluating to empty strings inside the harness’s own preprocessing, not inside bash. Switching to a raw subprocess call (bypassing the tool’s string substitution) immediately showed mktemp and command substitution working exactly as expected.

Once that noise was out of the way, the two-file approach did work — but I’d built a whole Python wrapper (argument parsing, temp-file plumbing, cleanup logic) to solve a problem that already has a built-in one-line solution.

The actual fix: bash -s

bash has had first-class support for “read the whole script from stdin” since forever: bash -s (or bash -l -s for a login shell). No temp file, no round-trip, no quoting through cmd.exe at all — the script bytes go straight to bash’s stdin exactly as sent.

$ cat script.sh | wsl -d Ubuntu-26.04 -- bash -l -s

That’s the entire trick. The shim just needs to pick this path when it’s not given a command-line argument:

@echo off
if "%~1"=="" (
    wsl -d Ubuntu-26.04 -- bash -l -s
) else (
    wsl -d Ubuntu-26.04 -- bash -lc %*
)

wu "cmd" keeps working exactly as before. wu <<'EOF' ... EOF or cat script.sh | wu now streams the whole script through stdin, untouched:

$ cat <<'EOF' | wu
cd ~/repo
cat <<'INNER' > foo.txt
literal $HOME and "quotes" and `backticks` survive here
INNER
ls -la
EOF

Every $, backtick, and quote in that payload comes out the other side exactly as typed, because it’s never been command-line text — it’s just bytes on a pipe.

The lesson

I skipped a “does something already do this” check before writing code, and paid for it twice: once in wasted implementation effort, once in wasted debugging effort chasing a false lead (WSL stdin quirk) caused entirely by my own test harness’s string substitution, not by the thing I was actually building. The fix ended up being four lines in an existing file with zero new dependencies, because bash -s was already the right tool — I just hadn’t asked whether it existed before reaching for a new one.

Source

• Shim: ~/.local/bin/wu.cmd (personal dotfiles, not public)
• bash(1) — -s flag: “If there are no operands, -s causes bash to read commands from standard input.”
• Using WSL to Launch Several Bash Commands from an Application (Rick Strahl) — same underlying problem (getting a real multi-line bash session going from a Windows host app) from a different angle.
• az.cmd truncates multi-line arguments on Windows — the exact same class of bug: a .cmd shim silently mangling multi-line payloads passed as command-line args, on a much bigger project.
• Bypass npm .cmd shim on Windows to preserve multi-line prompts — another AI-agent tool hitting the identical Windows .cmd-shim-eats-newlines failure mode, fixed the same way (stop routing the payload through argv).

The AFK toggle I built in May required remembering to type /afk before stepping away. Half the time I forgot — I’d just get up, and the agent would sit idle waiting for a prompt that never came. The fix isn’t a better reminder, it’s removing the step: detect that I’ve actually left the desk and flip the switch automatically.

The missing piece

/afk and /back already did everything needed once engaged — status bar indicator, autonomy prompt injection, guard against double-engagement. What was missing was the trigger. Manual commands only fire if you remember to fire them, and “remember to tell the computer you’re about to forget about the computer” is a bad UX pattern.

The obvious signal already existed on the machine: ActivityWatch, which I already run for time tracking, ships aw-watcher-afk — a small watcher that samples mouse/keyboard activity and writes afk/not-afk events to a local bucket, queryable over a REST API on localhost:5600. No new dependency, no new permission prompt, just a bucket that was already being written to.

What it does

Same /afk / /back commands as before, plus:

• A 15-second poll of ActivityWatch’s AFK bucket
• After a sustained 2-minute AFK reading (not the first tick — a 2-minute debounce avoids auto-engaging because you looked away to read a Slack notification for 20 seconds), it calls the exact same engage() path as typing /afk
• The moment activity resumes, it calls the exact same disengage() path as /back — but only if the current engagement was auto-triggered. If you typed /afk yourself and then, say, walk to get coffee and the AFK watcher fires again, it does not silently disengage a session you engaged on purpose.

function engage(ctx: ExtensionContext, viaAuto: boolean): void {
  if (afkActive) return;
  afkActive = true;
  autoEngaged = viaAuto;
  ctx.ui.setStatus(STATUS_KEY, viaAuto ? "AFK 🔴 auto" : "AFK 🔴");
  ctx.ui.notify(`[afk] engaged${viaAuto ? " (auto)" : ""}`, "info");
  pi.sendUserMessage(buildAfkPrompt(sessionId), { deliverAs: "followUp" });
}

async function poll(ctx: ExtensionContext): Promise<void> {
  const status = await fetchLatestAfkStatus(config);
  if (status === "afk") {
    afkSince ??= Date.now();
    if (!afkActive && Date.now() - afkSince >= config.debounceMs) {
      engage(ctx, true);
    }
    return;
  }
  afkSince = undefined;
  if (afkActive && autoEngaged) disengage(ctx);
}

The manual and automatic paths share engage()/disengage() — there’s exactly one code path that does the actual work, and two ways to trigger it.

Bucket auto-discovery, not a hardcoded name

ActivityWatch names buckets <watcher>_<hostname> — e.g. aw-watcher-afk_MYMACHINE. Hardcoding that string ties the extension to one machine. Instead, the extension queries GET /api/0/buckets/ once, finds whichever bucket has type: "afkstatus" (the type is stable; the name isn’t), and caches the result for the life of the process:

let discoveredBucket: string | undefined;

async function discoverAfkBucket(baseUrl: string): Promise<string | undefined> {
  if (discoveredBucket) return discoveredBucket;
  const res = await fetch(`${baseUrl}/`);
  const buckets: unknown = await res.json();
  for (const value of Object.values(buckets)) {
    if (isAwBucketInfo(value) && value.type === "afkstatus") {
      discoveredBucket = value.id;
      return discoveredBucket;
    }
  }
}

One request per process lifetime, not one per poll — at a 15-second poll interval that’s the difference between 1 request/day and ~5,760.

The mistake worth writing down

I built the first version of this from scratch — new repo, new poller, new prompt injection — without checking whether agent-afk-omp already existed. It did: five commits, already deployed in my OMP config, with the exact /afk//back mechanism this post’s predecessor documented. I overwrote its agent-afk.ts in place before noticing.

The recovery: git show HEAD:agent-afk.ts to pull the original content back, then a manual merge — keep every original function and command signature untouched, add the poller as a new trigger path into the same engage/disengage functions rather than replacing them. Nothing about the original interface changed; /afk and /back behave identically to how they did in May.

The actual lesson isn’t “check git log before writing code” (obviously true, not interesting). It’s that “build X” and “add X to what already exists” are different requests, and the difference only shows up if you check for existing work before deciding which one you’re doing. I had a note (~/Notes/omp-extensions.md) that would have answered this in one line and didn’t read it first.

Source

• agent-afk-omp — the extension, now with auto-detection
• AFK toggle for AI coding agents — the original manual version
• ActivityWatch — the AFK-detection source, already running for time tracking