agent-runtime-mcp
This server provides a generic MCP layer for interacting with pre-existing terminal channels (e.g., tmux panes), exposing tools to list, inspect, read, write, send controls, check health, and wait for channel events without managing channel lifecycle or interpreting application semantics.
List channels: Discover available terminal channels in the configured backend scope (
list_channels).Inspect a channel: Get mechanical metadata and capabilities, optionally establishing a snapshot observation cursor (
get_channelwithobserve).Read output: Retrieve bounded recent terminal output by specifying bytes/lines limits (
read_channel).Write text: Send ordinary Unicode text to a channel, with optional explicit ENTER submission (
write_text).Send controls: Deliver explicit terminal controls: ENTER, INTERRUPT, or ESCAPE (
send_control).Check health: Verify backend/service mechanical health, independent of channels or application state (
health).Wait for events: Wait for observable channel activity followed by a quiet period, using a snapshot cursor (
wait_channel_event).
Provides MCP tools for interacting with existing tmux terminal channels, including listing channels, reading output, writing text, sending explicit controls (ENTER, INTERRUPT, ESCAPE), waiting for channel events, and checking backend health.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@agent-runtime-mcp show me my active tmux channels and their latest output"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
agent-runtime-mcp
A generic MCP communication layer for already-existing interactive terminal Channels, with tmux as the first backend.
Product surface
The current main MCP server exposes exactly:
list_channels
get_channel
read_channel
write_text
send_control
healthIssue #32's additive contract is integrated: get_channel(observe=true) plus the seventh wait_channel_event tool are part of the current verified runtime.
The product owns the MCP capabilities and Channel semantics behind those tools.
It does not decide what a terminal represents.
A Channel may contain Codex, another Agent CLI, a shell, a REPL or any other interactive program.
Related MCP server: termcp
Boundary
Inside product:
MCP tool/schema contract
backend-neutral Channel model
existing-Channel discovery
bounded output read
bounded ordinary-text write
explicit ENTER / INTERRUPT / ESCAPE
backend/service health
bounded snapshot-change event wait
structured Channel/backend errors
tmux scope enforcementOutside product:
Worker / Agent / Task semantics
workflow scheduling / review / recovery
worktree / branch / PR lifecycle
tmux session/pane lifecycle
process startup/restart
application completion interpretation
deployment / tunnel / proxy
TLS / DNS / firewall
workspace/client authorization policy
provider credentials / host administrationDeployment is intentionally separate: agent-runtime-mcp is responsible for MCP capability, not how an operator makes the MCP process reachable.
Current implementation
The server currently runs over stdio.
Requirements:
Node.js 20 or newer;
npm;
tmux available to the service account.
Install and verify:
npm ci
npm run typecheck
npm test
npm run test:integration
npm run test:discovery
npm run test:dogfoodtest:discovery is the official-client regression for public stdio health/discovery. test:dogfood drives the complete six-Tool public MCP flow against an externally prepared disposable tmux + bash --noprofile --norc endpoint, including marker observation, INTERRUPT, post-control reuse, external destruction and no-recreation failure proof.
Build and run:
npm run build
npm startPrepare tmux externally
The MCP never creates panes. Prepare terminal endpoints with native tmux or another upper layer, for example:
tmux -L agent-runtime new-session -d -s demo
TMUX_SOCKET_NAME=agent-runtime npm startOptional backend configuration:
TMUX_SOCKET_NAME
TMUX_SOCKET_PATH
TMUX_ALLOWED_SESSIONS
TMUX_TIMEOUT_MS
TMUX_MAX_CHANNELS
TMUX_READ_DEFAULT_LINES
TMUX_READ_MAX_LINES
TMUX_READ_MAX_BYTESSafe input contract
write_text transports bounded ordinary Unicode text as data.
LF and TAB are allowed;
other Unicode
Cccontrols are rejected;caller text never becomes shell command syntax or caller-controlled tmux key grammar;
each call has a hard 1 MiB UTF-8 maximum;
submit=trueadds one explicit Enter only after text delivery succeeds.
send_control accepts exactly:
ENTER
INTERRUPT
ESCAPEMutation success means mechanical terminal transport only, not application success. Mutations are non-idempotent and are not blindly retried after ambiguous timeout.
Health contract
health reports only backend/service mechanical health:
backend_kind
available
detail?Health does not mean a Channel exists or that a foreground application/Agent/Task is ready.
Example composition
An upper layer may do:
prepare endpoint externally
→ list_channels
→ get_channel
→ read_channel
→ get_channel(observe=true) before a write that needs bounded waiting
→ write_text
→ wait_channel_event
→ read_channel
→ send_control when explicitly needed
→ interpret application result outside MCPThat is the key architectural split:
upper layer = lifecycle + meaning + workflow control
Channel MCP = communication capability onlyDocumentation
Product contract:
docs/requirements.mddocs/channel-architecture.mddocs/channel-model.mddocs/mcp-contract.mddocs/backends/tmux.mddocs/security.mddocs/technology-stack.mddocs/mvp-plan.md
docs/deployment.md documents the non-product deployment boundary only.
Repository development process:
AGENTS.mddocs/tasks/
The repository workflow and deployment environment are both separate from the public MCP capability model.
Available Tools
7 toolsget_channelARead-onlyIdempotent
Inspect mechanical metadata and capabilities for one terminal channel.
Inputs: channel_id (required), observe.
healthARead-onlyIdempotent
Report mechanical backend/service health independently of Channel inventory or application state.
Inputs: no named parameters.
list_channelsARead-onlyIdempotent
List existing terminal channels visible in the configured backend scope.
Inputs: no named parameters.
read_channelARead-onlyIdempotent
Read bounded recent terminal output from one channel without waiting for semantic completion.
Inputs: channel_id (required), bytes, lines.
send_controlADestructive
Send one explicit reviewed terminal control to an existing channel.
Inputs: control (required), channel_id (required).
wait_channel_eventBRead-onlyIdempotent
Wait for mechanically observed Channel snapshot activity followed by bounded quiet; never infers completion.
Inputs: channel_id (required), after_cursor (required), idle_ms, timeout_ms.
write_textADestructive
Deliver bounded ordinary Unicode terminal text to one existing channel. LF/TAB are allowed; explicit controls use send_control.
Inputs: text (required), submit (required), channel_id (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 7 tools
Each tool targets a distinct action: listing, inspecting, reading, writing, controlling, waiting, and health checking are all separable. The only mild ambiguity is between wait_channel_event and read_channel, but the descriptions clearly separate waiting for activity from reading output.
Most tools follow a clear verb_noun pattern: get_channel, list_channels, read_channel, send_control, write_text. The exception is health, which breaks the pattern by being a bare noun rather than something like get_health or check_health.
Seven tools is a well-scoped size for a terminal-channel runtime. Each tool covers a meaningful operation without redundancy or bloat.
The surface covers the core interaction lifecycle for existing channels: inspect, list, read, write, control, and wait. Channel creation/teardown is not exposed, but that may intentionally live outside this server's scope, so it is a minor rather than critical gap.
Maintenance
Related MCP Connectors
Real-time chat for AI agents. Claude Code, Cursor, Cline and Codex join channels over MCP.
Agent communication platform for agent to agent messaging via MCP. Messages, channels, skills.
Join durable public agent discussions and invite-only private group rooms through MCP.
Connect ChatGPT and Claude to your Mac, Windows or Linux with secure MCP remote access.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceMCP server for tmux operations that provides comprehensive control over tmux sessions, windows, and panes.1-
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to interact with real terminal sessions across local and remote hosts, driving multi-turn interactive programs like TUIs, REPLs, and SSH prompts through MCP.72MIT
- AlicenseNot gradedqualityAmaintenanceEnables AI agents running in separate tmux panes to read each other's output, send tasks and messages across panes, and coordinate multi-agent workflows through standard MCP tool calls. It calls tmux directly with no external dependencies beyond tmux itself.49 npmMIT
- AlicenseNot gradedqualityAmaintenanceEnables MCP-compatible AI agents to read, type, and send messages into other tmux panes, allowing them to coordinate multi-agent workflows, monitor processes, and exchange context without manual copy-pasting.49 npmMIT