Codex Chat Vault

Move archived Codex chats into encrypted local or cloud storage, then restore individual chats when you need them. The CLI is alv.

Codex archived_sessions  ──offload──>  encrypted vault (rclone crypt)
                        <─restore──  local folder, drive, or cloud storage

Offload removes the local archive only after uploading and reading back the exact bytes for SHA-256 verification. Restore keeps the encrypted copy. Active Codex sessions are never moved.

Previously agent-log-vault. The repo name changed; the alv launcher, agent-log-vault executable, and existing configuration paths stay the same.

Requirements

There is no build or installation step. Run ./alv from the cloned repository and keep the launcher, main executable, and lib/agent-log-vault/ together.

The CLI requires rclone and either shasum or sha256sum. Creating a vault also requires openssl. jq enables enriched listings, stats, planning, inspection, and recovery export. When available, sqlite3 adds Codex's stored title, archive time, and Git branch to inspection output.

Archive and restore a chat

Start with an encrypted vault in a local folder. There is no build step:

git clone https://github.com/filip-pilar/codex-chat-vault.git
cd codex-chat-vault
mkdir -p /absolute/path/to/cold-vault
./alv vault add local cold --path /absolute/path/to/cold-vault
./alv list local

Choose an archived rollout-*.jsonl from that list. Quit Codex Desktop and Codex CLI before offloading or restoring, then replace the example filename below with the one you chose:

# Move the archived chat into the encrypted vault after read-back verification.
./alv offload rollout-EXAMPLE.jsonl --vault cold

# Check the encrypted copy, then restore the chat to archived_sessions.
./alv verify rollout-EXAMPLE.jsonl --vault cold
./alv restore rollout-EXAMPLE.jsonl --vault cold

The chat is local again and its encrypted copy remains in the vault. To preview a larger cleanup without moving anything, use ./alv plan offload --created-before 2026-01-01 --vault cold.

See safety and recovery before moving valuable archives; keep a secure recovery export of the vault's encryption configuration.

Everyday use

./alv list local
./alv list cold
./alv stats local --top 10 --by-project
./alv plan offload --created-before 2026-01-01 --vault cold
./alv offload rollout-EXAMPLE.jsonl
./alv restore rollout-EXAMPLE.jsonl
./alv verify rollout-EXAMPLE.jsonl

The state transitions are:

local only --offload--> cold only
cold only  --restore--> both
both       --offload--> cold only

Restore retains the cold copy. Offloading a restored chat verifies the existing cold bytes and removes the local copy without uploading it again.

list local accepts --long, --created-before YYYY-MM-DD, --created-after YYYY-MM-DD, --project <cwd-or-name>, --larger-than <bytes-or-K/M/G/T>, --sort name|created|size, --limit <count>, and --json. Size sorting is largest first; creation sorting is newest first.

stats local reports task count, logical and on-disk bytes, available disk space, oldest/newest and largest tasks, and age buckets. Add --top <count>, --by-project, or --json for detail.

plan offload accepts the same filters, sorting, limit, and JSON options as the enriched local listing, plus --vault. It is strictly read-only: it shows the selected bytes, expected reclaim, required uploads, existing complete cold pairs, and incomplete-object conflicts. A listed cold pair is reported as unverified; actual offload still reads it back and verifies its hash before removing anything local.

inspect <thread> shows identifying metadata. CODEX_HOME and --codex-home <directory> are supported for disposable environments and non-default Codex homes.

Cloud vaults and configuration

Configure one cloud vault using the matching command below. R2 expects bucket-scoped Object Read & Write credentials. B2 expects a bucket-scoped Read and Write application key for the existing bucket. Dropbox and OneDrive hand browser authorization to rclone.

./alv vault add r2 cold
./alv vault add b2 cold
./alv vault add dropbox cold
./alv vault add onedrive cold

Run R2 and B2 setup without secret flags when possible and answer the private prompts yourself. ./alv --help documents every non-interactive option, but command-line secrets can be exposed through shell history or agent logs.

The OneDrive helper accepts Personal accounts only. Configure OneDrive Business, SharePoint, or Google Drive directly in rclone, then use the advanced command below.

Advanced users can wrap any existing rclone target. If the target is already a secure crypt remote, it is used directly.

./alv vault add rclone cold --remote existing-remote:optional/path

Setup creates the encryption configuration in rclone, performs a disposable upload/read-back check, and saves the named vault only if validation succeeds. The first vault is the default. Use ./alv vault list, ./alv vault use <name>, or --vault <name> when more than one is configured.

ALV profiles default to ${XDG_CONFIG_HOME:-$HOME/.config}/agent-log-vault and contain no credentials. ALV_CONFIG_HOME overrides that location. Codex data defaults to ${CODEX_HOME:-$HOME/.codex}; rclone owns provider credentials and encryption secrets.

Safety and recovery

• Only rollout-*.jsonl files directly inside archived_sessions can be offloaded.
• Offload uploads, reads back, SHA-256 verifies, rechecks the source, and only then removes the local file.
• Restore downloads to private temporary storage, verifies, and atomically places the exact bytes in archived_sessions when the destination filesystem supports same-directory hard links.
• Atomic no-clobber publication for restore and recovery exports requires same-directory hard-link support. Without it, the operation fails without creating or replacing the destination or removing its source.
• Different existing files are never overwritten, and failed operations retain their source.
• Restore never removes the cold copy.

Quit Codex Desktop and any Codex CLI process before offloading or restoring so the archive is stable during the operation.

Offload uploads and reads back the full JSONL. Verify and restore also download the full JSONL, so large threads require corresponding network transfer and temporary free space.

Rclone owns provider credentials, OAuth tokens, and encryption secrets. Back up the recovery export securely; it is sensitive and is required to decrypt the vault on another machine.

./alv vault recovery cold --output /secure/location/cold-recovery.conf

Use that file as RCLONE_CONFIG on the recovery machine, verify the printed rclone target, then pass the printed encrypted target to alv vault add rclone to recreate the named profile.

Use with an agent

Repository-aware agents should read AGENTS.md before acting. Claude Code uses the CLAUDE.md bridge to load the same instructions. A useful starting request is: “Read AGENTS.md, inspect my setup read-only, explain the exact proposed actions, and ask before changing real Codex or cloud state.”

An agent may safely begin with ./alv --help, ./alv vault list, and ./alv list local. A general request to use the repository should not be treated as permission to offload or restore histories.

Validation

The test suite also requires rg (ripgrep). It runs ShellCheck when available.

./tests/run.sh

The tests use disposable Codex homes, local storage, rclone configurations, and provider mocks. They do not access the normal rclone configuration, cloud accounts, browser OAuth, or the real ~/.codex.

Separately approved macOS live tests have passed for local storage, Cloudflare R2, Backblaze B2, and Dropbox, including encrypted offload, read-back verification, restoration, and exact-byte comparison. OneDrive Personal has only isolated mock coverage so far.

License

MIT © 2026 Filip Pilar.