agent-interactive-terminal

🖥️ Agent Interactive Terminal

Stateful PTY terminal sessions where an agent and a person share the same screen.

🌐 English · 简体中文

> One shared terminal core with two host adapters: a DeepSeek Harness bundle and a Codex/ChatGPT MCP App. Eight terminal_* tools, a live shared xterm panel, and password handoff that never enters the model context. Seventy-seven tests pass on Linux with Node 20/22; the full design is in [docs/design.zh.md](docs/design.zh.md).

Why

The usual exec tool has no TTY. Programs do not enter interactive mode, long work is invisible, passwords leak into the transcript, and a person cannot share the same shell with the model.

This project turns a terminal into a resource with identity, a screen, a phase, and a lease. The model reads discrete screen snapshots instead of a byte stream; the person can take over, make it read-only, or seal it.

Install

Requires Node.js 20+ and a C++ toolchain for node-pty. In DSH, add this index under Plugins → Discover:

https://raw.githubusercontent.com/AyanamiiiRei/agent-interactive-terminal/main/plugin-market.json

Search for agent-interactive-terminal, or paste a Git spec under Add plugin. Approve the node-pty build script on first install; restart DSH once after upgrading.

git clone https://github.com/AyanamiiiRei/agent-interactive-terminal.git
cd agent-interactive-terminal
npm install
npm run build

Platforms

Unix shells come first: Linux and macOS use the local zsh/bash; macOS falls back to /bin/zsh when $SHELL is unset. On Windows the launcher looks for wsl.exe: when usable it starts zsh (or bash if zsh is missing) inside WSL and translates the generated rc files to WSL paths. Without WSL it falls back to PowerShell 7, Windows PowerShell, or cmd.exe. Choosing zsh/bash without WSL fails with an explicit message. Native PowerShell/cmd has no prompt markers, so waits fall back to screen content and output silence: usable, but less precise than WSL.

Quick start

npm run demo -- "git status"   # one command and the model-facing screen
npm run demo                   # interactive loop: /snap, /wait, /key, /resize, /quit
npm run attach                 # browser attach demo, open the printed address

Inside DSH

The terminal icon lives in the session header. Opening it shows an xterm panel on the right; session tabs are numbered in their current order and close on middle click. While the agent is active, the top bar and the area below the terminal carry an RGB running light.

• Keyboard ownership: typing takes the lease; a few idle seconds hand it back. Agent writes queue during that window, with the queued command and a cancel button in the top bar, then drain in order after handback.
• Access levels: collaborate, observe (read-only), and sealed (no read or write; the list keeps only a redacted record). Read-only and sealed refuse queueing and return distinct errors.
• Tool policy: interactive first by default; one-shot first and terminal only are the alternatives. Terminal only hides bash from the agent. A separate switch steers REPL work into python and similar interactive sessions.
• Settings: theme, font, cursor, shortcuts, scrollback, bell, copy/paste, and lease timeout. The theme follows DSH by default and can be pinned to a fixed palette.

Inside Codex

The same core also ships as an MCP stdio server plus a Codex plugin. After building, add the repository to Codex's plugin marketplaces:

npm install && npm run build
codex plugin marketplace add /path/to/agent-interactive-terminal
codex plugin add agent-interactive-terminal@agent-interactive-terminal

Start codex and ask it to open a terminal; the terminal_open result carries a local panel URL. Open that page to share the shell, take over, make it read-only, seal it, and answer password prompts. See [docs/codex.zh.md](docs/codex.zh.md) for the full walkthrough.

The same terminal can also appear beside the conversation in the ChatGPT desktop app, which ships Codex as its agent. The interactive_terminal tool declares a thread entrypoint through MCP Extensions; after restarting the desktop app and opening a new Codex chat, choose Interactive Terminal in the side panel. The window embeds the same React panel used by the DSH adapter, with the MCP stdio transport adapted to the panel's attach protocol. That panel and Codex's built-in Terminal are separate: the built-in one is Codex's own PTY, while Interactive Terminal drives this project's terminal_* session, with screen snapshots, waits, a takeover lease, and read-only/sealed access.

Without the plugin marketplace, register the MCP server directly:

codex mcp add ait -- node /path/to/agent-interactive-terminal/plugins/codex/bin/ait-mcp.mjs

The MCP server and panel also run on their own:

npm run mcp          # or node dist/mcp/cli.js after a build
npm run panel        # standalone panel with a manually opened shell

From code

No agent framework is required; use TerminalRegistry directly:

import { TerminalRegistry } from 'agent-interactive-terminal'

const sessions = new TerminalRegistry({ maxSessions: 2 })
const session = await sessions.open({ name: 'build', cols: 100, rows: 30 })

await session.write('npm run dev')
const result = await session.wait({ match: ['ready in'], timeoutMs: 60_000 })
console.log(result.outcome, result.view.text)