1. End-to-End Topology
CLIs (claude, codex, gemini, opencode, agy),
desktop GUI apps via fiche warp --app, and shell wrappers (fiche shell-init --wrap)
route through the local loopback stack on 127.0.0.1:47821 to 23+ first-party and OpenAI-compatible upstream hosts.
2. Hybrid Context Compiler Pipeline
TSCG Schema & Static Compiler
Compacts repetitive JSON tool schemas and static system blocks deterministically while preserving prefix byte identity.
ANSI/CR + @toon + Drain
Strips terminal color codes, replays \r/backspace progress bars, encodes tabular JSON via @toon, and folds repetitive log lines via Drain. Guarded by isCodeOrDiffProtected so numbered reads & diffs remain byte-exact.
ACDC Frozen Epoch Digestion
Amortizes older conversation turns into sealed epoch summaries behind the upstream prompt-cache boundary.
CASI-Delta Cross-Turn Dedupe
Inverted-index line hashing eliminates redundant repeated blocks across turns while keeping live tail edits intact.
3. Model Routing & Font Bands (src/core/reader-tier.ts)
- Dense 5×8 bitmap (
spleen-5x8+Unifont8px fallback):claude-fable-5, measured Gemini vision tiers (gemini-3.6-flash,3.7-flash,3.8-flash,gemini-4-argon),gpt-6(non-Sol), and default GPT fallback (312cols on Claude/Gemini,152cols on GPT). - Spaced 5×8 bitmap (
5×10cell):claude-fable-5-1,claude-fable-5-2, and opt-in Claude models (312cols,1568×728max). - Native 14px (
jetbrains-mono-14, 9×16 cell): opt-ingpt-5.6-sol/gpt-6.1-sol/gpt-6.2-sol(84cols,764×1954), opt-ingrok-*, and opt-inqwen3.8-27b. - Text-only deterministic hygiene (0 images):
claude-opus-5-5,claude-sonnet-5-5,claude-haiku-*,gpt-6*-astra,gemini-4-neon/carbon/hydrogen,deepseek,kimi,glm,minimax, andgrok(unlessFICHE_FORCE_IMAGES=1).
4. Module Map (src/ & apps/)
| Module | Path | Responsibility |
|---|---|---|
| Pure Core Engine | src/core/ | Zero node: imports: wire transforms, 4-layer text pipeline, optical PNG renderer, cache state, 23-host COMPAT registry, kosha pricing. |
| Loopback Proxy & CLI | src/node.ts, src/worker.ts | HTTP daemon (127.0.0.1:47821), Cloudflare Workers adapter, fiche export, fiche turn-report, fiche stats. |
| TLS Warp & App Launch | src/warp/ | Local HTTPS CONNECT interceptor + macOS GUI launcher for fiche warp --app and fiche shell-init [--wrap]. |
| Local Dashboard | src/dashboard.ts | Warm Paper live telemetry dashboard, PNG crop inspector, /fragments/plugins, and /api/models controls. |
| MCP Server | src/mcp/ | Stdio & stateless Streamable HTTP MCP server (fiche-mcp / :47823). |
| Fast Telemetry Tail | src/turn-report.ts | Bounded reverse-tail scanner (<5 ms) for CLI rollups, Antigravity PostInvocation, and Claude statusLine. |
| macOS Companion | apps/macos-bar/ | Native Swift 6 / SwiftUI FicheBar.app with 5 Apple HIG themes and weighted-vs-raw savings clarity. |
5. Append-Only Prefix-Cache Seal & Fail-Open Safety
~/.fiche/session-state.json records sealed epoch boundaries so turns 1..K remain byte-identical across turns,
achieving 80.9–90.9% KV cache hit rates. Requests carrying x-fiche-bypass: 1 pass through verbatim,
and any unexpected transform error fails open so agent sessions never stall.