Session continuity for Claude Code
The work should survive the session.
Velra carries the engineering state that gets lost between coding sessions: the objective, constraints, test status, edits, reversions, and what to do next.
- 01Record
- 02Reduce
- 03Restore
A bounded record of what the session did. Not a replay of the conversation.
Velra capsule
706estimated tokens
740 default target1,000 ceiling
- objective
- 2 dead ends
- 8 files
- 01
Local-first
No network code in the hook path. No model calls.
- 02
Deterministic
Same ledger, same clock, same bytes.
- 03
Bounded
740 estimated tokens by default. Never more than 1,000.
- 04
Explicit
Nothing crosses sessions until you run velra restore.
0x01Interactive replay
See the state move. Not the whole transcript.
Step through real commands and their output, then open the capsule to see what was kept. This is a recorded replay. Nothing on this page runs on your machine.
Captured output, sanitized
Seven captured steps, from installing Velra to a capsule staged and waiting, then a guide to checking the handoff yourself. Prompts, file names, ids and paths are replaced with placeholders, and the home directory is shown as ~.
Install Velra
Velra installs as one global npm package.
Step 1 of 8. Install Velra. Velra installs as one global npm package.
0x02Why state
Your repository knows the code. It does not know where the work stands.
A new session can read every file and still miss what the last one learned. That knowledge is small, and it is cheap to carry if it is carried precisely.
A fresh session, reading the files
- reconcile.py as it is now, with no sign of what was tried
- Three failing tests, and nothing to say which one matters
- A reverted edit that left no trace in git
- No record of the rule that was stated once, in chat
The same session, with the capsule
- The objective: the reconcile failure, not the other two
FIRST_MESSAGE - A window closes on the booking date, never the value date
STATED_CONSTRAINTS - The exact failing test, by id
TEST_STATUS - The edit that was tried and undone
REVERTED_EDITS - The next step, in the user's own words
LATEST_MESSAGE
Values from the documented example in the Velra README. Open it in the replay.
The capsule is context, not a command. The files stay the source of truth, and Velra does not promise that an agent will act on it.
0x03How it works
Five steps. No model in any of them.
Velra records what a session does, not what it says. The record is reduced by ordinary code, rendered within a budget, and handed over only when you ask.
Capture
Claude Code hooks pass Velra each event: prompts, edits, commands, test runs and reverts. Each one is normalised, redacted and appended to a local SQLite ledger.
hook event → ledgerReduce
A reducer folds the events, in order, into task state: the objective, constraints, tests, edits and reverts.
ledger → task stateRender
A pure renderer writes the capsule within a fixed budget. If it runs over, a fixed ladder drops regenerable detail first and exact identifiers last.
task state → capsuleStage
velra restore writes the capsule for the source session you picked to ~/.velra/staged, outside every repository.
velra restore → staged fileDeliver
The next new Claude Code session in that workspace claims the capsule once and receives it as additional context.
SessionStart(startup) → context
Observed or inferred
Every capsule section says how it is known. Files on disk remain the source of truth, and the capsule says so in its first lines.
- Observed
- Read directly from a prompt or a tool event: what you typed, which test failed, which edit was reverted.
- Inferred
- Derived from observed rows. Two sections are inferred: where failing output points, and the most recent live edit.
What Velra leaves out
The conversation
A capsule is a bounded rendering of recorded state. It is not a transcript and it is not a summary written by a model.
Assistant reasoning
The assistant's replies are not hooked, so they are never recorded.
Merged sessions
The source session keeps its identity and the new one keeps its own. Only the capsule text crosses.
Automatic handoffs
Nothing moves between sessions until you run velra restore and name the source.
To reopen a whole conversation, use Claude Code's own /resume. Velra is for a fresh, small context that still knows where the work stands.
0x04Trust and privacy
Precise about what it promises. And about what it does not.
These are the properties Velra documents, each with the limit the documentation attaches to it.
Local-first storage
State lives under ~/.velra on your machine. No accounts and no telemetry.
LimitThe files are not encrypted at rest. Anyone who can read your account can read them.
Secret redaction
Known secret formats are replaced before anything is written, the spool included.
LimitRedaction is pattern matching. An unusual secret format can pass through.
No model calls
Capture, reduction and rendering are deterministic code. Nothing is summarised by a model.
LimitSo the capsule holds only what Velra observed. It cannot fill a gap by guessing.
Nothing leaves the machine
No network-capable code is linked into the hook path, and CI checks that it stays that way.
LimitThe installers do download a release archive and verify its checksum.
A bounded capsule
Never more than 1,000 estimated tokens or 9,500 characters, whatever the budget is set to.
LimitBounded means lossy. Under pressure your own wording is shortened before an identifier is.
Explicit restore
Only velra restore crosses sessions, for a session you name, inside one workspace.
LimitA restore is a snapshot of the moment you ran it. Later work needs a restage.
Delivered at most once
To the next new session in the same workspace, within seven days.
LimitAt most once is exact. A session start killed mid-delivery means zero deliveries.
Claude Code only
Velra integrates with Claude Code through its hooks, and with nothing else.
LimitHook payloads are not a stable public interface. A Claude Code change can require a Velra update.
Prompts travel
A capsule quotes your prompts. Anything you typed in the source session can reach the next session in that workspace. That is the feature, and it is also the thing to be aware of.
Evidence, with its limits
In Velra's v0.1.2 live qualification, four matched pairs of sessions were compared. The sessions that received a capsule met the registered correctness criterion in 4 of 4 trials, and the fresh baselines in 0 of 4. Total input was lower in three pairs and higher in one.
LimitThe documentation calls this qualification evidence, not an effect size. It ran on an earlier build, and the baseline was a fresh session rather than a resumed one.
0x05For the work after the reset
Clear the context. Keep the state. Continue working.
Velra is open source under the MIT licence. Install it, run velra enable once, and keep working as usual.
Install
$ npm install -g velra
$ velra enable # once per machine
$ velra doctorInstallation guide (opens in a new tab)Restore guide (opens in a new tab)Architecture (opens in a new tab)Security (opens in a new tab)