# Krill — Full Technical & CLI Reference (`llms-full.txt`)

> Canonical URL: https://krill.page/llms-full.txt
> Summary Index: https://krill.page/llms.txt
> Website: https://krill.page (Korean) · https://krill.page/en (English)
> CLI Docs: https://krill.page/docs · https://krill.page/en/docs
> Repository: https://github.com/craftowen/krill
> License: Apache-2.0

---

## 1. Executive Summary

### English
**Krill** is an open-source (Apache-2.0), pure-Rust native macOS application (`krill-app`) and command-line interface (`krill`) engineered to run multiple AI coding agents — including **Claude Code (`claude`)**, **OpenAI Codex (`codex`)**, **Gemini CLI (`agy`)**, **Cursor (`cursor`)**, and **OpenCode (`opencode`)** — side by side in isolated Git worktrees without ever dropping a terminal session.

Unlike Electron-based terminal wrappers or single-process multiplexers, Krill isolates terminal ownership across three tiers:
1. **`krill-holder`** (PTY parent): A tiny (`≤ 1,250` lines on macOS), panic-free process that owns the master PTY file descriptors and spawns child shells/agents.
2. **`krilld`** (session daemon): The single terminal query responder that maintains a 1,000-row hot `alacritty_terminal` grid per session, streams older lines into `zstd`-compressed cold scrollback segments, processes agent lifecycle hooks, runs a serialized Git queue, and coordinates multi-agent task DAGs.
3. **`krill-app`** (`gpui` native macOS UI): Renders only visible screen snapshots and row deltas without mirroring full terminal state in the UI process.

If `krill-app` crashes (`kill -9`), quits, or updates, or if `krilld` is restarted or upgraded, running AI agents continue uninterrupted and missed bytes replay from keyframes and raw segment records when the UI or CLI reconnects.

### 한국어 (Korean)
**Krill**은 Claude Code(`claude`), OpenAI Codex(`codex`), Gemini CLI(`agy`), Cursor(`cursor`), OpenCode(`opencode`) 등 AI 코딩 에이전트를 Git 워크트리마다 격리해 병렬로 실행하는 순수 Rust 기반 네이티브 macOS 앱(`krill-app`) 및 단일 바이너리 CLI(`krill`)입니다.

화면을 그리는 앱(`krill-app`), 터미널 상태를 해석하고 스크롤백·훅·오케스트레이션을 담당하는 세션 데몬(`krilld`), 그리고 PTY 마스터 파일 디스크립터(fd)를 소유하는 초소형 부모 프로세스(`krill-holder`)를 3단으로 분리했습니다. 앱을 `kill -9`로 강제 종료하거나 업데이트해도, 심지어 `krilld` 데몬이 재시작되어도 에이전트 프로세스는 죽지 않으며, 재연결 시 키프레임과 원본 바이트 세그먼트를 통해 놓친 출력이 바이트 단위로 복원됩니다.

---

## 2. System Requirements & Memory Budgets

### Requirements
- **OS**: macOS (Apple Silicon `arm64` for prebuilt release bundles; Intel `x86_64` supported via source build)
- **Build Toolchain (Source Build)**: Command Line Tools, Rust `1.98` or newer (`Cargo.toml` MSRV `1.98`), Python `3.9+` (for release packaging scripts)

### Memory Budgets & Measured Verification
- **Design Budgets (10 concurrent terminals, macOS `phys_footprint`)**:
  - `krill-app`: `≤ 120 MB`
  - `krilld`: `≤ 60 MB`
  - Combined app + daemon target: `≤ 180 MB` (release-blocking hard gate: `200 MB`)
  - Hot scrollback grid: `1,000 rows` per session; older scrollback is compressed into `zstd` cold segments (never keeping 10,000+ uncompressed cell rows in RAM).
- **Existing Measured Benchmark Record**:
  - Daemon total (`krill-holder` + `krilld`, app excluded): **47.39 MiB** `phys_footprint` across 10 sessions (120×40 grid × 24 accelerated epochs soak test).
  - App `SIGKILL` survival test: **3/3 passes**, **408,058 bytes** output verified with exact SHA-256 match after `kill -9` of release binary.

---

## 3. Architecture & Failure Guarantee Matrix

```
[ krill-app (gpui UI) ]  <-- UDS (0600, getpeereid): snapshots + row deltas -->  [ krilld (session daemon) ]  <-- SCM_RIGHTS fd handoff -->  [ krill-holder (PTY parent) ]
```

| Failure Scenario | Agent Processes | Screen & Output Guarantee |
|---|---|---|
| `krill-app` crash / quit / update (`kill -9 krill-app`) | **Alive** | Lossless within ring buffer & segment retention; if retention overflows, an explicit `"N bytes skipped"` gap marker is displayed. |
| `krilld` crash (`kill -9 krilld`) | **Alive** (`krill-holder` keeps PTY fds and relaunches `krilld`) | Bytes read from PTY but not yet flushed to disk segments may be lost; shown honestly as a gap marker after `krilld` restarts. |
| `krilld` upgrade | **Alive** | Lossless: PTY reader is paused and segments are sealed before `SCM_RIGHTS` handoff. Only one daemon generation exists (0 orphan daemons). |
| `krill-holder` crash only | **Alive** (`krilld` also holds open PTY fds) | Lossless terminal output; only child process exit codes are lost. |
| Simultaneous `krill-holder` + `krilld` loss or OS reboot | **Terminated** | Read-only screen restoration up to the last sealed segment, allowing immediate session continuation via `claude --resume` or `codex resume`. |

---

## 4. Installation

### Method 1: One-Click Release Installer (Recommended)
```sh
curl -fsSL https://krill.page/install.sh | bash
```
The installer downloads the latest GitHub Release, verifies the ZIP SHA-256 checksum and `codesign --verify --strict`, installs `/Applications/Krill.app` in place without killing running sessions, and links `~/.local/bin/krill`.

Pass-through options:
```sh
curl -fsSL https://krill.page/install.sh | bash -s -- --release v0.1.2 --no-open
curl -fsSL https://krill.page/install.sh | bash -s -- --from-source --tag main
```

### Method 2: Build from Source
```sh
git clone https://github.com/craftowen/krill.git
cd krill
cargo build --release --locked --bins
bash packaging/install.sh --source-dir "$PWD"
export PATH="$HOME/.local/bin:$PATH"
krill doctor
```

---

## 5. Complete CLI Reference (`krill`)

`krill` communicates directly with `krilld` over a Unix domain socket. Every command works whether `krill-app` is open or closed.

### 5.1 Quickstart Workflow
```sh
# 1. Verify daemon health and install agent lifecycle hooks
krill doctor
krill hook install claude

# 2. Spawn an agent in an isolated Git worktree (no GUI required)
id=$(krill new --worktree feat-x --agent claude)
krill wait "$id" --for idle
krill read "$id" --lines 40

# 3. Attach interactively from any terminal (Ctrl-] to detach)
krill attach "$id"
```

### 5.2 Sessions
| Command | Description (EN) | 설명 (KO) |
|---|---|---|
| `krill ls [--json]` | List active sessions and their state | 세션 목록과 상태 조회 |
| `krill new [--cwd <path>] [--worktree <name>] [--agent <profile> \| -- <program>…]` | Create a new session running an agent profile or arbitrary program | 에이전트 프로필 또는 임의 프로그램으로 새 세션 생성 |
| `krill send <id> [--enter] [--text <text>] [--stdin]` | Send keystrokes or text input to a session | 세션에 텍스트 입력 전송 |
| `krill read <id> [--lines N]` | Read current screen and recent scrollback lines | 현재 화면 및 최근 출력 읽기 |
| `krill wait <id> --for idle\|waiting\|blocked\|done\|exited\|pattern\|quiet [--timeout <s>]` | Block until target state, regex match, or quiet period | 특정 상태·정규식 패턴·출력 정지까지 대기 |
| `krill attach <id>` | Attach any standard terminal to the session (`Ctrl-]` detaches) | 일반 터미널에서 세션에 직접 연결(`Ctrl-]` 분리) |
| `krill kill <id>` | Terminate a session cleanly (`HUP` → `TERM` → `KILL`) | 세션 종료(`HUP` → `TERM` → `KILL`) |
| `krill --host <user@host> ls` | Drive a remote `krilld` over SSH Unix-socket forwarding | SSH 유닉스 소켓 포워딩으로 원격 `krilld` 제어 |
| `krill handoff --from <id> [--to-agent <agent>] [--prompt <text>]` | Hand off a session's context to another AI agent | 세션 맥락을 다른 에이전트에게 인계 |

### 5.3 Worktrees & Git Changes
| Command | Description (EN) | 설명 (KO) |
|---|---|---|
| `krill worktree new <name> [--repo <path>] [--base <ref>] [--setup run\|skip]` | Create a Git worktree (and optionally run repo setup script) | Git 워크트리 생성 및 레포 초기화 스크립트 실행 |
| `krill worktree rm <path> [--force]` | Remove a Git worktree | 워크트리 삭제 |
| `krill changes [--repo <path>]` | List modified/added/deleted files in the worktree | 변경 파일 목록 조회 |
| `krill set --comment <text> \| --workspace-status <…> \| --pr <n>` | Attach worktree memo, status badge, or PR/issue link | 워크트리 메모·상태 배지·PR/이슈 연결 |
| `krill reference list\|add\|remove <url>` | Attach reference URLs to a session or worktree | 세션·워크트리에 참고 URL 연결 |
| `krill ports` | List local TCP ports opened by sessions | 세션이 리스닝 중인 로컬 포트 조회 |

### 5.4 Multi-Agent Orchestration (`krill orchestration`)
```sh
# 1. Isolate work in a fresh Git worktree
krill worktree new feat-api --base main

# 2. Create an orchestration run and dependent task DAG
krill orchestration run-create --title "ship replay"
krill orchestration task-create --run R --title impl-api
krill orchestration task-create --run R --title review --deps T1

# 3. Dispatch a worker agent on a task
krill orchestration worker-start --run R --task T1 \
    --worker api --agent codex \
    --cwd ~/Minikrill/worktrees/feat-api --prompt "implement T1"

# 4. Block on a human decision gate
krill orchestration gate-create --from coordinator --run R \
    --question "merge feat-api?" --options yes,no
krill orchestration gate-resolve G1 --decision yes
```

| Command | Description (EN) | 설명 (KO) |
|---|---|---|
| `krill orchestration run-create --title <t>` | Create a multi-agent orchestration run | 오케스트레이션 런 생성 |
| `krill orchestration task-create --run <r> --title <t> [--deps t1,t2]` | Add a task node to the DAG with optional dependencies | 의존성 있는 작업(DAG 노드) 추가 |
| `krill orchestration worker-start --run <r> [--task <t>] --worker <name> [--agent <a>] [--cwd <dir>] --prompt <text>` | Boot and assign a worker agent on a task | 작업에 워커 에이전트 배정 및 기동 |
| `krill orchestration send \| check [--wait] \| ask \| reply` | Coordinator ↔ worker messaging and blocking ask/reply | 코디네이터↔워커 메시지 및 블로킹 질의응답 |
| `krill orchestration gate-create --from <n> --question <q> [--options a,b]` | Open a human decision gate | 사람 결정 게이트 생성 |
| `krill orchestration gate-resolve <id> --decision <choice>` | Resolve an open decision gate | 게이트 결정 처리 |
| `krill orchestration worker-list \| worker-read \| worker-stop` | Inspect worker status, read output, or stop workers | 워커 목록·출력 조회 및 중지 |

### 5.5 Agents, Hooks, Accounts & Schedules
| Command | Description (EN) | 설명 (KO) |
|---|---|---|
| `krill hook install\|uninstall claude\|codex\|agy\|cursor\|opencode` | Install agent status hooks for notifications, Dock badges, and Needs You | 에이전트 상태 훅 설치(알림·배지·Needs You) |
| `krill agent list` | List detected AI coding agent profiles on the machine | 감지된 에이전트 프로필 목록 |
| `krill account list\|switch\|add\|rm\|auto-switch` | Switch agent accounts or auto-switch when usage limits are hit | 에이전트 계정 전환 및 한도 도달 시 자동 전환 |
| `krill skills list\|get\|install <name>` | Browse and install agent skills | 에이전트 스킬 조회 및 설치 |
| `krill schedule add <id> --cron '…' --prompt <text> -- <exe>` | Schedule recurring agent runs using UTC cron expressions | UTC cron 기반 예약 에이전트 실행 |
| `krill statusline [install\|uninstall]` | Integrate with Claude Code status line | Claude Code 상태 줄 연동 |

### 5.6 Artifact Sharing (`krill artifacts` & `share.krill.page`)
Publish HTML or Markdown reports generated by agents to `https://share.krill.page` for a sandboxed public URL (90-day retention, up to 2 MB with owner token, 64 KB anonymous, Orca-compatible `/v1/artifacts` wire contract).

```sh
# Via Krill CLI
krill artifacts share ./report.html --title "Architecture Audit"
krill artifacts update ./report.html
krill artifacts unshare ./report.html
krill artifacts list
krill artifacts delete <slug>

# Via HTTP API (Orca-compatible wire contract)
jq -n --rawfile c report.html \
  '{content:$c, contentType:"text/html", fileName:"report.html"}' \
| curl -s https://share.krill.page/v1/artifacts \
    -H 'content-type: application/json' --data @-
```

### 5.7 Diagnostics, History & Updates
| Command | Description (EN) | 설명 (KO) |
|---|---|---|
| `krill doctor [--bundle \| --json]` | Diagnose `krill-holder`, `krilld`, socket, and hooks; export support bundle | holder·krilld·소켓·훅 상태 진단 및 지원 번들 생성 |
| `krill update [--check] [--json]` | Check for and install updates without dropping active sessions | 활성 세션을 유지한 채 새 릴리스 확인·업데이트 |
| `krill history clear` | Clear cold scrollback segments | 콜드 스크롤백 기록 삭제 |
| `krill telemetry status\|enable\|disable` | Manage telemetry (disabled by default) | 텔레메트리 설정(기본값 꺼짐) |

---

## 6. Frequently Asked Questions (FAQ)

### Q1: How is Krill different from Electron terminal apps or `tmux`?
- **Versus Electron apps**: Krill is written in 100% Rust using `gpui` for GPU-accelerated rendering and `alacritty_terminal` inside `krilld`, keeping the combined app + daemon memory budget within `≤ 180 MB` for 10 terminals (`≤ 120 MB` app, `≤ 60 MB` daemon). More importantly, `krill-app` does not own PTYs — `krill-holder` does — so UI crashes or updates never kill running agents.
- **Versus `tmux`**: `krilld` is the single terminal query responder with a 1,000-row hot grid and `zstd` cold scrollback segments, avoiding nested-TUI escape sequence collisions. Krill also provides native macOS Git worktree management, read-only diff review, 6-state agent hooks (`Needs You` priority queue), first-class Korean Hangul IME composition, and built-in multi-agent DAG orchestration (`krill orchestration`).

### Q2: Which AI coding agents work with Krill?
Krill has built-in profile and lifecycle hook support (`krill hook install`) for **Claude Code (`claude`)**, **OpenAI Codex (`codex`)**, **Gemini CLI (`agy`)**, **Cursor (`cursor`)**, and **OpenCode (`opencode`)**. Because persistence operates at the PTY file-descriptor level in `krill-holder`, any shell (`zsh`, `bash`, `fish`), dev server, or TUI tool receives the exact same crash-survival guarantee.

### Q3: How does Korean (Hangul) IME input work in Krill?
Many terminal emulators drop, duplicate, or reorder trailing Hangul syllables when pressing Enter (`⏎`) inside TUI prompts like Claude Code. `krill-term` implements a dedicated framework-neutral IME state machine verified against Hangul composition test suites so `"안녕하세요⏎"` commits cleanly without character loss or reordering.

### Q4: Can one AI agent orchestrate other AI agents using Krill?
Yes. A coordinator agent (for example, Claude Code) can invoke `krill worktree new` to isolate branches and `krill orchestration` (`run-create`, `task-create --deps`, `worker-start`, `send`, `check --wait`, `ask`, `reply`, `gate-create`) to dispatch and supervise worker agents (such as Codex, Gemini, or OpenCode) across a dependency DAG while pausing at human decision gates when approval is required.