calva-backseat-driver: Instructions file for Codex

Calva Backseat Driver - AI Agent Guide

ClojureScript VS Code extension providing REPL access to AI agents via Language Model API and MCP. Enables Interactive Programming where AI evaluates code in the user's running environment rather than guessing.

When authoring code and test, ask yourself: Will this and the tests work on Windows too?

Essential Architecture

Action/Effect System ("Ex")

Functional core with unidirectional flow:

dispatch! → handle-actions → [enrich → route] → {:ex/db, :ex/fxs, :ex/dxs} → update state → execute effects

Actions (*/axs.cljs): Pure functions returning state changes and effects Effects (*/fxs.cljs): Side effect handlers with dispatch access State: Single app-db atom in src/calva_backseat_driver/app/db.cljs

Runtime State Structure

The app-db atom contains:

{:vscode/extension-context    ; VS Code extension API access
 :app/log-file-uri            ; Logging location
 :app/min-log-level           ; :debug/:info/:warn/:error
 :mcp/wrapper-config-path     ; ~/.config/calva/backseat-driver
 :calva/output-line-counter   ; Monotonic line counter for output entities
 :calva/history-storage-uri   ; Workspace-scoped Transit file for persistent history
 :extension/disposables       ; VS Code subscriptions
 :extension/when-contexts}    ; Context keys for enablement

Datascript Connections

• !output-conn — Session-scoped, schemaless. All REPL output categories. Cap: 1000 entities.
• !history-conn — Persistent, :output/line unique identity schema. evaluatedCode only. Cap: 10000 entities. Persisted to eval-history.transit.json under context.storageUri.

Calva API Integration

Available at calva-backseat-driver.integrations.calva.api/calva-api:

{:repl     {:evaluateCode, :currentSessionKey, :onOutputLogged
            :listSessionsAndRuntimes, :onSessionsChanged}
 :ranges   {:currentTopLevelForm, :currentEnclosingForm, ...}
 :editor   {:replace}
 :document {:getNamespace, :getNamespaceAndNsForm}
 :info     {:getSymbolInfo, :getClojureDocsDotOrg}}