PreviouslyOn
PreviouslyOn is a local-first, verifiable handoff layer for Codex. It connects captured session events to Git state and test evidence, then returns a deterministic Context Pack only after the user approves a resume suggestion.
Version 0.1.0-alpha.1 is an early public alpha. Historical evidence is always untrusted data,
not an instruction and not a replacement for checking the current source.
What the alpha includes
- one Rust
previouslybinary for collection, storage, Git correlation, MCP, and the review UI; - an embedded React evidence inspector;
- a task timeline with source-thread identity, relative activity age, turn and compaction counts, and observed context usage;
- deterministic context packs with provenance, freshness, and capture-coverage warnings;
- one-time new-thread advice after a session crosses a continuation threshold;
- no API key, telemetry, or outbound network access in the default mode;
- repository-scoped JSON export and complete local purge.
PreviouslyOn deliberately does not include a code graph, chat replay, cloud sync, multi-agent integration, or automatic Context Pack injection.
Install
Apple Silicon release archive
Download previously-on-v0.1.0-alpha.1-macos-arm64.tar.gz and SHA256SUMS from the
v0.1.0-alpha.1 release,
then verify and install the unsigned alpha binary:
|
The Apple Silicon artifact is not signed or notarized. Review the checksum and release attestation before allowing it through macOS security controls.
crates.io or source
Intel Mac users should install from crates.io or source; no Intel binary archive is published.
Building the repository requires Rust 1.90+ and Node.js 22+:
Quick start
The review UI is deterministic and local. v0.1 does not invoke an AI model from the UI; facts are activated only through explicit user review.
Restart Codex after setup so it loads the managed Hooks and previously_on MCP server. Other
public commands are:
previously export --format json
previously import codex --repo <path>
previously purge --repo <path>
previously uninstall codex
The official executable is previously. If the shorter spelling does not conflict with another
tool already installed on your machine, add an optional shell alias yourself:
PreviouslyOn does not install a prev binary or symlink because an existing development tool
already uses that command name.
Codex workflow
- Register the repository, then start supported alpha sessions with
previously run codex --repo <path> -- <codex arguments>. - The wrapper runs Codex in that repository with inherited terminal I/O, preserves Codex's exit status, replays any redacted crash-safe queue, and attempts an App Server repair import.
- If Codex was started separately, run
previously import codex --repo <path>explicitly. The import reports skipped/degraded threads and never treats unknown items as trusted evidence. - A completed session creates a deterministic checkpoint from observed events, Git state, and verification results.
- On a later first prompt, Codex may show a small resume candidate. Nothing is loaded until the
user approves it and
resume_taskis called through MCP. - The localhost inspector shows the source thread, relative activity age, turns, compactions, observed context usage, and the Git changes since the checkpoint. Facts can be confirmed, pinned, invalidated, or superseded.
- When a session reaches six compactions or at least 80% observed context usage, the next user prompt receives one suggestion to continue in a new thread. A session inactive for at least 72 hours receives the same one-time suggestion only when relevant code has changed. This is advice, not an automatic thread switch or Context Pack injection.
Context usage is recorded only when the App Server actually emits a token-usage notification. PreviouslyOn does not infer a percentage from prompt size or other incomplete observations.
Transparent capture from an independently launched Codex process is experimental in this alpha. The mapped 30-row regression driver and live App Server schema probe do not prove 30 real Codex workflows or stable Hook/App Server ID linkage, so releases must not advertise that path as supported yet.
The MCP server is read-only and exposes suggest_resume, resume_task, search_tasks,
explain_fact, and get_task_timeline.
Local data and privacy
Data lives under ~/.previously-on by default. Set PREVIOUSLY_ON_DATA_DIR to use a different
location. Full transcripts are disabled by default; evidence excerpts are redacted and limited
to 500 characters. Run previously purge --repo <path> to delete a repository's canonical
events, projections, queues, cached packs, WAL, and related recovery data.
The unpublished ~/.lineage development directory is never migrated or deleted. previously doctor reports it as ignored.
See the privacy model, architecture, and compatibility matrix.
Development
./scripts/build-release.sh runs the local quality, adversarial, packaging, offline-smoke, and
reproducibility gates. It writes Apple Silicon artifacts, an SBOM, license inventory, NOTICE, and
checksums to outputs/. It does not run or certify the separate live Codex compatibility
matrix. A tag release remains blocked until a SHA-pinned, separately supplied live evidence
artifact passes scripts/validate-live-compatibility.mjs in the protected
release-compatibility environment.
Security and license
Report vulnerabilities through GitHub's private vulnerability reporting flow; see SECURITY.md. PreviouslyOn is licensed under Apache-2.0. Third-party notices are in NOTICE and THIRD_PARTY_LICENSES.md.