bricelancasterwcp-sudo/sensorium

Record what a program actually did; ask it questions afterward.
Sensorium records one run of a program — every call, return and exception,
with captured values — into a SQLite trace, and answers debugging questions
from that trace in dense plain text shaped for a language model to read. It
exists because reading logs is reading a diary; this is watching the
execution.
Three recorders write that trace, and one command line reads it:
- **Python** — sensorium run -- wraps one run with PEP 669
(sys.monitoring) instrumentation. Python 3.12+, no runtime dependencies.
- **Rust** — cargo sensorium test|run instruments a workspace's own crates
at build time and writes one trace per process. Stable rustc, Linux.
- **TypeScript** — sensorium ts run [--focus ]… -- vitest run … (or
-- node --test …) transforms the consumer's own sources at load time and
writes one trace per test-file process. Node 24, vitest 4.1.
All three write trace format 4, so every query below
answers on any of the three kinds of trace — and where a recorder declares a
capability it does not have, the query refuses by name instead of answering
from data that was never recorded. Python is documented first; Rust
and TypeScript have their own sections here, and
rust/README.md and
typescript/README.md are their full references.
Two commitments run through all of it:
- **The instrument never answers from data it does not have.** Truncated
captures are marked and counted, sites a predicate could not be evaluated at
are counted rather than skipped, a recording that died is labelled, and a
rerun that turned out to be a different execution says so permanently.
- **Nothing here guesses.** Every answer is a deterministic function of the
recorded trace, and where the trace cannot settle a question the output says
so instead of inferring. Sensorium reports; the agent reading it reasons.
(refocus is the one command that *executes* anything — it re-runs your
program, which is why its whole job is telling you whether what came back
was the same execution.)
Install
uv venv .venv && uv pip install -p .venv/bin/python -e ".[dev]"
Requires Python 3.12+ — the recorder is sys.monitoring and nothing else, so
on 3.11 it refuses to start rather than falling back to something weaker. No
runtime dependencies; the trace is a SQLite file written with the standard
library. One capability is version-gated: witnessing a multiprocessing
spawn needs the _posixsubprocess.fork_exec audit event, which arrived in
**3.14** — below it such a spawn is unwitnessed, and refocus says so by
withholding the "no child process witnessed" line rather than claiming it (see
"What the answers claim"). Everything else works
identically on 3.12 through 3.14, all three of which CI exercises. The Rust
recorder is a separate build and install: Install and
record, under Rust.
Use
sensorium run -- pytest tests/test_fog.py # record
sensorium runs # what have I recorded
sensorium info last # what am I looking at
sensorium tree last --depth 3 # what actually ran
sensorium frame last --fn compute # one activation, in full
sensorium grep last compute --kind RETURN # every event that mentions it
sensorium exceptions last # what blew up, what got caught
sensorium flow last --value 1800 # where did that number come from
sensorium flow last --object build_key:record # what happened to that object
sensorium diff RUN_A RUN_B # where two runs part
sensorium refocus last --focus fog:compute # re-run deeper, verified
sensorium redact --all --dry-run # what an older store still holds
sensorium mcp --allow-run # serve all of the above to a model (MCP, stdio)
Per-line state is opt-in at record time, so a predicate over locals needs a
run that captured them:
sensorium run --focus fog:compute -- pytest tests/test_fog.py
sensorium watch last --at fog:compute --expr 'visible > 100'
Asked against a run recorded without that --focus, watch does not report
zero hits — it reports NOTHING WAS CHECKED and prints the exact re-recording
command. Every example above was run as typed, against a small fog.py whose
compute sums cells into a visible local and whose build_key(record)
takes a dict, and a two-test tests/test_fog.py.
On an asyncio program tree groups by task, and from trace format 3 every
traced code object opens a frame — function, generator, coroutine, or async
generator alike — so a coroutine's callees nest under it exactly like a
plain function's do, tagged [generator], [coroutine], or
[async_generator] when the kind isn't function. A frame that suspended