ADR 0003: clanky-herdr Fork in the Monorepo

• Status: Accepted
• Date: 2026-07-05

Context

Clanky depends on clanky-herdr, its Herdr fork, as the persistent terminal stage. Some stage behavior uses fork work before it is available in upstream Herdr, including pane/session API capabilities used by the agent and mobile window.

Keeping that fork outside the Clanky repository makes stage API changes move on a different commit timeline from the agent and iOS surfaces that consume them.

Decision

The Clanky-owned Herdr fork is called clanky-herdr and lives in the monorepo at:

herdr/

The directory contains the clanky-herdr fork source and its package-local docs, tooling, and instructions. The package remains a Rust project with its own Cargo.lock, justfile, docs site, and Herdr-specific AGENTS.md.

Upstream Herdr remains the rebase source for generally useful terminal-runtime work, but Clanky development treats herdr/ as the local clanky-herdr source tree alongside the agent, iOS app, contract, and media plane.

Consequences

• Stage API changes can land with the Clanky agent and mobile code that depends on them.
• clanky-herdr fork work still follows Herdr's package-local instructions and checks.
• Root CI includes a Linux Herdr check from the herdr/ package directory.
• Herdr build output and local state stay ignored by package-local and root ignore rules.