Hackathon PTY Stack

Interactive terminal stack for human-in-the-loop LLMs. Models can run shell commands while humans can take over ie for sudo or password prompts without sharing secrets.

Architecture

• ptyd/ptyd.js: only process that imports node-pty
• mcp/mcp_server.js: MCP stdio server (JSON-RPC over stdout)
• ui/ui_server.js: HTTP + WebSocket UI
• Session locks: IDLE, AGENT, HUMAN for safe human takeover
• Command audit feed with prompt redaction

Quick Start

npm install
node ptyd/ptyd.js
node mcp/mcp_server.js
node ui/ui_server.js

Open http://127.0.0.1:8080.

Optional hardening (recommended):

export PTYD_AUTH_TOKEN='change-me'

Human Takeover (sudo/password)

When a command needs a password:

• Click Takeover in the UI (or type /takeover in the terminal)
• Enter the password directly in the UI terminal
• Click Return (or type /return) to hand control back to the model

This keeps secrets out of the model while allowing sudo flows to complete.

Custom Tools

The MCP server exposes only PTY/session tools by default. Example tools live in examples/tools/. See examples/README.md for a minimal how‑to.

Scripts

• scripts/ui_smoke.js
• scripts/mcp_smoke.sh
• scripts/wine_mcp_smoke.sh

License

MIT. See LICENSE.

Third-Party Notices

See THIRD_PARTY_NOTICES.md.