AGENTS.md

Clanky Monorepo

This repository contains the public Clanky system packages as one GitHub monorepo. Clanky is a swarm visibility and management engine: clanky-agent is the lead agent that spawns, watches, and harvests worker harnesses as visible panes on the bundled clanky-herdr terminal multiplexer; the other packages are the presence plane, the wire contract, and the private iOS window. Each top-level package keeps its own toolchain, lockfile, and package-level instructions; read the package AGENTS.md or README before editing inside it. Internal full checkouts also contain the private clanky-ios/ package, which is excluded from the public tree and public Git history.

Packages

Dir	Role	Tooling	Primary docs
`clanky-agent/`	Lead agent brain (Eve): spawn/watch/harvest loop, channels, Herdr-backed command host, custom pi-tui face, bundled runtime skills	pnpm	`clanky-agent/SPEC.md`, `clanky-agent/AGENTS.md`
`clankvox/`	Presence plane: Rust Discord voice / Go Live realtime media	cargo, pnpm for docs	`clankvox/README.md`, `clankvox/docs/architecture.md`
`clanky-contract/`	Shared TypeScript wire schemas for relay, Eve session, lifecycle, pairing, and app-facing contracts	pnpm	`clanky-contract/README.md`
`herdr/`	`clanky-herdr`, the bundled terminal multiplexer (Clanky-owned Herdr fork) where worker harnesses run as visible panes; pane/session API and fork-carried mux capabilities	cargo, just, bun for integration assets	`herdr/README.md`, `herdr/AGENTS.md`
`packages/create-clanky/`	Private/pre-public npm bootstrapper that clones a checkout and delegates to `scripts/install.sh`	node	`packages/create-clanky/README.md`

Worker harnesses — Claude Code, Codex, OpenCode, or Clanky's own clanky worker CLI — are the coding agents: the lead agent spawns them as clanky:<slug> panes on Herdr and they do the actual coding.

flowchart TB
  subgraph repo["Clanky monorepo"]
    agent["clanky-agent<br/>lead agent brain + command host + face"]
    vox["clankvox<br/>presence plane"]
    contract["clanky-contract<br/>wire schemas"]
    herdr["clanky-herdr<br/>bundled terminal multiplexer"]
  end
  ios["clanky-ios<br/>private mobile window"]
  workers["worker harnesses<br/>workers: Claude Code, Codex, OpenCode, clanky worker"]

  agent -->|spawn + watch + harvest| workers
  herdr -.->|"hosts as clanky:slug panes"| workers
  agent <-->|stdin/stdout IPC| vox
  ios <-->|tailnet supervisor + relay WS| agent
  agent --> contract
  ios --> contract
  agent <-->|mux + pane/session API| herdr

Working Here

Treat each top-level directory as a package boundary. Run package tooling from that package directory unless a root workflow/script explicitly says otherwise.
The root package.json is only a private Git/npx shim for create-clanky; keep actual package installs and lockfiles package-local.
Use pnpm only for TypeScript packages. Do not introduce npm lockfiles.
Use cargo for clankvox; pnpm there is for the docs site only.
Use just from herdr/ for Herdr checks; Herdr's own AGENTS.md remains authoritative for fork work.
Treat clanky-ios/ as private-only. Public export removes that directory and the internal TestFlight workflow before publishing.
Preserve package-local docs and update them with code changes. Root docs are only the cross-package map.
Cross-surface API changes start with the agent/contract shape, then wire iOS or ClankVox to that contract.
Keep secrets and local state out of git. Package-local .gitignore files still apply under their package directories.
The Clanky lead agent may merge its own workers' PRs to master autonomously once it has reviewed the diff and the required checks are green — no human wait. After merging, fast-forward local master so it never falls behind origin. Reserve hand-off for changes that genuinely need a human (on-device or taste verification, credentials, or irreversible/outward-facing ops). The per-integration "can the lead merge PRs" lever is the planned mechanism (see the delegation-profiles / integration protocol work, VUH-599).

Common Commands

cd clanky-agent && pnpm check && pnpm lint
cd clankvox && cargo test --locked --all-features
cd clanky-contract && pnpm typecheck
cd clanky-ios && pnpm --filter @clanky/mobile check
cd herdr && just ci 'all()'

The public root GitHub Actions workflow runs the public package gates from their respective directories. The internal iOS Mobile workflow runs the private mobile fast gate on clanky-ios and clanky-contract changes; its production TestFlight/EAS build is a manual workflow_dispatch release lane.

The monorepo decision, public/private split, clanky-herdr placement, and shipping it as the bundled terminal-multiplexer binary are recorded in docs/adr/0001-clanky-monorepo.md, docs/adr/0004-public-mirror-private-ios.md, docs/adr/0003-herdr-fork-in-monorepo.md, and docs/adr/0005-clanky-ships-its-stage.md.