claudine

name

claudine

description

Use when working in the claudine/ package area or with the Claudine library/CLI — normalizing agentic-CLI lifecycle events and hooks, wrapping providers (Claude Code, Codex, Gemini, Goose, Kimi, OpenCode, Qwen, Kilo, Pi, Antigravity), composing Markdown prompts (compose/inline-compose/sequence), managing the MCP catalog, linking skills/commands/agents across providers, or researching agentic CLI platform behavior.

Overview

Claudine is a universal event handler, shared-resource linker, MCP catalog manager, and composition harness for agentic CLIs. It normalizes 16 lifecycle events across 10 providers (Claude Code, Codex CLI, Gemini CLI, Goose, Kimi Code, OpenCode, Qwen Code, Kilo, Pi, and Antigravity) into a single configuration model, fires 6 action types — TTS, sound effects, logging, shell commands, reports, and blocking calls — when those events fire, synchronizes skills/commands/agents/scripts between providers, manages a provider-agnostic MCP catalog plus provider-specific import/sync/runtime behavior, and provides three Markdown composition commands (compose, inline-compose, sequence) that flow through the same wrapper-grade execution pipeline as the provider wrappers.

The 10 providers above are the compiled Provider enum (PROVIDER_COUNT = 10); the research roster (claudine/docs/providers.yaml) is currently in sync with it (Kilo, Pi, and Antigravity graduated through the Phase H provider ladder, 2026-07-08). The roster is designed to run ahead of the enum during onboarding (a new entry is active-but-unwired until its variant lands) and carries skip_research: true for keep-identity-but-pause deprecations. Roo Code support was removed in 2026-07; major provider version changes enter the roster as new entries rather than mutating existing ones (see "Major-version changes are new providers" in the spec below). The provider-metadata automation workstream — research-driven metadata, codegen, signal catalog, the model ground-truth catalog, and the unified dispatch guard — is complete (RATIFIED & IMPLEMENTED, claudine/features/_completed/2026-07-02-provider-metadata/spec.md); consult it before extending provider metadata by hand. Each lib/src/provider/<slug>/data.rs is GENERATED by claudine-gen (in claudine/gen, using shared vocab from the leaf claudine/catalog-types crate) from roster + facts + research + overrides (regenerate with claudine providers generate; drift-checked in CI) — only behavior.rs is hand-written. A single site-level drift guard (claudine-cli/tests/dispatch_inventory.rs) prevents new decentralized match Provider dispatch from regrowing across both lib/src and cli/src.

The package follows the monorepo lib + cli split: library crate claudine, CLI crate claudine-cli (binary claudine). A third sub-crate, claudine-contract (claudine/contract), implements biscuit_contract::inference::InferenceAdapter by running a provider as a single non-interactive, tool-free, filesystem-isolated session and returning its final assistant text — letting deterministic consumers (Reaper, Darkmatter) delegate to an agentic CLI via Arc<dyn InferenceAdapter> without depending on claudine directly. It depends on claudine (lib) but not claudine-cli. v1 enables Claude and Codex; other providers are reported Unsupported. See claudine/contract/README.md for the provider support matrix and security posture, and the biscuit-contract skill for the contract itself.

Alongside these, claudine/rendezvous/ is a first-class package-area family of three crates backing claudine dashboard and the (unwired) lifecycle defer scheduler, in a core → {daemon, client} shape: rendezvous-core (leaf — protobuf/gRPC stubs, identity, signed envelopes, sync wire framing, and the typed LocalEndpoint), rendezvous-daemon (the long-running service: gRPC over the platform's local endpoint, the redb → Loro → DuckDB session-log pipeline, register store, QUIC sync engine), and rendezvous-client (the portable connect(&LocalEndpoint) plus a thin gRPC test client). Both leaf crates depend on rendezvous-core, never on each other. Its area justfile (cd claudine/rendezvous) exposes just check|build|test|lint, each iterating all three crates.

The local control plane is platform-native and per stable OS user: a Unix-domain socket on macOS/Linux/WSL, a Windows named pipe on native Windows, qualified by the effective UID or process-token SID from sniff::os::current_user_id() — never a username. One portable spawn_local_server binds it to a transport-neutral daemon built exactly once. Read claudine/docs/rendezvous/local-ipc.md before changing endpoint, daemon-boot, or connector behavior; see architecture.md → Rendezvous Package-Area Family for the crate roles, the local-IPC rules, and the SessionLogManager module boundary.

Where to look next:

• For library internals (module structure, key types, provider adapters, dispatch, stream parsing) → architecture.md
• For full per-command documentation → cli-reference.md
• For when/why a feature changed → timeline.md
• For a specific subsystem → the deep topic docs under Reference Documents

Library Module Map

The primary public modules are below; the shared error type and flat provider_id leaf sit beside them. Full detail is in architecture.md.

Module	Responsibility
actions	Hook action types and responses
badges	Styled terminal badge constants
composition	Markdown frontmatter composition (direct/inline/sequence) plus the loop engine
config	Agent detection, hook registration, atomic writes, backups
diagnostics	Typed diagnostic facets, discovery, effective selection, and snapshots
dispatch	Event processing pipeline, templates, matchers, expression bridge
events	The normalized 16-event lifecycle model
harness	Shell audit, timeouts, runtime attempt classification, speech helpers, and kept lifecycle recovery infrastructure (no validation/handler DSL — see Validations and Handlers → Lifecycle Stacks)
hook_adapters	Native hook request/response adapters (parse provider hook payloads; distinct from stream/providers stdout NDJSON parsers)
interrupt	Process-scoped user-interrupt state shared by lifecycle work
linking	Cross-provider resource sync with portability classification
mcp	Catalog, defaults, provider-state, import/export, runtime injectors
messaging	Outbound routes (Discord/Slack/Signal/WhatsApp); desktop notifications are separate and zero-config
model_catalog	Model validation against the generated expected-offerings baseline (+ user overrides), family_latest alias resolution, and the dynamic-listing drift channel
opencode_config	OpenCode configuration parsing and projection
permissions	Provider-agnostic policy engine (PolicyEngine)
protect	Standalone regex deny catalog (bash commands, write/edit paths, MCP responses)
provider	Generated provider metadata registry plus hand-written behavior
render	Functional render components — FinalMessage, AgentPrompt/SystemPrompt (under render/prompt/, absorbed the former prompt_reporting module), EventRenderer + the exhaustive DISPATCH table (live-sink stderr status dispatch), the dual-target MetricsReport (TerminalRenderable + BrowserRenderable), and the StreamRenderable span contract (open/append/flush_idle/close) with its AssistantStream streaming-markdown component, and TaskStream/TaskStreamFrame + the two-channel TaskStreamSink seam and its TaskLiveOutput binding (attributed color-bar framing for group tasks — headers/footers on the status channel, task body data on the data channel; TaskBar::Invisible gives serial work the same geometry); all consume data + policy (DisplayPolicy), never match provider
reporting	JSONL-to-SQLite metrics index
runaway	Pure content-guard detector (exit-expressions, group-cycle repetition, volume cap) + per-layer config; trips map to ProcessTermination::Aborted
signals	Generated and bespoke normalized signal catalog and hub
stream	Structured stream parsing through 8 parser implementations for 9 provider identities (typed models in stream::protocol; Kilo reuses OpenCode's parser; Goose has no native stream parser)
system_prompt	Launch-CWD detection (LaunchContext), system-prompt.md discovery, ResolvedSystemPrompt resolution
provider_id (leaf)	Provider enum, provider_info(), PROVIDERS_DISPLAY_ORDER, OutputFormatSelector (split from provider/mod.rs to break the provider ⇄ stream import cycle)

CLI Commands

The claudine binary provides interactive setup, hook inspection, event handling, shared-resource management, MCP management, log reporting, provider wrapping, and Markdown composition. Output flows through a structured logging system that separates pipeable data (stdout) from status messages (stderr), formatted with biscuit-terminal components. Provider names accept fuzzy matching (exact → prefix → contains), so cl resolves to claude. Full reference: cli-reference.md.

Shared Resources

Command	Description
claudine skills	List skills across providers and show link/sync state
claudine commands	List slash commands across providers and show link/sync state
claudine agents	List agent/subagent definitions across providers and show link/sync state
claudine mcp [list|init|show|default|alias|remove|sync] [--json]	Manage the normalized MCP catalog, defaults, validation, refresh, and sync state

Hook Events and Actions

Command	Description
claudine hooks [provider]	Show registered hooks for all or one provider
claudine hooks --support	Provider event support matrix
claudine hooks --mapping	Native event name mappings per provider
claudine hooks --describe	Event descriptions and payload schemas
claudine hooks --variables	Template variables with current values
claudine actions	Show which actions are configured and for which events
claudine handle <event> [--provider]	Process event from stdin (hidden; called by hook registrations)

Wrapped Execution

Command	Description
claudine claude|codex|gemini|goose|kimi|opencode|qwen|kilo|pi|antigravity	Wrap a provider CLI with preflight checks, env sanitization, system prompt resolution, optional --edit prompt drafting, MCP injection, and structured streaming where the provider exposes it

Composition

Command	Description
claudine compose <file> [key=value ...]	Compose a Markdown file and send the result as a prompt (no file mutation)
claudine inline-compose <file> [key=value ...]	Use frontmatter prompt to generate content and replace the body; preserves frontmatter, updates last_updated, stamps a Darkmatter Simple hash:
claudine sequence <file> [key=value ...]	Run an ordered list of steps — static preflight over the whole task graph, then just-in-time composition at each step's turn; tasks, groups (serial/parallel), and the outputs accumulator

Administration

Command	Description
claudine init [--quick] [--repo]	Interactive setup wizard (4 phases) or quick defaults
claudine config	TUI for managing configuration, including messenger routes
claudine sync [--dry-run] [--provider] [--fix]	Re-apply hook registrations
claudine uninstall [--keep-config]	Remove hooks from all agents
claudine providers	Provider capability matrix, catalog generation, and deterministic agent-errors research checks
claudine logs [today|week|month|sessions|tools|errors|repos|trends|drift|sync]	Reporting and sync for Claudine JSONL logs
claudine dashboard [--local]	Mesh NOW view: live sessions across rendezvous hosts, with per-host staleness and the needs-human-intervention signal (reads the rendezvous daemon)
claudine completions <shell>	Generate shell completions
claudine context [--values|--expressions|--side-effects]	Show Darkmatter context variables, expression engine, and side-effect capabilities
claudine (no subcommand)	Render rich grouped help

Context command: claudine context renders from Darkmatter's public typed descriptor catalogs, not from parsed Markdown. The default report shows every context variable grouped by category with Property (ctx.NAME), Type, and Description columns. --values replaces Description with live captured values (nulls shown, not dropped). --expressions shows the expression-language overview — precedence, truthiness, unary/comparison/arithmetic operators, variable access, parse modes, null propagation, and the complete function catalog grouped by category — with an Example column where layout permits. --side-effects shows the capability catalog with Capability, Description, Safety, and Example columns; the Example column is hidden below 70 characters to preserve the minimum-supported-width floor. It is documentation-only and does not invoke, probe, or check availability of any capability. All reports share a 140ch-inclusive width contract, inverse-styled inline code, and UnorderedList bullet formatting. Every report table fills to the right margin (configure_shared_table sets width: 100% via the shared Table's Width::Fixed(Length::Percent(100)); the last column absorbs the slack) so tables with and without wrapped cells share one right edge — and the Example column carries a per-table min_width floor so a long Description cannot starve it.

Wrapper & composition subsystems — each row is a pointer; depth lives in the linked doc:

Subsystem	In one line	Reference
Argv pre-parsing	argv::normalize rewrites composition-subcommand argv before clap (provider booleans → --provider, --help hoisting)	CLI Pre-Parsing
System prompt	File-backed --append-system-prompt/--asp + --replace-system-prompt/--rsp, launch-CWD system-prompt.md discovery, per-provider delivery; direct wrappers also take --edit	System Prompt
Timeouts	Two rules only — timeout (wall-clock, opt-in) and step_timeout (stream-silence, default 30m)	Timeouts
Runaway content guards	Three volume backstops — exit_expressions, runaway_repetition (≥30 cycles), runaway_volume (50k lines / 32 MiB) — mapping to Aborted/AgentFailure, never a retry	Timeouts § Content guards
OpenCode stalled-generation	Live-but-dead backstop: trips only on retry churn and progress silence (stall_timeout, default 10m); not a third timeout	Timeouts § Stall · OpenCode Event Sources
Signals	One signal-aware wait loop across every spawn path; per-press stderr feedback, SIGTERM → SIGKILL ladder, _exit(130) second-press guard, Windows parity	Signal Handling
Transient overlays	Written under <repo_root>/.claudine/tmp/ (or <launch_cwd>/.claudine-tmp/), cleaned up on Drop	System Prompt
Schema validation	$schema runs Darkmatter SimplifiedSchema; typed errors, null-as-absent, a biscuit-tui prompt loop for required-missing values	Composition § Schema
Error architecture	One discovery seam (as_diagnostic) + one role-based selection walk; rendering, err.*, and machine output all project the same effective diagnostic. Read before adding an error type or a catalog code	Error Architecture
Composition diagnostics	Prepare-time did-you-mean warnings (unknown function / ctx.*, --silent-suppressed); frontmatter-rooted errors append a highlighted, line-numbered YAML block (TTY-gated)	Composition
Whole-value frontmatter	A value that is exactly one {{ … }} / $(…) span is executable state — it must resolve and must never leak as raw syntax	Composition § Whole-value
Sequences	Two phases: static preflight over the whole task graph (dynamic sources snapshot once, shell approved byte-for-byte, no exceptions), then just-in-time composition at each step's turn against the live file. One executable per task; outputs is the sole accumulator; groups run serial or parallel	Sequences · architecture.md § Sequences
Lifecycle stacks	Seven flow-control verbs (stop/skip/error/proxy/retry/resume/defer; defer unimplemented), two action forms, early/late binding via Darkmatter DM1/DM2 (strict, fail-closed), leak & err-placement guards, no_error, the stdout channel	Lifecycle
Document handoffs	proxy swaps the active document; one coordinator owns identity, one canonical service prepares every entry reason, so a proxied target behaves like the same document invoked directly. Key/value proxy.with: adds a transient, source-evaluated, typed frontmatter overlay for the immediate target	Lifecycle § Proxy Handoffs · Composition § Handoffs
Retry/resume re-entry	Both replace only the provider-attempt slice: canonical fresh read, overlay + provenance kept, budgets decrement, no second initialize. The whole launch bundle is recomputed at that fresh read, not snapshotted at adoption, and that bundle is the launch — a retry spawns under the refreshed plan. resume also compares a session-compatibility key and refuses (LifecycleResumeIncompatible) when a facet moved — every document-reachable facet refuses end-to-end; workspace CWD and system-prompt content are immutable invocation inputs	Lifecycle § Retry and resume · Composition § Retry and resume
Dry run	--dry-run stops at a seam right after provider/model resolution — no selected-executable validation, lifecycle events, MCP/argv/CWD setup, proxy traversal, or inline-compose mutation. The selected agent need not be installed. ::shell spans in the document graph are composition, not lifecycle, and still run for real	Composition § Dry Run
Protect	protect::observe classifies bash- and write-shaped tools; best-effort defense-in-depth, not a security boundary	Protect Service

MCP Support

Claudine stores normalized MCP data in ~/.claudine/mcp/catalog.json, ~/.claudine/mcp/defaults.json, and ~/.claudine/mcp/provider-state.json, with optional repo defaults in <repo>/.claudine/mcp.json (repo defaults replace user defaults).

Provider rollout:

• Import and sync: Claude, Codex, Gemini, OpenCode
• Runtime wrapper injection: Codex, Gemini, OpenCode
• No MCP support yet: Goose, Kimi, Qwen

Wrapper behavior: --mcp launches with effective defaults; --use id-or-alias[,...] adds explicit servers and enables MCP mode. Codex/Gemini inject via a shadow HOME under ~/.claudine; Codex keeps SQLite state at its pre-shadow native sqlite_home/CODEX_SQLITE_HOME/CODEX_HOME destination so database and WAL/SHM files are never linked into the overlay. OpenCode uses OPENCODE_CONFIG_CONTENT. Claude, Goose, Kimi, and Qwen wrappers direct users to claudine mcp export <provider> --apply instead. Read MCP Catalog and MCP Mode before changing MCP behavior.

Reference Documents

Skill docs (in this directory)

• Architecture — module structure, event matrix, key types, provider adapters, dispatch, stream parsing, composition, linking, exit codes
• CLI Reference — full per-command documentation, flags, output system, exit codes, file locations, env vars
• Change Timeline — condensed history of significant features and refactors
• Supported Platforms
• Unified Hook/Event Model
• Supported Actions
• Linking Strategy
• Non-Portable Assets
• PolicyEngine
• Validations and Handlers → Lifecycle Stacks — the retired validation/handler DSL and its lifecycle-stack replacement
• OpenCode Event Sources — Dual-Source Contract, stderr promotion table, watchdog interaction

Portable topic references

These materialized skill-local snapshots keep the operational references portable. Update them alongside the authoritative Claudine topic docs when behavior changes.

• Error Architecture — the Diagnostic/BlockError pair, the discovery seam, effective-diagnostic selection and the Semantic/Transparent role contract, the snapshot boundary, typed-wrapper rules, and the lossy-boundary audit
• Composition — compose, inline-compose, sequence, lifecycle stacks, provider selection
• Timeouts — the two timeout rules, four env vars, precedence, termination path, exit reasons, and the three runaway content guards
• Signal Handling — user Ctrl+C vs wrapper-driven SIGTERM/SIGKILL, the unified wait loop, termination labels (Aborted/Interrupted/TimedOut), non-interactive ladder, Windows parity
• System Prompt — launch-context discovery, --append/--replace, Darkmatter preparation, per-provider delivery
• MCP Catalog and MCP Mode
• Protect Service — deny catalog, scan surfaces, rule groups, merge semantics, dispatch integration
• Messaging — outbound routes (Discord/Slack/Signal/WhatsApp), the config-TUI route manager, webhook redaction invariants, the desktop-notification boundary
• Traces and Logging, Log Reporting
• CLI Pre-Parsing — argv normalization pipeline; rule-by-rule reference in argv-normalization.md
• Shell Completions — dynamic completion engine, per-mode pipelines, magic @ resolution

Research on Agentic CLI Platforms

Cross-provider Summaries

Curated comparison documents distilling each research fleet across all providers. Start here for "how does X vary across providers"; drop into the per-provider research docs below for depth. Generated by claudine sequence from the prompt documents in claudine/docs/research/summary/ and published here via just publish-summary-research (run from the claudine/ package area).

• Protocols & session shape: MCP · ACP · Hooks · System Prompt · Non-Interactive Sessions · Session Resumption
• Provider identity & operations: CLI Identity · Logging · Models · Permissions
• Shared assets & model extension: Skills · Slash Commands · Subagents · Plugins · Model Config · Local Runners

Hooks Research

Each Agentic CLI's provided hooks, payloads, and return types.

• Claude Code · Codex · Gemini CLI · Goose · Kimi Code · OpenCode · Qwen CLI

Cross-referencing Research

Each Agentic CLI's support for skills, slash commands, agents/subagents, and shared scripts folders.

• Claude Code · Codex · Gemini CLI · Goose · Kimi Code · OpenCode · Qwen CLI

ACP Support

Claudine does not use ACP today but may add it. For ACP work use the acp skill; for ACP + observability use the agent-observability skill. Cross-provider ACP support comparison: summaries/acp.md.

Topic Research (schema-enforced fleets)

Per-provider, per-topic research documents produced by claudine sequence over the roster, with structured facts in frontmatter validated by a _schema.yaml sidecar ($schema: ./_schema.yaml). Live topics under claudine/docs/research/:

• agent-logging/ — log surfaces, per-site time semantics (unit/zone), record types
• agent-models/ — out-of-box models, selection mechanisms, precedence, dynamic listing
• agent-permissions/ — permission CLI params, config files, YOLO, PolicyEngine fit
• agent-errors/ — ordered structured-stream error vocabularies with per-needle provenance; generation projects these research records into lib/src/stream/providers/vocabulary.rs. Immutable Phase-A baselines under agent-errors/_seeds/ let the deterministic gate detect removals, re-kinds, and reorders after facts graduation. New parser-backed providers must research this topic rather than add keyword constants or facts seeds. The 2026-07-14 live roster converged in ten clean first attempts; its 55 accepted additions are locked by generated-row, precedence, exact-code, and near-miss tests.
• model-config/ — user-side model extension (cloud + local) across all 9 roster providers: config files/formats, API standards spoken (api_standards), local-runner integration paths framed as API-standard bridging (local_runners[].integration: first_class / base_url_override / proxy_required / unsupported), cross-cloud bridging (cloud_bridge), merge semantics, env overrides. Refreshed 2026-07-02 against local-runners ground truth (refresh notes: model-config-refresh.md). For configuration depth, prefer the model-config skill (distilled comparison tables); the research docs remain the source of truth.
• local_runners/ — the runner-side counterpart to model-config: local model runners (Ollama, LM Studio, oMLX, Llama.cpp, vLLM) as servers — per-OS binaries and installs, OpenAI/Anthropic API surfaces, detection probes, config, model-id grammar, traps. Roster: claudine/docs/local-runners.yaml; spike notes: spike-local-runners.md. For runner-specific depth, prefer the local-runners skill (distilled tables); the research docs remain the source of truth.
• agent-cli/, non-interactive-sessions/, usage/ — earlier topics; sidecars authored (every live topic directory carries a _schema.yaml sidecar as of 2026-07-03, including mcp/, acp/, hooks/, resume/, skills/, slash-commands/, subagents/, plugins/, and system-prompt/)

The pattern (sidecar rules, lifecycle verification stacks, pilot technique) is documented in claudine/features/_completed/2026-07-02-provider-metadata/spec.md and its spike findings. New topics follow that recipe; do not invent a parallel research format.