Skip to main content

​
Overview

Codaph uses a dual-store architecture that balances local performance with cloud collaboration:

Local JSONL Mirror

Fast, deterministic timeline rendering from append-only local storage

Mubit Cloud Memory

Shared collaborative backend for cross-contributor context and semantic query

​
Design Goals

1

Capture without disruption

Record coding-agent activity without changing your normal agent workflows
2

Fast local rendering

Keep timeline and diff rendering deterministic and fast in terminals
3

Share across contributors

Enable cross-contributor memory and context through Mubit cloud backend
4

Preserve attribution

Maintain actor attribution from ingestion through query

​
Components

​
Adapters

Adapters capture events from different agent sources:
Location: src/lib/adapter-codex-sdk.tsCaptures live events from Codex SDK streamed runs. Subscribes to the Codex event stream and transforms events into Codaph’s canonical format.
const adapter = new CodexSdkAdapter({
  codexPath: '/path/to/codex',
  pipeline: ingestPipeline
});

await adapter.runAndCapture({
  prompt: 'Add auth to API',
  cwd: '/project/path'
});
Location: src/lib/adapter-codex-exec.tsParses JSON output from codex exec --json. Spawns the codex process and parses JSONL output line-by-line.
codaph exec "Refactor the auth module"
Locations:
  • src/codex-history-sync.ts - Codex ~/.codex/sessions
  • src/claude-history-sync.ts - Claude Code transcripts
  • src/gemini-history-sync.ts - Gemini CLI transcripts
Import historical sessions from local agent history directories.
codaph push --providers codex,claude-code,gemini

​
Ingestion Pipeline

Location: src/lib/ingest-pipeline.ts The IngestPipeline normalizes events, redacts sensitive data, and orchestrates dual writes: 
interface IngestContext {
  source: AgentSource;
  repoId: string;
  actorId?: string | null;
  sessionId: string;
  threadId: string | null;
  sequence: number;
  eventId?: string;
  ts?: string;
}
Pipeline flow:
1

Redaction

Removes sensitive data via redactUnknown() from src/lib/security.ts
2

Canonicalization

Creates canonical events with createCapturedEvent() - adds eventId, actorId, timestamps
3

Deduplication

Checks eventId index before mirror append
4

Dual write

Writes to local mirror (always) and Mubit (fail-open circuit after consecutive errors)
5

Batching

Supports batching and concurrency for Mubit writes during bulk sync

​
Storage Layer

​
Local JSONL Mirror

Location: src/lib/mirror-jsonl.ts The JsonlMirror maintains an append-only event store under .codaph/: 
.codaph/
├── manifest.json           # Segment registry
├── sparse-index.jsonl      # Session→segment lookup
├── eventid-index.jsonl     # Deduplication index
└── segments/
    ├── <session-id>.jsonl  # Event segments
    └── ...
Index structures:
  • Manifest: Tracks all segments with checksums
  • Sparse index: Maps sessions to segments for fast lookup
  • Event ID index: Enables deduplication checks

​
Mubit Cloud Memory

Location: src/lib/memory-mubit.ts The MubitMemoryEngine writes canonical events to Mubit control APIs:
  • Supports project-scoped and session-scoped run IDs
  • Appends codaph_event activity for remote replay
  • Provides semantic query over evidence
Run ID patterns: 
// Project scope (collaborative default)
codaph:<projectId>

// Session scope (isolated sessions)
codaph:<projectId>:<sessionId>

​
Query and Visualization

​
Query Service

Location: src/lib/query-service.ts Reads the local mirror and returns:
  • Sessions list with metadata
  • Timeline events with filters
  • Diff summaries
  • Contributor lists
const query = new QueryService(mirror);
const sessions = await query.listSessions({ repoId });
const timeline = await query.getTimeline({ 
  repoId, 
  sessionId,
  actorId: 'alice' 
});

​
CLI and TUI

Location: src/index.ts Exposes:
  • CLI commands for setup, sync, status, inspection
  • Interactive TUI for browsing sessions and timelines
  • Local sync and remote Mubit sync workflows

​
Data Flow

1

Capture

Codaph captures agent events from live runs or provider history importers
2

Normalize

Ingest pipeline redacts and canonicalizes event payloads
3

Local append

Event is appended to local mirror with eventId idempotency checks
4

Cloud write

New events are written to Mubit with actor/project metadata
5

Remote sync

Remote Mubit timeline can be synced back into the mirror
6

Render

TUI and CLI render timeline/diff from mirror and call Mubit for semantic queries

​
Event Types

From src/lib/core-types.ts: 
type AgentSource =
  | "codex_sdk"              // Live Codex SDK capture
  | "codex_exec"             // codex exec --json wrapper
  | "codex_history"          // ~/.codex/sessions import
  | "claude_code_history"    // Claude Code transcript import
  | "gemini_cli_history";    // Gemini CLI transcript import
Each event source maintains its own sequence numbering and event ID generation to ensure deterministic deduplication.

​
Circuit Breaker

The ingest pipeline includes a fail-open circuit breaker for Mubit writes:
  • Tracks consecutive Mubit write errors
  • Opens circuit after 3 consecutive failures (configurable)
  • Local mirror writes continue even when circuit is open
  • Allows codaph repair cloud to backfill missed events
const pipeline = new IngestPipeline(mirror, {
  memoryEngine: mubitEngine,
  memoryMaxConsecutiveErrors: 3,
  memoryWriteTimeoutMs: 15000,
  onMemoryError: (error) => console.warn('Mubit write failed:', error)
});

​
Performance Tuning

For bulk sync operations (e.g., codaph push): 
const pipeline = new IngestPipeline(mirror, {
  memoryEngine: mubitEngine,
  memoryWriteConcurrency: 2,      // Parallel Mubit writes
  memoryBatchSize: 24,            // Batch events for Mubit
  retryMemoryWriteOnLocalDedup: true  // Retry deduped events
});
High concurrency and batch sizes can increase Mubit API load. Use defaults for live capture.

​
See Also

Data Model

Event envelope structure and types

Sync Automation

Git hooks and sync triggers

Identity Resolution

Project and actor ID resolution

API Reference

TypeScript APIs and types

Build docs developers (and LLMs) love

Get started for freeTalk to us