What is tmux-runtime?

Documentation for a tmux-based agent runtime, where tmux is a terminal tool that keeps interactive programs running in panes. It explains how the runtime starts Claude, routes tool requests through safety checks, streams session data, and handles completion.

Use it when changing or diagnosing the tmux agent, session manager, hook bridge, streamed session data, or related server code.

It gives maintainers a reference for understanding and debugging the runtime's moving parts and required versions.

How vmehera123/leashd configures Claude Code

Reuse

Borrowing it

Nothing to install: this file belongs to vmehera123/leashd. Take a copy, put it at the same path in your own repository, and replace the rules that are about this project with yours.

Copy the file

curl -O https://raw.githubusercontent.com/vmehera123/leashd/main/.claude/skills/tmux-runtime/SKILL.md

Clone the repo

git clone --depth 1 https://github.com/vmehera123/leashd

Made for: Claude Code.

Wrote this? Show the measurements

A badge with what this costs and how it scanned, read live from this page, so it follows the numbers instead of freezing them. Markdown for a README, HTML for a documentation site or a project page.

README.md

[![agentmods](https://agentmods.dev/badge/skills/vmehera123/leashd/tmux-runtime/github.svg)](https://agentmods.dev/skills/vmehera123/leashd/tmux-runtime)

Your own site

<a href="https://agentmods.dev/skills/vmehera123/leashd/tmux-runtime"><img src="https://agentmods.dev/badge/skills/vmehera123/leashd/tmux-runtime/github.svg" alt="Measured on agentmods" height="20"></a>

Or the 80×15 button, for a site that already has a row of RSS and ATOM ones. Only the verdict fits; the numbers stay here.

Your own site · 80×15

<a href="https://agentmods.dev/skills/vmehera123/leashd/tmux-runtime"><img src="https://agentmods.dev/badge/skills/vmehera123/leashd/tmux-runtime.svg" alt="Reviewed on agentmods" width="80" height="20"></a>

Per session 116 Skills are progressive disclosure: only the name and description are preloaded; the body loads when the skill is used.

When invoked 3,618 The whole file, excluding the scripts and references it only reads on demand.

Security scan B 1 finding. A grade says what 26 rules found in the file — not that it is safe.

Origin original No closer match found in the catalogue.

Token cost

What it costs to keep this loaded

Counted locally with the o200k_base tokenizer, which is exact for GPT models; Claude uses its own tokenizer and its counts differ. Treat this as one consistent yardstick across the catalogue rather than a bill. Prices are per million input tokens.

Model	Per session	Once invoked
Fable 5.1	$0.00116	$0.03618
Opus 5.5	$0.00046	$0.01447
Sonnet 5.5	$0.00023	$0.00724
Haiku 4.5	$0.00012	$0.00362

Measured 19d ago against content hash 8e3d0a09d15e, method: parsed. Prices are Anthropic first-party input rates as of 2026-10-07, from the pricing page.

Security

Grade B, and why

tmux-runtime scanned grade B with 1 finding against 26 rules in 11 categories — prompt injection, anti-refusal, data exfiltration, privilege escalation, supply chain, agent snooping, system-prompt leakage, SSRF and excessive agency — measured 19d ago.

A static scan of the body, not an audit. Every finding is printed with the line that produced it so you can judge whether it matters here. A mod is markdown that instructs an agent; that is exactly why what it instructs is worth reading.

Reads agent configuration directoriesmediumAgent snooping

.claude/, .codex/, .gemini/ hold keys, settings and other credentials a mod has no legitimate need for.

leashd writes a **managed `--settings`** file and never touches the user's `~/.claude/settings.json`. The opt-in `security-guidance` marketplace plugin (`LEASHD_SECURITY_GUIDANCE_ENABLED`; install ≠ enable) composes its

.claude/skills/tmux-runtime/SKILL.md · 71 lines

How it starts

The opening of the file, as written. The whole thing — 71 lines — stays where its author put it; the contents beside it link to each section on GitHub.

tmux runtime

leashd's default runtime. Instead of leashd owning a subprocess, it runs a real interactive claude TUI inside a tmux pane on a private socket, and the safety pipeline runs over Claude Code HTTP hooks (the --permission-prompt-tool path does not fire in interactive mode). Requires claude ≥ 2.1.259 and tmux ≥ 3.3. Default socket: ~/.leashd/tmux/tmux.sock (LEASHD_TMUX_SOCKET_DIR).

Files

File	Role
`agents/runtimes/tmux.py`	`TmuxAgent` — the `BaseAgent` impl; spawns/follows panes, `cancel_chat()` to kill a live pane by chat
`agents/runtimes/tmux_session.py`	`TmuxSessionManager` — owns all tmux/libtmux interaction and the hook→gatekeeper bridge (~3k lines; the heavy core)
`web/tmux_hooks.py`	thin FastAPI router; Claude Code hooks POST here, it delegates to the session manager
`web/tmux_jsonl.py`	polls the session JSONL and feeds text/cost events back (streaming)
`web/tmux_server.py`	standalone loopback hook receiver for Telegram-only / CLI-only mode (WebUI/multi mode mounts the hook router on the WebUI app instead)

main.py:_maybe_tmux_session_manager builds the shared TmuxSessionManager singleton so the hook receiver and the runtime drive the same manager.

How a turn works

Prompt in — text is injected as keystrokes into the pane's composer. The TUI ignores programmatic answer payloads (updatedInput.answers), so questions/approvals must be answered by driving keystrokes, not by returning data.
Per tool call — a synchronous PreToolUse hook (a command hook running agents/runtimes/hook_relay.py, which POSTs to leashd, retries for 60s while the daemon is away and denies if it gets no verdict) reaches leashd → TmuxSessionManager → ToolGatekeeper (sandbox → policy → approval). The hook's allow/deny response gates the call, and the human/AI wait happens inside this hook. Its timeout is set effectively-infinite (1 year — Claude Code has no infinite hook value and no heartbeat; a daemon restart reaps panes).
Async hooks — UserPromptSubmit, PostToolUse, Stop, StopFailure, SubagentStop, SessionStart, SessionEnd, Notification are fire-and-forget and drive streaming + turn-completion.
Cost — Claude's own figure. The managed settings set a statusLine command that curls claude's statusLine payload to /internal/tmux/hook/StatusLine (routed by pane token only). Each reply gets the rise in cost.total_cost_usd since the previous reply (TmuxClaudeSession.take_usage), so spend after a reply (a background subagent, claude answering it) lands on the next one. There is no estimate: pricing transcript tokens missed about 10% (auto mode's permission classifier and side calls never reach any transcript), so a pane that never reports a statusLine cost reports $0 and logs cost_reported=False. The pane's transcript usage still feeds the logged token counts. Cost left over when a pane dies is never reported (Claude's lastCost in ~/.claude.json has it after a graceful /exit).
Streaming — tailed from ~/.claude/projects/<encoded-cwd>/<session-uuid>.jsonl (see encode_project_dir). Turn end is authoritative on the Stop hook OR the JSONL system/turn_duration record, which Claude writes for every response. TmuxTurn.end_response counts each source separately and the nth report from either ends the nth response: the tailer can trail the hook by a whole response, so a seen-this-response flag re-armed by new text ended a queued follow-up's turn one response early. Interactive transcripts carry no result record. An API error fires StopFailure instead of Stop with a typed error (rate_limit, authentication_failed, model_not_found, …) and writes an isApiErrorMessage assistant record, so the turn ends at once as an error carrying AgentResponse.error_kind, which the engine never retries.

Read the full file on GitHub · 71 lines

Changes

What this file has done since we first saw it

Hashed on every crawl. A supply-chain change to an agent config is a question of when, not whether, so the history is kept rather than the latest state alone.

19d ago Changed · +3 lines 8e3d0a09d15e
28d ago Changed · +2 lines ec5f4317f400
1mo ago Changed · +1 lines 3391869744f4
1mo ago Changed · +5 lines e5810743d4e3
1mo ago Changed · +1 lines 952f1c7cd747
2mo ago First seen · 59 lines · 116 tokens per session scan B 6b0e4b5d8027

Subscribe to this mod's changes

tmux-runtime is a skill published in the GitHub repository vmehera123/leashd (5 stars, last pushed 7d ago), licensed Apache-2.0. It adds 116 tokens to every session and 3,618 once invoked, about $0.0005 per session on Opus 5.5. A static security scan graded it B with 1 finding (reads agent configuration directories). No closer match exists in the catalogue, so it is treated as the original; first seen 2026-08-31.

AI Safety Building agents Debugging agentic-coding ai-agents ai-governance audit-trail automation

nio-scan

Nio code/skill execution-risk scanner. Use when the user wants to scan a file, repo, directory, or skill for execution risks — e.g. "scan this code for risks", "is this file/plugin dangerous", "check this repo for malicious code", "run nio scan on ". Focused single-purpose skill; for other Nio operations use /nio.

core0-io/nio · 81 tokens

nio-doctor

Nio config validator + connectivity check. Use when the user wants to validate their Nio setup — e.g. "run nio doctor", "is my nio config valid / working", "test my OAuth / external endpoint / LLM connectivity", "why isn't my scorer firing". Focused single-purpose skill; for other Nio operations use /nio.

core0-io/nio · 75 tokens

deep-code-review

Use when reviewing current branch for bugs before pushing or merging, when wanting a thorough multi-agent review of local changes, or when preparing work for human review.

Peaky8linders/eu-ai-act-scanner · 34 tokens

pact-bug

Log a bug investigation using PACT's structured bug tracker.

jonathanmr22/pact · 11 tokens

ai-slop-cleaner

Clean AI-generated code slop with a regression-safe, deletion-first workflow and optional reviewer-only mode.

Yeachan-Heo/oh-my-claudecode · 25 tokens

hns-lsel-curator

Local Self-Evolution Loop (LSEL) curator — the CLUSTER + drain engine for the GOOS-local PROPOSE→APPLY seam closure (SPEC-LSEL-LOCAL-EVOLUTION-001). Companion-offset drain of .moai/lessons-inbox.jsonl with a drain-side severity filter that drops the 65% Bash-timeout/sandbox noise, eventkey clustering with a frequency…

modu-ai/moai-adk · 135 tokens

leashd: Skill for Claude Code