Use Agent Capture
Enable external-agent capture with libra agent
Use Agent Capture
The libra agent command installs capture hooks for supported external agent CLIs and lets Libra record sessions, checkpoints, and trace refs for later inspection.
Supported hook-installable agents are claude-code, codex, and opencode. Legacy gemini installs are uninstall-only: libra agent remove gemini removes old Libra-managed hooks, but new Gemini capture is not enabled.
Native Windows capture is available in current main source builds on local NTFS drives. It is not included in the v0.30.50 release binaries. Until a published release includes it, use the source build instructions. Read the Windows capture boundary before setup: the trusted native exporter uses a Job Object for process control, without an OS filesystem/network sandbox. Raw reasoning artifact export remains unavailable on Windows.
For macOS ordinary OpenCode capture, use Libra 0.30.49 or later compatible versions and official OpenCode
2.0.29. This captures safe ordinary conversation content; verified native
signature, redactedData and reasoningEncryptedContent archival remains a
separate, unproven path. A session row alone does not prove a transcript or
checkpoint was captured.
On macOS or Linux, before starting OpenCode in the repository, explicitly trust the reviewed exporter:
libra agent rpc trust --dir "$(dirname "$(which opencode)")"
libra agent rpc trust opencode
libra agent add opencode
Replace the directory with the actual directory containing your OpenCode binary.
The current CLI requires these two separate trust commands; --dir and the
opencode slug cannot be combined. Trust is repository-local and pinned to binary
bytes, so an OpenCode upgrade requires reviewing and trusting the new executable
again. Refresh the managed plugin with libra agent add opencode after upgrading
Libra, then restart OpenCode in this repository. --pure / OPENCODE_PURE=1
disables the plugin. No private OpenCode producer is required for ordinary capture.
After a turn, use the checkpoint list/show/export commands below. If you only see
a session, or an export is empty, run libra agent doctor for capture diagnostics.
Check libra --json agent list --schema-version 2 for OpenCode's importable and
export_bridge readiness and their unavailable reasons (trusted exporter or
required Unix sandbox or Windows native process boundary). Also verify plugin installation and captured source
completeness. Do not equate empty output with a successful capture. See the current command reference
for partial-capture and historical-import limits.
1. Check the Agent Matrix
Start by checking which agents Libra can manage on your machine:
libra agent list
libra agent status
Use JSON when scripting:
libra --json agent list
libra --json agent status
2. Enable Capture Hooks
Enable one agent explicitly:
libra agent add codex
Or enable every supported agent:
libra agent enable
add is an alias for enable; remove is an alias for disable. Libra writes only Libra-managed hook entries, so uninstalling removes those entries without owning unrelated user configuration.
Provider notes:
claude-codewrites a Libra-managed entry in.claude/settings.json.codexwrites user-level$CODEX_HOME/hooks.jsonand the matching Libra-managed trust entry in$CODEX_HOME/config.toml.opencodewrites.opencode/plugin/libra-hooks.js;opencode --puredisables external plugins, including capture.
3. Run Your Agent Tool
Use the external agent normally. Libra captures sessions and checkpoints through the installed hooks.
After a run, inspect what was captured:
libra agent session list
libra agent checkpoint list
libra agent checkpoint show <checkpoint-id>
To copy a session transcript:
libra agent session show <session-id> --extract-transcript /tmp/session.jsonl
Checkpoint transcript export is redacted by default. A raw export requires both an explicit request and authorization, and is written to the append-only audit log:
libra agent checkpoint export <checkpoint-id>
libra agent checkpoint export <checkpoint-id> --allow-raw --raw --justification "local debugging" -o /tmp/checkpoint.jsonl
4. Diagnose and Maintain Capture State
Run doctor in read-only mode first:
libra agent doctor
Repair recoverable checkpoint-store inconsistencies:
libra agent doctor --repair
Clean stopped-session checkpoints when they are no longer needed:
libra agent clean
libra agent clean --all
libra agent clean --gc --retention-days 30
Push agent trace refs to a remote:
libra agent push --remote origin
If clean rewrites the Libra-managed trace chain, use the guarded force-with-lease path:
libra agent push --remote origin --force-rewrite
5. Disable Capture
Disable one agent:
libra agent remove codex
Disable every supported agent:
libra agent disable
Captured sessions stay readable after hooks are removed.
Security Defaults
Agent capture is designed to fail closed:
- raw checkpoint export requires
--allow-raw --rawand an audit entry; - transcript and stderr output are redacted and capped;
- RPC adapters are disabled by default and must be explicitly trusted;
- unsupported agents are refused with actionable errors instead of silently falling back.
See the full command reference for every subcommand and option: libra agent.