Caliban captures every significant architectural decision in an Architecture Decision Record (ADR). Each ADR states the context, the decision, and its consequences — giving contributors (and curious operators) the rationale behind the design, not just the outcome.
ADRs live in the docs/adr/ directory of the repository. They use a lightweight MADR-lite format and carry a status:
accepted — currently in effectsuperseded — replaced by a later ADR; kept for historyproposed — under discussion, not yet in effectrejected — considered and explicitly declined
This is the contributor/internals layer
You do not need to read ADRs to use caliban. They exist for contributors and operators who want to understand why something works the way it does. For crate orientation, see Crate Map .
# Title Status
0000 Record architecture decisions (MADR-lite under docs/adr/) accepted 0001 Async runtime → tokio accepted 0002 Error model → thiserror for libs, anyhow for binary accepted 0003 License → AGPL-3.0-only accepted 0004 Naming → caliban-* libraries, caliban binary accepted 0005 Workspace layout → crates/ for libs, binaries at root accepted
# Title Status
0006 Message schema → provider-neutral IR accepted 0007 Schema/transport factoring via Transport trait accepted 0008 Role::System is positional (leading-only)accepted
# Title Status
0009 Agent-core design (stream-as-primitive, sequential tools, opt-in compaction) accepted (sequential-tools clause superseded by 0016) 0010 WorkspaceRoot path resolution + opt-in restricted mode accepted (restricted-mode default amended by 0048) 0016 Parallel tool dispatch (semaphore-bounded; supersedes 0009 sequential clause) accepted 0021 Sub-agent primitive (AgentTool; synchronous in-process; allowlist-filtered registry) accepted
# Title Status
0011 Sessions persisted to disk + interactive REPL accepted 0012 TUI via ratatui (replacing the rustyline REPL) accepted 0013 TUI overlays + layout v2 accepted 0014 Default system prompt + TUI stall fixes + debug logging accepted 0015 Context preservation + path conventions (~ expansion) accepted 0027 TUI ergonomics (@file, !, Ctrl+G, Ask modal, transcript viewer) accepted 0041 TUI redraw tick — close-out (resolves 0014 open question) accepted
# Title Status
0018 Memory tier model (global / project / auto-memory; spliced into system prompt) accepted 0028 Auto-checkpointing + /rewind accepted 0035 Auto-memory (model-written notes per project) accepted 0036 CLAUDE.md ancestor walk + @-imports accepted
# Title Status
0020 Permission rules layered on Hooks (TOML rule sources; interactive Ask) accepted 0029 Permission modes (acceptEdits / auto / dontAsk / bypassPermissions) + auto-mode classifier accepted 0032 OS-level sandbox (macOS Seatbelt + Linux bubblewrap) accepted (confinement posture refined by 0054) 0045 Permissions v2 — TOML-primary config + richer rule schema accepted 0048 --workspace restricts file/shell tools by default (amends 0010)accepted 0054 Sandbox confinement posture — keep filesystem reads open, close network egress by default under --workspace (refines 0032) accepted
# Title Status
0026 Unified settings hierarchy (managed > user > project > local) accepted 0043 arc-swap as the read-mostly shared-state primitiveaccepted 0050 XDG-first path locations on all platforms (drops the macOS-native ~/Library default; amends 0017) accepted
# Title Status
0019 Skills loading & invocation (frontmatter + body; SkillTool on-demand load) accepted 0024 Hook event taxonomy (expanded events + handler types) accepted 0030 Plugin packaging (skills + hooks + agents + MCP + output-styles bundles) accepted 0031 Output styles (Default / Proactive / Explanatory / Learning + custom) accepted 0040 Slash command registry (extensible SlashCommand trait) accepted
# Title Status
0017 MCP client architecture (stdio v1; tools surface as mcp__<server>__<tool>) accepted (stdio-only scope superseded by 0023; macOS mcp.toml path amended by 0050) 0023 MCP v2 — transports, OAuth, elicitation, resources accepted 0044 rmcp 1.7 version pin (dedicated-PR bumps)accepted 0046 Two-stage tool surface — lazy MCP schema loading + ToolSearch accepted
# Title Status
0022 Model routing architecture (Layer 3 caliban-model-router; router-impl-Provider) accepted 0034 Bedrock + Vertex providers accepted 0038 Model router v2 (fallback / hedging / circuit breakers / capability filtering) accepted 0039 Image / vision input accepted
# Title Status
0025 Headless / print mode + JSON output protocol accepted (result-frame shape amended by 0049) 0033 OpenTelemetry export + cost accounting accepted (GenAI semconv scope refined by 0053) 0049 Result-frame enrichment toward the Claude Code contract (amends 0025) accepted 0053 OpenTelemetry GenAI semantic conventions — emit gen_ai.* only, no vendor-specific or cost attributes (builds on 0033) accepted
# Title Status
0037 Sub-agent worktree isolation + background fleet accepted (runs-to-completion non-goal revised by 0047; per-repo identity + worktree isolation amended by 0052) 0042 caliband sibling-binary placement (under caliban-supervisor)accepted 0047 Interactive background sub-agents (idle / await-input; amends 0037) accepted 0051 caliband network transport — NDJSON over TCP+TLS with a bearer token (Unix socket retained for local; gRPC deferred)accepted 0052 Workspace-scoped caliband — multi-source workspace identity + wired per-source worktree isolation (amends 0037) accepted