clrun

The Interactive CLI for AI Agents

Persistent. Deterministic. Agent-Native.

yup! that's right — no more --yes or command retries

clrun gives AI agents full control over interactive terminal sessions — TUI prompts, select lists, checkboxes, long-running processes, and stateful shells. Every response is structured YAML with contextual hints telling the agent exactly what to do next.

pip install clrun

Why clrun?

Traditional CLI execution gives agents a string and an exit code. clrun gives them:

• Structured context — every response includes output, hints, and warnings
• Interactive control — navigate TUI prompts with named keystrokes
• Persistent sessions — env vars, cwd, and history survive across calls
• Agent-native errors — failures include the reason, alternatives, and recovery commands

# What an agent sees after running a command:
---
terminal_id: f5e6d7c8-...
command: npx create-vue@latest
output: |
  ◆  Project name:
  │  vue-project
status: running
hints:
  send_input: clrun f5e6d7c8 "my-app"
  send_keys: clrun key f5e6d7c8 enter
  view_output: clrun tail f5e6d7c8 --lines 50
  kill: clrun kill f5e6d7c8

Quick Start

# Run any command
clrun echo "hello world"

# Start an interactive scaffolder
clrun "npx create-vue@latest"

# Send input to a session
clrun <terminal_id> "my-project-name"

# Navigate TUI prompts with keystrokes
clrun key <terminal_id> down down enter

# View output
clrun tail <terminal_id> --lines 50

# Check all sessions
clrun status

# Kill a session
clrun kill <terminal_id>

Commands

TUI Prompt Navigation

Python Version

This is the Python port of clrun. It uses pexpect for PTY management instead of node-pty, which means:

• No native compilation — pexpect is pure Python on macOS/Linux
• Same CLI interface — identical commands and YAML output
• Same file-based state — .clrun/ directory structure is fully compatible

Install via pip:

pip install clrun

Or pipx for isolated install:

pipx install clrun

License

MIT — github.com/cybertheory/clrun