fiche v0.17.0
GitHub
ARCHITECTURE · v0.17.0 · wiki/Architecture.md

Pure Core Engine & Host Adapters

fiche intercepts coding-agent inference traffic (or compiles payloads offline via library, MCP, or fiche export) through a strict boundary between a runtime-agnostic pure core (src/core/, zero node: imports) and thin host adapters.

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.

fiche end-to-end architecture diagram
Component topology across CLI/GUI clients, loopback proxy + warp, MCP server, and upstream providers.
fiche request flow and prefix cache seal sequence diagram
Request transformation, append-only prefix-cache sealing, and zero-token telemetry flow.

2. Hybrid Context Compiler Pipeline

STAGE 1

TSCG Schema & Static Compiler

Compacts repetitive JSON tool schemas and static system blocks deterministically while preserving prefix byte identity.

STAGE 2

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.

STAGE 3

ACDC Frozen Epoch Digestion

Amortizes older conversation turns into sealed epoch summaries behind the upstream prompt-cache boundary.

STAGE 4

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 + Unifont 8px 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 (312 cols on Claude/Gemini, 152 cols on GPT).
  • Spaced 5×8 bitmap (5×10 cell): claude-fable-5-1, claude-fable-5-2, and opt-in Claude models (312 cols, 1568×728 max).
  • Native 14px (jetbrains-mono-14, 9×16 cell): opt-in gpt-5.6-sol / gpt-6.1-sol / gpt-6.2-sol (84 cols, 764×1954), opt-in grok-*, and opt-in qwen3.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, and grok (unless FICHE_FORCE_IMAGES=1).

4. Module Map (src/ & apps/)

Module Path Responsibility
Pure Core Enginesrc/core/Zero node: imports: wire transforms, 4-layer text pipeline, optical PNG renderer, cache state, 23-host COMPAT registry, kosha pricing.
Loopback Proxy & CLIsrc/node.ts, src/worker.tsHTTP daemon (127.0.0.1:47821), Cloudflare Workers adapter, fiche export, fiche turn-report, fiche stats.
TLS Warp & App Launchsrc/warp/Local HTTPS CONNECT interceptor + macOS GUI launcher for fiche warp --app and fiche shell-init [--wrap].
Local Dashboardsrc/dashboard.tsWarm Paper live telemetry dashboard, PNG crop inspector, /fragments/plugins, and /api/models controls.
MCP Serversrc/mcp/Stdio & stateless Streamable HTTP MCP server (fiche-mcp / :47823).
Fast Telemetry Tailsrc/turn-report.tsBounded reverse-tail scanner (<5 ms) for CLI rollups, Antigravity PostInvocation, and Claude statusLine.
macOS Companionapps/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.