Accordion: Instructions file for Claude Code

CLAUDE.md — Accordion

Guidance for AI coding sessions. VISION.md = product north star · README.md = short pitch.

Key URLs

• Marketing site: https://get-accordion.dev/
• Public repo: https://github.com/a-Fig/Accordion

Terminology

• pi — the CLI AI coding harness whose context window Accordion visualizes. Not an Accordion product; it's the tool the user runs. extension/accordion.ts is a pi plugin that hooks into pi's context hook (fires before each model call).
• block — atomic unit of context: one chunk of a single kind (system, user, text, thinking, tool_call, or tool_result). See core/types.ts → Block (app/src/lib/engine/types.ts is a re-export shim).
• bolted — a block no actor may fold, group, pin, or replace: not the human, not a conductor, not the agent. Today exactly the system kind (the harness's own prompt, SYSTEM_BLOCK_ID = "sys:0", always the FIRST block, order -1). Predicate: core/digest.ts → isBolted; refusals surface as the "bolted" ClampReason, checked FIRST in every op handler so a conductor learns the PERMANENT reason rather than a misleading incidental one. Distinct from held (a human override the human can release) and from protected (the working tail, which moves as the tail resizes) — bolted is a property of the kind and never lifts. Its tokens ARE counted in liveTokens/fullTokens: a fixed floor, not reclaimable headroom. If no prompt can be sourced, NO block appears at all (silent absence, never a placeholder).
• turn — one user message plus all assistant content (thinking, text, tool calls, tool results) that follows it before the next user message.
• fold / folding — replacing a block's content in-place with something shorter, like a summary; the block stays on the wire to the LLM in compressed form. Always reversible.
• authored digest — a folded block's digest, or a folded group's summary, written by the HUMAN instead of the engine (fold op's digest, group op's summary; UI: app/src/lib/ui/map/DigestEditor.svelte). Stored verbatim in Block.subst / Group.digest and — the load-bearing part — untagged. See the tag is the handle. Clearing the editor means different things at the two granularities, deliberately: a BLOCK commits the EMPTY_DIGEST sentinel {empty} (~6 tok — per-block folding is content substitution, and applyPlan drops an empty digestText, which would ship the block WHOLE), while a GROUP commits a real DROP (Group.digest === null; a group may legally change the wire's message count, subject to the tool-pair fixpoint and role-validity floor). Saving with no text at all restores the engine's own digest/recap, tag included.
• the tag is the handle — the {#<code> FOLDED} prefix is the ONLY way a fold code ever reaches the model, so whether the wire text carries that block's OWN tag decides whether the agent can reach it at all (core/digest.ts → hasOwnFoldTag; enforced in core/agentView.ts's agentReachable/groupAgentReachable). Own-tag, not any-tag: a foreign tag — pasted by a human, hand-authored by a conductor — must not make a block reachable by its own code, which is the accidental-restore path the rule exists to close. Engine digests, default group recaps, and a conductor's recoverable replace carry their own tag and are therefore unfold/recall-able; a HUMAN-authored digest and a conductor's recoverable: false replace are untagged and unreachable — a human's own words are not something the agent may undo. To keep that true, the HUMAN branches of BOTH Truth.opFold and Truth.opGroup strip leading tags (stripFoldTags, to a fixed point) exactly as opReplace does — the engine is the sole author of the tag. This is enforced in Truth, not in the editor, deliberately: the editor seeds its box with the current digest/recap, so edited engine text still starts with a tag, and sanitizeOps passes a raw fold.digest/group.summary through untouched — a widget-only strip would leave the invariant resting on a Svelte component. The strategy branches deliberately do not strip — ViewConductor emits fold-with-digest and a conductor authoring its own recall handle is a supported shape. The one carve-out is a DROP group: it emits no text, but stays reachable because the role-validity floor may degrade it to a roleFloorRecap stub carrying foldTag(g.id) on purpose.
• Truth — core/truth.ts's Truth class: the canonical, framework-free context state — block log, per-block overlay (override/autoFolded/subst/by), multiblock groups, the protected working tail, involvement locks, budget/context-window dials, and a monotonic rev that bumps on every change and rides every emitted TruthEvent. One instance lives authoritatively inside the pi extension per live session (ADR 0021); the app's Svelte store and any conductor are thin mirrors over it, never a second source of truth.
• replica — a Truth hydrated from a host's snapshot (core/replica.ts → hydrateSnapshot) and kept in lockstep by replaying WireEvents; it asserts its rev matches the host's after every replay and requests a fresh snapshot on any mismatch rather than patching around a gap. The GUI is always a replica in live mode; a spawned conductor is a replica too (core/conductor/remote.ts).
• held — a block carrying a human override (manual pin, fold, or unfold): a non-null Block.override. Held state always wins over a strategy's proposed ops — the one exception is an involvement lock: while a conductor holds human-steering, the human steering mutators are refused outright (no override is ever created) until the lock releases or the conductor is detached (see freeze, below, and the Conductors section).
• conductor — a pluggable, evented context-management strategy (core/conductor/contract.ts's frozen v2 Conductor interface) that attaches to a host, subscribes to HostEvents (blocks-appended/turn-committed/state-changed/wire-departing/resync), and proposes diff-op transactions between turns rather than being polled every pass. Never a privileged write path — every proposed op is clamped by the exact same Truth.apply a human hand action or the agent's own tools go through. Five ship today: compaction-naive, handoff, doorman (in-process, bundled into the extension) and thermocline + triptych (out-of-process, each spawned as its own Node process). See the Conductors section.
• transaction / propose — a conductor's unit of write: host.propose({ baseRev, ops }): Promise<TxnResult> (core/conductor/contract.ts). Async by contract — an in-process host applies the ops synchronously and resolves on a microtask; an out-of-process host resolves after a propose/proposeResult wire round trip. A conductor cannot tell the two hosts apart, which is the whole portability point.
• birth-fold — the exemption (ADR 0018, restored as ADR 0023) letting a strategy fold a block that sits inside the protected tail but has never yet reached the model whole (Truth.canFold's if (this.isProtected(b)) return !this.sent(b) branch). Such a fold is tracked in Truth's sticky birthFolded set so the tail growing over it later doesn't heal it back open. doorman is the shipped demonstration — it skeletonizes or folds a giant fresh tool_result before it ever rides the wire.
• hold / holdWireUpToMs — a conductor may declare holdWireUpToMs (ms, default 0) to ask the host to pause the departing wire briefly on the wire-departing event, giving it one last chance to propose a last-moment fold before the model call actually leaves. The hold ends when the conductor's wire-departing handler settles — in-process, the returned promise resolving/rejecting; a remote conductor sends a dedicated holdRelease { holdId } the instant its handler settles (protocol v14; the host correlates by the holdId it minted per hold and ignores a stale/unknown one). A propose never releases the hold, so a concurrent background-tick propose (e.g. thermocline's prepare epoch) can't race it out from under the handler. Bounded: a timeout releases the wire unchanged and counts against holdTimeouts. Surfaced live as MapHeader's HOLD chip and in telemetry's lastHoldMs/holdTimeouts.
• freeze — the conductor-detach kill switch ({ kind: "freeze" }, core/ops.ts): converts every currently strategy-owned fold/group into a human-owned one (the substituted content preserved byte-identical) BEFORE the host releases the conductor's locks, so work an exclusive conductor did survives its own detach instead of reverting or vanishing.
• the wire — the messages array sent to the LLM provider. "Wire-valid" = the outgoing array is well-formed. Distinct from the WebSocket between the app and the pi extension (that's the live link / accordion protocol).
• browser-served — mode where the pi extension HTTP-serves the SvelteKit UI on the same ephemeral port as the WS. Multi-session-aware (the served extension lists every live session over /__accordion/sessions); no Tauri desktop app required.
• CC — Claude Code (as in "CC transcript", "CC browsing"). Read-only mode; sessions loaded from ~/.claude/projects/.
• controller / lease — the global, machine-wide right to send mutating steering commands (ADR 0024, issue #66). Exactly one surface (a desktop app instance, a browser tab) holds it at a time, tracked as a ControllerLease blackboard at ~/.accordion/controller.json (app/src/lib/live/registry.ts); every other connected surface is a live, strictly zero-write READ-ONLY mirror. Claiming (claimController) is silent when uncontested and never refused when contested — the human is always the authority, last write wins. Enforced at the extension's WS command ingress (a synthesized "read-only" ClampReason, never produced by Truth.apply itself), so conductor propose and the agent's own unfold/recall are completely unaffected.
• door / surface — the door is the fixed, well-known loopback port (DOOR_PORT = 24317, core/protocol.ts) exactly one extension binds at a time, as an additional listener alongside its own per-session ephemeral server, so /accordion can print one stable URL that survives any single session's death (first-bind-wins, automatic takeover on the holder's exit). A surface is a connecting client's per-tab identity (a sessionStorage UUID — per tab, not per origin, with a duplicate-tab BroadcastChannel dedupe guard; see app/src/lib/live/surfaceId.ts — plus a human label like "Desktop app"/"Browser tab") — what the controller lease is actually granted to.
• READ-ONLY — the one term for "this view cannot write," covering two distinct situations: a Claude Code transcript (plain badge, no wire, no escape) and a live session currently steered from another surface (READ-ONLY · <WHO> STEERS chip + a TAKE CONTROL button). Both share the exact same guarantee (see the RULE below); "view-only" is deliberately never used as a second term for either.