# Krill

> Krill is an open-source (Apache-2.0), pure-Rust native macOS application (`krill-app`, built with `gpui`) and headless CLI (`krill`) for running parallel AI coding agents — Claude Code, OpenAI Codex, Gemini CLI (`agy`), Cursor, and OpenCode — in isolated Git worktrees without ever losing a terminal session. By splitting the UI (`krill-app`), the session daemon (`krilld`), and the PTY parent (`krill-holder`) into three separate processes, agent sessions survive app crashes (`kill -9`), app updates, and daemon restarts with byte-exact terminal replay.

Krill (한국어 요약): Claude Code·Codex·Gemini(agy)·Cursor·OpenCode 등 AI 코딩 에이전트를 Git 워크트리별로 병렬 실행하는 순수 Rust 기반 네이티브 macOS 앱 및 CLI입니다. 화면을 그리는 앱(`krill-app`), 터미널 상태를 해석하는 세션 데몬(`krilld`), PTY 마스터 fd를 보유하는 부모 프로세스(`krill-holder`)를 3단 분리해 앱 강제 종료(`kill -9`)·업데이트·데몬 재시작에도 에이전트 세션이 끊기지 않고 바이트 단위로 복원됩니다.

## Key Facts

- **Website**: https://krill.page
- **CLI Documentation**: https://krill.page/docs (English: https://krill.page/en/docs)
- **Full LLM Reference**: https://krill.page/llms-full.txt
- **Artifact Sharing Portal**: https://share.krill.page
- **Source Repository**: https://github.com/craftowen/krill
- **Latest Release**: https://github.com/craftowen/krill/releases/latest
- **One-Line Installer**: `curl -fsSL https://krill.page/install.sh | bash`
- **License**: Apache-2.0 (`https://www.apache.org/licenses/LICENSE-2.0`)
- **Platform**: macOS (Apple Silicon `arm64` release bundle; Intel Mac supported via source build with Rust 1.98+)
- **Tech Stack**: Pure Rust (`gpui` GPU UI, `alacritty_terminal`, `zstd` cold scrollback segments, Unix domain sockets `0600` + `getpeereid`, `SCM_RIGHTS` file descriptor handoff)
- **Memory Budgets (Release-Gating Design Targets @ 10 Terminals, `phys_footprint`)**:
  - `krill-app`: ≤ 120 MB
  - `krilld`: ≤ 60 MB
  - Combined target: ≤ 180 MB (hard release gate: 200 MB)
  - Existing measured test record (daemon soak, 10 sessions 120×40 × 24 accelerated epochs, app excluded): **47.39 MiB** `phys_footprint`; app `SIGKILL` survival **3/3 runs** with **408,058 bytes** SHA-256 exact match.

## Architecture: Three-Tier Process Isolation

1. **`krill-app` (gpui UI)**: Draws only visible screen snapshots and row deltas (no duplicate `Term` mirror in the UI process).
2. **`krilld` (Session Daemon)**: The single terminal query responder. Maintains per-session `alacritty_terminal` (1,000 hot rows), `zstd` cold scrollback segments, agent status hooks, Git worktree/diff queue, and multi-agent orchestration.
3. **`krill-holder` (PTY Parent)**: Tiny (`≤ 1,250` lines on macOS), panic-free process that owns PTY master file descriptors and hands them to `krilld` over Unix domain sockets via `SCM_RIGHTS`.

### Failure Survival Matrix

- **App crash / quit / update (`kill -9 krill-app`)**: Agent processes stay alive. Output replays losslessly within ring/segment retention (overflow is explicitly marked as an `N bytes skipped` gap).
- **Daemon crash (`kill -9 krilld`)**: Agent processes stay alive (`krill-holder` retains PTY master fds and relaunches `krilld`). Unpersisted in-flight bytes are shown as an explicit gap marker after restart.
- **Daemon upgrade**: Agent processes stay alive with lossless output (reader paused and segments sealed before fd handoff; single daemon generation with zero orphan daemons).
- **Holder-only crash**: Agent processes stay alive (`krilld` also holds open fds); lossless output, only process exit codes are lost.
- **Simultaneous holder + krilld loss / OS reboot**: Processes terminate; screen restores read-only up to the last persisted segment so users can run `claude --resume` or `codex resume`.

## Core Capabilities

- **Agent-Agnostic PTY Persistence**: Works identically for Claude Code (`claude`), OpenAI Codex (`codex`), Gemini CLI (`agy`), Cursor (`cursor`), OpenCode (`opencode`), shells (`zsh`, `bash`), dev servers, and any TUI.
- **Parallel Git Worktrees & Diff Review**: Create and remove worktrees (`krill worktree new/rm`), inspect changed files (`krill changes`), and review read-only diffs per worktree.
- **Six Agent States & `Needs You` Queue**: `working`, `waiting`, `blocked`, `done`, `exited`, `unknown`. `krill hook` translates agent lifecycle events into macOS notifications, Dock badges, and the top-of-sidebar "Needs You" queue.
- **Multi-Agent Orchestration (`krill orchestration`)**: Coordinator runs (`run-create`), dependent task DAGs (`task-create --deps`), isolated worker dispatch (`worker-start`), coordinator↔worker messaging (`send`, `check --wait`, `ask`, `reply`), and human decision gates (`gate-create`, `gate-resolve`).
- **Sandboxed Artifact Sharing (`share.krill.page`)**: Publish HTML or Markdown reports (`krill artifacts share/update/unshare/list/delete`) with a 90-day TTL, up to 2 MB, sandboxed CSP viewer, and Orca-compatible `/v1/artifacts` HTTP API.
- **First-Class Korean (Hangul) IME**: Dedicated IME state machine ensuring Hangul composition (`안녕하세요⏎`) enters agent prompts without dropped, duplicated, or reordered characters.
- **Headless CLI & Remote SSH**: Every operation works via the single `krill` binary even when `krill-app` is closed, including `krill attach <id>` from any terminal and `krill --host <user@host>` over SSH Unix-socket forwarding.

## Documentation & Resources

- [Landing Page (Korean / English)](https://krill.page/): Overview, interactive UI preview, architecture diagram, and failure matrix.
- [English Landing Page](https://krill.page/en): Direct English entry point.
- [CLI Reference & Quickstart](https://krill.page/docs): Complete command-line reference and installation guide.
- [Full LLM Documentation (`llms-full.txt`)](https://krill.page/llms-full.txt): Single-file comprehensive documentation for AI assistants and RAG pipelines.
- [One-Line Installer (`install.sh`)](https://krill.page/install.sh): Verifies release ZIP SHA-256 and `codesign --verify --strict` before installing `/Applications/Krill.app` and `~/.local/bin/krill`.
- [Artifact Sharing Portal (`share.krill.page`)](https://share.krill.page/): Public sandboxed viewer and REST API for HTML/Markdown agent reports.
- [GitHub Repository](https://github.com/craftowen/krill): Source code, issue tracker, architecture docs, and releases.