Skip to main content

​
derun

derun is a terminal-faithful command runner with side-channel transcript capture and MCP-based output retrieval for AI workflows.

​
Why use derun

  • Keep terminal behavior unchanged for human operators.
  • Capture complete command transcripts for later replay and live tail.
  • Expose read-only MCP tools for deterministic session discovery and output access.

​
Core capabilities

  • Run mode: derun run -- <command> [args...]
  • -- is required in run mode to separate derun flags from the target command and args.
  • MCP mode: derun mcp
  • Cursor-based output APIs over MCP:
    • derun_list_sessions
    • derun_get_session
    • derun_read_output
    • derun_wait_output

​
Install

Tag contract:
  • derun@v<semver>
Package manager:
  • macOS/Linux: brew install delinoio/tap/derun
Windows direct install:
  • ./scripts/install/derun.ps1 -Version latest -Method direct
Script installer: 
./scripts/install/derun.sh --version latest --method package-manager

./scripts/install/derun.ps1 -Version latest -Method direct
Direct installers verify Sigstore bundle sidecars (*.sigstore.json) and only support bundle-enabled releases.

​
Quick start

Run a command with transcript capture: 
derun run -- ls -la
Run with an explicit session ID and retention: 
derun run --session-id local-debug-001 --retention 24h -- go test ./...
Start MCP bridge server for session retrieval: 
derun mcp

​
Terminal fidelity rules

  • Child stdout/stderr are forwarded without mutation.
  • PTY transport is used for interactive terminals (POSIX PTY / Windows ConPTY).
  • Process exit code or signal semantics are preserved.

​
Retention and storage

  • Default retention TTL is 24 hours.
  • Session artifacts are stored under the local state root ($XDG_STATE_HOME/derun or fallback path).
  • Per-session artifacts include meta.json, output.bin, index.jsonl, and final.json.