Open Source · Production Grade

The Interactive CLI
for AI Agents

Persistent. Deterministic. Project-Scoped Execution.

terminal
$npm install -g clrun
Get StartedView on GitHub

Built for the age of
autonomous coding

Every feature designed to give AI agents reliable, observable, deterministic control over interactive command execution.

Persistent Interactive Execution
Full PTY sessions that persist independently of your agent process. Commands stay alive, buffers stay intact, state stays consistent.
Deterministic Input Queues
Every input is queued with explicit priority ordering. Higher priority sends first. Same priority follows FIFO. No ambiguity.
Priority + Override Control
Queue inputs with priority levels for ordered multi-step flows. Use override to cancel all pending inputs and force immediate execution.
Crash Recovery
Automatic detection of orphaned sessions on restart. Dead processes are marked as detached. Buffer logs remain readable. No data loss.
Project-Scoped Execution
All state lives in .clrun/ at your project root. No global state, no home directory pollution. Every project is isolated.
Structured JSON State
Every command returns structured JSON. Every session, queue entry, and event is machine-readable. Built for programmatic consumption.
AI-Native CLI Workflows
Designed from the ground up for AI coding agents. Built-in skill files teach agents how to use the tool without configuration.
Agent Observability
Append-only buffer logs and structured event ledger provide full visibility into execution history. Every action is auditable.
Git-Trackable Execution History
Optionally commit .clrun/ledger/ to git. Enable AI agents to reason about past execution across sessions and team members.
Multi-Agent Safe Design
Runtime locking prevents state corruption. File-based communication enables multiple agents to interact with the same execution substrate.
Infrastructure-Grade Architecture
Clean separation of concerns. Lock manager, queue engine, PTY manager, buffer system, and ledger all operate independently.
Real-Time Session Monitoring
Tail and head commands provide instant access to terminal output. Status command shows live session states and queue depths.

Four commands.
Complete control.

A minimal, powerful API surface designed for machine consumption. Every response is structured JSON.

1
Execute
$ clrun run "npm init"

Spawn an interactive PTY session. Get back a terminal ID.

2
Interact
$ clrun input <id> "yes" --priority 5

Queue deterministic input with priority control.

3
Observe
$ clrun tail <id> --lines 50

Read terminal output. Monitor execution in real time.

4
Verify
$ clrun status

Check session states, exit codes, and queue depth.

Zero-Configuration AI Compatibility

Built-in agent skills

On first run, clrun automatically installs structured skill files into your project. Point your AI agent at .clrun/skills/ and it knows everything.

Core Skill
clrun-skill.md
Complete CLI reference written for AI consumption. Covers all commands, queue behavior, session lifecycle, and best practices.
Download skill
Claude Code
claude-code-skill.md
Optimized integration instructions for Claude Code. Covers workflow patterns, prompt detection, override strategies, and error handling.
Download skill
OpenClaw
openclaw-skill.md
Structured skill reference for OpenClaw agents. Full command reference, workflow patterns, and agent-specific guidance.
Download skill

$ clrun run "any command"
→ Skills auto-installed to .clrun/skills/ on first run

Browse all skills
Coming Soon

Where this is going

clrun is the foundation. What comes next transforms individual agent execution into team-wide infrastructure.

Team Dashboard

Real-time visibility into team-wide agent execution.

Shared Execution Fabric

Collaborative execution substrate across machines.

Enterprise Audit Layer

Compliance-grade audit trails for regulated environments.

Cloud-Backed Execution

Persistent execution that survives machine restarts.

Team Observability

Unified view of all agent actions across your organization.