tmux-agent-control
Skill3 starsChanged 53 days agoMITView on GitHub
Drive a live TUI coding agent in a tmux pane: locate it by process, read its real state, wait for idle, then hand it one complete instruction without corrupting the session. Use when taking over or monitoring an interactive agent turn. Not for one-shot generation — run that headless.
1 other project uses a version of this.
Adopted by
Most recently taken up by
- acupof-ai/arletheir own version, first seen Sep 24, 2026
Other versions1 project uses a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 1
- acupof-ai/arle★ 19same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository59 other files it gives its agents.
- AGENTS.mdAGENTS.md
- agent-harness-settings-paritySkill
- agent-operating-contract-evolutionSkill
- ai-coding-agent-delegationSkill
- arch-improvement-planSkill
- contract-bound-deliverablesSkill
- cross-agent-repair-routingSkill
- define-goalSkill
- delegated-work-acceptanceSkill
- design-an-interfaceSkill
- design-mdSkill
- discord-rich-messageSkill
- dotnet-repo-workflowSkill
- evidence-backed-analytical-writingSkill
- evidence-boundary-disciplineSkill
- find-nearbySkill
- gddSkill
- generated-runtime-repairsSkill
- ghc-searchSkill
- git-auto-sync-pipelinesSkill
- github-code-reviewSkill
- github-repo-managementSkill
- grounded-citationsSkill
- harness-engineeringSkill
- hermes-context-file-loadingSkill
- hermes-modelsSkill
- hermes-updatesSkill
- hoa-introspect-distillSkill
- hoa-introspectSkill
- hoa-skill-reviewSkill
- hoa-skill-workSkill
- html-artifactSkill
- jupyter-live-kernelSkill
- kanban-workflowsSkill
- m365-copilot-cdpSkill
- measurement-campaign-evidenceSkill
- microsoft-officeSkill
- notes-to-prdSkill
- ocr-and-documentsSkill
- official-document-verificationSkill
- omp-headless-orchestrationSkill
- ops-claim-verificationSkill
- package-release-verificationSkill
- plan-to-issuesSkill
- project-phase-closeoutSkill
- report-claim-auditSkill
- research-stream-consolidationSkill
- review-revision-candidatesSkill
- rss-feedsSkill
- skill-library-curationSkill
- skill-porting-and-publishingSkill
- spec-convergenceSkill
- structural-validity-gatesSkill
- subagent-driven-developmentSkill
- systematic-debuggingSkill
- teams-cdpSkill
- whisperSkill
- writing-plansSkill
- writingSkill
The file
We split this skill into the rules it gives an agent
5 rules. About 0 are common, 1 is distinctive, and 4 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 29
NOT for one-shot generation — that is headless pi -p / omp -p ...
- Distinctive: line 39
Never start a second agent in a repo that already has one mid-turn: two writers on one working tree produce a diff nobody can attribute.
- Very specific: line 81
Verify the outcome yourself: When the turn ends: git -C <repo> status --short, git diff --stat, run the repo's own test command, and diff …
- Very specific: line 124
Storage: only omp gc; never delete the harness's session JSONL files by hand.
- Very specific: line 131
A vanished tmux session does not mean the agent died: Check the PID before declaring it gone.
≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Controlling a live TUI agent in tmux
Driving a coding agent (omp, pi, opencode, claude-code) that someone left running in a tmux pane: read its state, wait for it to go idle, then hand it the next instruction without corrupting the session.
When to Use
- the operator says "watch that agent and tell it X when it finishes" / "take over the session in tmux"
- you must monitor a long agent turn and report its real outcome
- a multi-phase delivery (goal → simplify → review → PR → babysit → merge) runs through a driven
agent → follow
gddand use this skill for the mechanics - NOT for one-shot generation — that is headless
pi -p/omp -p ... @prompt.md > out.md(seeomp-headless-orchestration); never route a one-shot through tmux
Pick the control mode first
- Existing interactive pane the operator may also be using → drive it in place (this skill).
- New task, no steering needed → headless
omp -pwith the prompt in a file, output to a file. - New task needing multi-turn steering → own detached session:
tmux new-session -d -s agent-dev -c <repo>, then the same protocol.
Never start a second agent in a repo that already has one mid-turn: two writers on one working tree produce a diff nobody can attribute.
Procedure
- Locate the pane by process, not by a remembered session name.
ps -eo pid,ppid,etime,cmd | grep -E 'omp|pi |opencode'→ PID;ls -l /proc/<pid>/cwd→ repo;tmux list-panes -a -F "#{session_name}:#{window_index}.#{pane_index} pid=#{pane_pid} cmd=#{pane_current_command} cwd=#{pane_current_path}"→ pane. Session groups (new-session -t main,destroy-unattached keep-group) let the session you saw a minute ago disappear while the pane and PID live on in a sibling session. Cache the PID, not thesession:window.panestring, and re-resolve before every send. - Read state instead of guessing it.
tmux capture-pane -p -t <target> -S -80;-S -200for a whole turn,-Jto join wrapped lines into contiguous text. The status line carries model, repo, branch, dirty count, context %, cost — quote it as evidence in your report. - Decide busy vs idle mechanically. Busy if any of: braille spinner glyphs
(
⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏⠿⡿⣟⣯⣷⣻⢿⡷⣾⣽⣶⣇⣏),Subagents · N running,waiting on N job. Idle only when none match AND two consecutive captures hash equal ~15-30s apart. One still frame is not idle — TUI redraw gaps look identical. A session restart or auto-compaction also freezes the pane for minutes: before acting on an idle snapshot, re-capture and check the harness's debug log for a recorded session exit or a scheduled continuation — a restarting turn needs a re-armed watcher, not a "done" verdict. - Send safely; never type blind.
- Tail shows a modal/report hint (
esc,q quit,press … continue) → sendtmux send-keys -t <target> Escape, re-capture, up to 3 tries. - Refuse to send unless the composer prompt (
❯in omp) is visible in the last lines; abort and report instead. A keystroke into an unread dialog confirms something you never saw. - Short instruction:
tmux send-keys -t <target> -l "<text>", then a separatetmux send-keys -t <target> Enter.-lalone does not submit. - Multi-line instruction (a plan or prompt file): write it to a file, then
tmux load-buffer -b p <file> && tmux paste-buffer -b p -t <target> -d, capture to confirm the composer holds it, then sendEnteron its own. Bracketed paste keeps newlines; embedding them insend-keys -lsubmits early or mangles the composer.
- Tail shows a modal/report hint (
- Make the instruction complete on the first send. An agent that already reported "done" will silently narrow scope to what it considers valid. Restate the full ask, name the items it rejected earlier, and require a per-item outcome table (id, file, change, test result) plus an explicit reason for anything it judges invalid rather than skipping it.
- Run it as a background watcher, not a foreground sleep loop.
scripts/tmux-agent-watch.shimplements steps 3-4:TARGET=... MSG=... OUT=... bash scripts/tmux-agent-watch.sh, launched as a background job with completion notification (the harness's own background-job mechanism, orsetsid … &plus a polled status file when there is none). Report job id + artifact dir to the operator. Log every transition and snapshot the pane at idle / after-send / timeout — those files are the proof. - Verify the outcome yourself. When the turn ends:
git -C <repo> status --short,git diff --stat, run the repo's own test command, and diff the agent's per-item table against the operator's ask. Report counts that actually moved, not the agent's summary.- Read the aggregate, not the per-item column. An agent writes "PASS" in every row while the
suite summary says
总计 2579 / 失败 1. Parse the totals line; a per-item PASS table and a green suite are different claims. - Prove pre-existing failures with a worktree, not a stash. The working tree belongs to the
other agent, so never
git stashin it.git worktree add ${TMPDIR:-/tmp}/base-verify HEADin a non-interactive shell, run the failing test there, thengit worktree remove --force. Same failure at HEAD = pre-existing, and you can say so with proof.
- Read the aggregate, not the per-item column. An agent writes "PASS" in every row while the
suite summary says
Process lifecycle & graceful shutdown
Three states with distinct signals and actions — never conflate idle with done:
- Working. The footer shows
Working…; the harness's session transcript grows (mtime < ~60s); the process isR/Swith CPU;omp pslists running workers when subagents are active. Action: wait, do not disturb. - Idle-but-alive — do NOT kill. (a) TUI sitting at the composer
❯: a live session the operator may attach — 0 CPU and no transcript growth but still theirs. (b) Provider wait: the log showsprovider errorthenagent.continue scheduled … automatic-retry(a 429prefill_cap_refusedclears in minutes) or--wait-asyncis awaiting background jobs — the harness self-recovers; give it ~15 min before switching provider. (c) Print-mode turn finishing its final flush — judge by exit code, not by silence. - Done → release. A headless
-prun that exited (notification fired; exit code captured, e.g. 0 = ok, 3 = max-cost) with the final report inoutis finished — the process is already gone, nothing to kill. Only then reclaim storage:omp gc --dry-run, thenomp gc --apply --blobs --wal --stale(add--archive/--compressfor cold sessions). Confirm no live workers withomp psfirst.
Graceful shutdown — never kill <pid> on harness children:
- Daemon-supervised workers/brokers (
__omp_worker_daemon_broker,browser-relay, subagent workers):omp psto find the name,omp ps stop <name> [--timeout N](grace period, then hard kill) — the documented graceful path.omp ps kill <name>only ifstopis refused. This replaces rawkill <pid>; a plain kill leaves orphaned brokers. - TUI session: send
/exit, wait for the shell prompt; never SIGKILL (it drops the in-flight turn and session state). - Headless
-p: let it exit on its own; bound the run up front with--max-time/--max-costinstead of killing mid-turn. If you must abort, prefer SIGTERM over SIGKILL and confirm the session file is intact afterward. - Before
--resume(operator attach):omp session lease --json -- <id>shows which running omp holds the session — never two writers. - Storage: only
omp gc; never delete the harness's session JSONL files by hand.
Pitfalls
- Judge success by exit code and log files, not by stderr. A background job has no TTY, so the
tmux client prints
open terminal failed: not a terminaland every call still succeeds; silence the noise with2>/dev/nulland readwatch.log+ snapshots. - A vanished tmux session does not mean the agent died. Check the PID before declaring it gone;
session groups and
destroy-unattachedmove panes without killing processes. - The agent's own summary is not the operator's definition of done. "All findings applied" means the findings it accepted; items it rejected earlier stay open until someone names them.
- A fresh detached session captures as blank. A new
tmux new-session -dstarts at 80x24 and omp/pi draw only inside the pane's geometry, socapture-panereturns empty lines and the TUI looks dead while its PID is alive.tmux resize-window -t <target> -x 200 -y 50, wait a beat, then capture. - Ctrl-C does not exit the TUI; it only interrupts the current turn. To relaunch (e.g. after a
self-update), send the quit command (
/exitin omp), capture until the shell prompt is back, and only thensend-keys '<agent> …'. Sending the launch command while the agent still owns the composer submits it as a prompt — the agent spends a turn reasoning about its own launch line. - Version: read the TUI banner, not the package manager. omp's own updater stages a release and
shows
vX → vY ✔ next launch, while the version manager can still report the older version because of a minimum-release-age policy. Quit and relaunch to pick up the staged build; verify the banner before sending work. Without attaching, the harness's staged-update manifest (${OMP_HOME:-$HOME/.omp}/update/auto-update.json,{phase, version, target}) reports the same build — check it at each new work phase, and relaunch with the session resumed (omp --resume <id>) when a bump makes restarting worth it. - Unattended repo work needs the approval mode set at launch.
omp --approval-mode yolo(or--auto-approve) skips per-tool prompts; without it a background run stalls on the first write/exec approval nobody is watching. State the guardrails (no commit/push) in the prompt instead of relying on prompts. - A version-manager-installed CLI is not on PATH in a non-interactive shell. Resolve it under
the install root's version directory and call the absolute path; the running process may be a
different version than the one on disk (
omp --helpprints its version first).readlink -f /proc/<pane-pid>/exenames the exact binary driving a pane, andtr '\0' '\n' < /proc/<pid>/environ | grep '^PATH='shows the PATH it was launched with. - A provider error is not a dead session; check the log before restarting. The harness retries a
failed model call by itself — the session log carries
agent turn ended with provider errorand thenagent.continue scheduled … source=automatic-retry(a 429prefill_cap_refused= provider cell at capacity, typically clears in minutes), while the pane still showsWorking…. Spend the stall on work that needs no model (run the repo's gates, read the diff) instead of killing the turn. Only when the harness debug log shows no recovery after ~15 minutes, quit and relaunch withomp --resume <session-id> --model <provider>/<model>to continue on a healthy provider — providers and models are listed in the harness's model registry (seereferences/harness-internals.md). - Don't drive a pane the operator is typing in. Attached and in use → open a detached session of your own; two writers to one composer corrupt the input line and the pending turn.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

