> ## Documentation Index
> Fetch the complete documentation index at: https://oss.delino.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Derun

# 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:

```bash theme={null}
./scripts/install/derun.sh --version latest --method package-manager
```

```powershell theme={null}
./scripts/install/derun.ps1 -Version latest -Method direct
```

Direct installers verify the selected release artifact against its `SHA256SUMS` entry.

## Quick start

Run a command with transcript capture:

```bash theme={null}
derun run -- ls -la
```

Run with an explicit session ID and retention:

```bash theme={null}
derun run --session-id local-debug-001 --retention 24h -- go test ./...
```

Start MCP bridge server for session retrieval:

```bash theme={null}
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`.

## Related pages

* [Projects Overview](projects-overview)
* [Documentation Lifecycle](documentation-lifecycle)