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 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 0045 Permissions v2 — TOML-primary config + richer rule schema accepted
# Title Status
0026 Unified settings hierarchy (managed > user > project > local) accepted 0043 arc-swap as the read-mostly shared-state primitiveaccepted
# 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 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 0033 OpenTelemetry export + cost accounting accepted
# Title Status
0037 Sub-agent worktree isolation + background fleet accepted 0042 caliband sibling-binary placement (under caliban-supervisor)accepted