bherdr

bherdr is a FreeBSD-focused Go port of herdr, the terminal workspace manager for AI-agent sessions. It carries forward a versioned subset of Herdr's CLI, socket API, session format, and agent-detection contracts.

The installed command remains herdr; bherdr is the repository and package identity.

Role in Clawdie

bherdr owns the terminal/session boundary:

zot / pi  ←→  bherdr (`herdr` process, panes, PTYs, sessions)
                         │ newline-JSON socket API
                         ▼
                 Colibri control plane
                 tasks, lifecycle, MCP, ledger

Colibri consumes bherdr as a process through its socket API. There is no shared library, Go dependency, or cgo/FFI boundary with Colibri; bherdr remains the terminal/session component and Colibri remains the orchestration and memory component.

What bherdr provides

• FreeBSD-native process and agent detection through kinfo_proc.
• Terminal sessions, panes, PTY ownership, events, and the compatible socket contract.
• FreeBSD jail integration and packaging-oriented deployment primitives.
• Compatibility with the observed herdr protocol and session behavior.

The compatibility contract is docs/COMPATIBILITY-SPEC.md. It defines the supported surface and records source and behavioral provenance.

Relationship to Colibri memory

Memory is not owned by bherdr. Colibri's planned memory layer presents one agent-facing contract: remember, recall, forget, and improve. OpenViking provides fuzzy/semantic recall; Oxigraph provides exact relational facts. Agents reach both through Colibri, never by calling Oxigraph directly. The system of record is the source of truth; its concrete representation — authored files, Brain table, or another explicitly chosen store — remains open. OpenViking's semantic index and Oxigraph's graph are rebuildable projections. Every derived triple must be traceable to its source and carry a minimal provenance envelope (source_ref, derived_at, derivation_method as opaque fields); the richer provenance schema, retention, and promotion-from-derivation policy, together with authorship and write authority for canonical records, remain open design questions.

License and distribution

bherdr is distributed under Apache-2.0 as an attributable downstream port of Herdr. NOTICE, upstream attribution, and third-party notices record the distribution obligations. Qualified counsel must review Apache compliance, third-party notices, and Herdr trademark/command-name use before public distribution.

Build and packaging decisions are recorded in docs/wiki/, including the Apache-port decision.

Repository layout

• HOWTO.md — short answers to recurring operational questions (remote-attach status, session nesting)
• docs/COMPATIBILITY-SPEC.md — implementation contract and behavioral evidence
• docs/PHASE-01-SLICE.md — bherdr ↔ Colibri coexistence plan
• docs/VENDOR-HYGIENE-REVIEW-2026-09-29.md — pinned vendor review and unresolved Fira Code distribution evidence
• docs/wiki/ — architecture and design decisions
• AGENTS.md — contributor and agent conventions