CoTerm — AI Native Terminal Runtime

English | 中文

The runtime layer between AI and the terminal.

CoTerm isn't another terminal emulator. It's a programmable shared terminal session runtime for Humans, AI Agents, and MCP tools.

CoTerm is a headless runtime that manages PTY-backed shell sessions and exposes them to humans and AI through a unified Session API and MCP (Model Context Protocol) server. Any terminal, AI agent, or IDE plugs into the same shared session.

        Human (Tabby / WezTerm / VS Code)
                    │
                    ▼
   ┌─────────────────────────────────────┐
   │          CoTerm Runtime             │
   │  Session ─ PTY ─ Prompt ─ Screen    │
   │  Intelligence ─ Recording ─ Workspace│
   │  Input Arbitration (Human > AI)     │
   └──────────┬──────────────┬───────────┘
              │              │
      Session API      MCP (stdio)
      (in-process)      (AI agents)

What CoTerm IS

What CoTerm is NOT

Why CoTerm?

Every AI coding tool (Claude Code, OpenHands, Cline, Roo Code…) re-implements the same plumbing:

• PTY lifecycle management

• Output parsing and prompt detection

• Session state and Ctrl+C handling

• Timeouts and error handling

CoTerm solves this once. Any MCP-compatible agent connects and gets a shared, long-lived terminal session — it never re-logins, never re-initializes the environment, and never pollutes the human's terminal.

• Windows ConPTY built in — the platform most terminal-sharing tools ignore.

• Enterprise SSH flows (VPN → bastion → OTP → SSH) stay alive inside the session; AI attaches, it doesn't authenticate.

• Human always wins — priority-based input arbitration means the human can interrupt any AI command instantly.

Related MCP server: TermPipe MCP

Features

Session Management

• Full lifecycle: created → starting → running → active → paused → closed

• Create / attach / detach / close, ownership model (Human owns, AI collaborates)

Connectors

Input Arbitration

• Human input always has priority; AI input is queued

• Human can interrupt any AI command with Ctrl+C (session:interrupted)

• Real-time lock/unlock state with events

Session Intelligence (L3)

• Current directory tracking (error-aware, via cd parsing — no pwd probe)

• Toolchain detection (node / python / git / docker…) via PATH scan — no subprocess

• Full-screen app detection (vim, top, less) via ANSI alternate-screen sequences

• Command graph — every command with requester, duration, error heuristic, and output preview

AI Runtime (L4)

• Multi-AI attach — several agents share one session with distinct identities

• Session recording — JSONL event log (output, prompts, commands, interrupts)

• Snapshot / restore — capture config + screen + history, recreate a session with continuity

Workspace (L5)

• Group sessions into named workspaces (e.g. a deploy workspace of Linux / Redis / MySQL / K8s)

• Run commands across all members in parallel

Integration

• MCP server over stdio — 23 terminal + workspace tools

• Session API — programmatic TypeScript interface for terminal renderers

• CLI — full session lifecycle and inspection commands

• Windows standalone — a single coterm.exe, no Node.js or bun required

Tech Stack

Note: On Windows, node-pty ConPTY writes are unreliable under the bun runtime. CoTerm runs the PTY layer under Node (dev via tsx, distribution via pkg). The CLI warns when launched via bun.

Quick Start

Requirements: bun (dev), Node.js 18+.

bun install

# Type-check and run tests
bun run typecheck
bun test

Activate the environment (conda-activate style)

coterm            # starts the daemon (if not running) and activates the shared environment
coterm activate   # same, explicit

# Now every command acts on the shared environment's default session
coterm run --command "kubectl get pods"   # runs in the native shell session (no session id needed)
coterm status                             # cwd, toolchains, command graph
coterm list                               # all sessions
coterm env                                # environment status
coterm stop                               # deactivate (stops the daemon)

Commands pick the first running session when you omit a session id. To target a specific session, pass it: coterm status <sessionId>.

Configuration (~/.config/coterm.json)

The daemon reads its MCP port/host and shell defaults from a config file. CLI flags always override it.

coterm config                        # show config path + effective MCP endpoint
coterm config-set mcp_server_port 9000   # change the MCP port
coterm config-set defaultShell cmd.exe

{
  "mcp_server_port": 8377,
  "defaultShell": "powershell.exe",
  "defaultCwd": "C:\\work"
}

Create sessions with connectors

coterm create --connector ssh --host jump.company.com --user admin --port 22
coterm create --connector wsl --distro Ubuntu
coterm create --connector docker --container web

Connecting an AI Agent (MCP)

Multiple agents sharing one daemon (recommended)

Run a single daemon, then any number of agents connect over HTTP and share the same sessions:

{
  "mcpServers": {
    "coterm": {
      "type": "http",
      "url": "http://127.0.0.1:8377/mcp"
    }
  }
}

Agent A creates a session; Agent B sees and attaches to it — one process, one shared session registry.

Single agent over stdio (ad-hoc)

{
  "mcpServers": {
    "coterm": {
      "command": "coterm",
      "args": ["mcp"]
    }
  }
}

Terminal tools

Workspace tools

Session API (for terminal renderers)

CoTerm exposes an in-process TypeScript API so terminal frontends (Tabby, WezTerm, VS Code) can embed the runtime:

import { SessionAPI } from './src/api/session-api.js';

const api = new SessionAPI();

const sessionId = await api.createSession({ shell: 'powershell.exe' });
await api.runCommand(sessionId, 'git pull', 'ai');
await api.waitForPrompt(sessionId);
console.log(api.readText(sessionId));

const unsub = api.onPromptDetected(sessionId, (prompt) => {
  console.log('command finished at', prompt);
});

await api.close(sessionId);

Standalone Executables (Windows / Linux / macOS)

Package self-contained binaries — no Node.js or bun needed on the target machine:

bun run package:windows   # -> coterm.exe
bun run package:linux     # -> coterm
bun run package:macos     # -> coterm

Pushing a v* tag runs the release workflow on all three platforms (windows-latest / ubuntu-latest / macos-latest) and publishes one GitHub Release with coterm-windows-x64.exe, coterm-linux-x64, and coterm-macos-x64. Each binary embeds the Node.js runtime, all code, and node-pty's native binaries (ConPTY on Windows, forkpty on POSIX).

Shell integration (prompt prefix + shorthand commands)

After coterm activate, the shell prompt shows a (coterm) prefix and shorthand commands (list, status, run, stop, ...) work without the coterm prefix. It is auto-installed on first activation — or manually:

# any platform
coterm            # auto-starts daemon (hidden) + activates; prompt gains "(coterm) "
list              # shorthand — no "coterm" prefix needed
run --command "echo hi"
status
stop              # deactivates; prompt reverts

read and history shorthands are omitted on bash/zsh to avoid clashing with shell builtins (use coterm read / coterm history).

Distribution

Ship only the single binary — it is fully self-contained. On each target machine just run it: coterm activates (and auto-installs the shell integration on first use). Restart the shell (or source ~/.bashrc / . $PROFILE) to see the (coterm) prompt.

Optional per-user config lives at ~/.config/coterm/config.json (mcp_server_port, defaultShell). Everything else is auto-generated at runtime.

Claude skill

A ready-to-use Claude skill lives at skills/coterm/SKILL.md — it drives CoTerm as a pure HTTP client (calls the daemon's /cli endpoint via curl; no MCP client config needed). Install by copying it into your agent's skills directory:

mkdir -p ~/.claude/skills && cp -r skills/coterm ~/.claude/skills/

The skill only calls the running daemon — start it first with coterm.

Project Structure

src/
├── index.ts              # CLI entry
├── main.ts               # Runtime bootstrap
├── api/session-api.ts    # Programmatic Session API
├── core/                 # types, event-bus, session, session-manager
├── pty/                  # PTY adapters (Windows / POSIX) + factory
├── connectors/           # local / ssh / wsl / docker
├── buffer/               # screen buffer, prompt detector
├── queue/                # command queue, input scheduler (arbitration)
├── intelligence/         # cwd, toolchains, screen mode, command graph
├── ai/                   # multi-AI, recorder, snapshot/restore
├── workspace/            # session groups
├── mcp/                  # MCP server + tools
└── cli/                  # CLI commands

Roadmap

• L1 Session / PTY / Prompt detection / Connectors

• L2 Input arbitration + Presence

• L3 Session Intelligence (cwd, toolchains, command graph, full-screen detection)

• L4 AI Runtime (multi-AI, recording, snapshot)

• L5 Workspace (session groups, batch commands)

• Plugin ecosystem (recorder, metrics, notification)

• CI/CD cross-platform builds

• Desktop UI (Tauri + React) as a renderer frontend

License

MIT