interminal: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Interminal is an MCP server that gives AI assistants terminal access — SSH and local shells — with support for interactive commands. It is distributed via uvx and has no build step.

Running & Installation

# Run directly (no install)
python mcp_server.py

# Install from source
pip install .

# Run via uvx (published package)
uvx interminal

There are no test, lint, or build commands configured in this project.

Architecture

mcp_server.py          ← FastMCP tool definitions (6 tools)
    ↓
session_manager.py     ← SessionManager: SSH sessions + transient local execution
    ↓
channel.py             ← Channel abstraction (SSHChannel | LocalChannel | PtyChannel)
    ↓
command.py             ← RunningCommand: background read loop, UTF-8 decoding

Key design decisions

Channel duck-typing — SSHChannel, LocalChannel, and PtyChannel share an interface without ABC/abstractmethod. All three implement read(), write(), close(), send_control(), and is_finished().

Two-phase timeout (_wait_for_result in session_manager.py) — Phase 1 waits up to pause_timeout + 1s for the first byte; if it times out we return immediately (already satisfies the "silent for pause_timeout" contract — going into Phase 2 would waste another full pause_timeout). Phase 2 only runs when bytes are actually arriving, collecting until a pause_timeout gap or total_timeout hits.

PtyChannel platform split — Windows uses pywinpty.PtyProcess; Unix uses stdlib pty with fcntl non-blocking I/O. pywinpty is an optional dependency.

SSHChannel stdin reference — session_manager.py explicitly retains a reference to stdin to prevent Python GC from calling __del__ and closing the paramiko channel prematurely.

Incremental UTF-8 decoding — command.py uses codecs.getincrementaldecoder so multibyte characters split across reads are assembled correctly.