Developer Tools & Replay

Relevant source files

The following files were used as context for generating this wiki page:

• src/replay.rs
• src/transcript.rs
• src/main.rs
• src/curate.rs
• assets/viewer/app.js
• src/setup.rs

Developer Tools & Replay provides a suite of utilities for performance measurement, system diagnostics, and historical data analysis within the oboete environment. It allows developers to simulate agent interactions, evaluate system latency, and inspect the internal state of the memory store.

The system uses JSONL fixtures and agent transcripts to reproduce specific sequences of events. This capability ensures that changes to redaction rules, curation logic, or store schemas produce predictable results.

Replay System

The replay module simulates hook events to measure system performance and verify store integrity. It processes JSONL fixtures containing sequences of agent events and payloads.

Replay Execution Flow

The run function in src/replay.rs executes the replay in three main stages:

1. In-process hook path: Measures the pure store cost per event.
2. Real process spawns: Executes real oboete hook processes to measure startup, redaction, and locking overhead.
3. Backup export: Times the sealing of record segments.

Performance Metrics

Replay reports include specific latency and resource usage statistics:

• hook_in_process_us: Percentiles (p50, p95) and max latency for internal recording.
• hook_spawn_ms: Latency for full process execution across different tool-output sizes (e.g., 1KB, 64KB, 256KB).
• vmhwm_kb: Peak resident set size of the process.
  Sources: src/replay.rs:94-106, src/replay.rs:109-116

Transcript Conversion

Transcripts transform raw agent logs into replay fixtures. The system supports parsers for Claude and Codex agents.

Conversion Logic

The converter reads JSONL transcript files and emits events that the oboete replay command can ingest. It handles complex structures such as subagent calls and interrupted requests.

Agent	Source File Characteristics	Handling
Claude	Sidechains and subagents	Reads from <session>/subagents/ directory.
Codex	Rollouts and task messages	Identifies user.text and assistant roles.
Both	Timestamps	Replay preserves original fixture times rather than using "now".
Sources: src/transcript.rs:518-540, src/replay.rs:245-248

Diagnostic & Administrative Tools

Oboete provides several CLI commands for system maintenance and verification.

Doctor & Setup

The Setup command wires the oboete binary into agent hooks. The Doctor command reports on the current wiring state, stored data, and the readiness of configured providers.
Sources: src/main.rs:118-121, src/main.rs:271

Recuration

The Recurate command allows developers to re-process previously curated spans. This is used when redaction rules change or when providers previously failed.

Option	Description
--skipped	Curates windows that every provider skipped.
--span	Curates a specific range of records formatted as <device>:<from>-<to>.
--yes	Required to actually send data to providers; otherwise, it only lists and estimates.
Sources: src/curate.rs:458-522, src/main.rs:69-82

Web Viewer

The project includes a lightweight web-based viewer for browsing the memory store. It provides a read-only interface to the SQLite databases.

Architecture

The viewer consists of a single-page application (assets/viewer/app.js) that communicates with a local API server. It uses a token-based authentication system where the access key is passed in the URL fragment.
Sources: assets/viewer/app.js:4-21

Viewer Components

• Feed: Displays summaries, observations, and prompts newest first.
• Timeline: Lists coding sessions grouped by repository.
• Context: Shows the exact text injected into new agent sessions.
• Stats: Summarizes session totals, knowledge counts, and provider performance.
  Sources: assets/viewer/app.js:203-228, assets/viewer/app.js:246-277

Summary of Developer Tools

Command	Module	Primary Purpose
oboete replay	src/replay.rs	Benchmarking and performance validation.
oboete transcript	src/transcript.rs	Converting raw logs into testable fixtures.
oboete doctor	src/setup.rs	System health check and wiring report.
oboete recurate	src/curate.rs	Reprocessing records after rule/provider changes.
oboete view	assets/viewer/	Graphical inspection of remembered data.

Developer tools facilitate the "Measure, don't assume" philosophy of the project. Developers use oboete replay <fixture> to print hook latency and VmHWM, ensuring that memory operations remain lightweight for coding agents.
Sources: CLAUDE.md:27-28, src/main.rs:180-192