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-code writes a Libra-managed entry in .claude/settings.json.
  • codex writes user-level $CODEX_HOME/hooks.json and the matching Libra-managed trust entry in $CODEX_HOME/config.toml.
  • opencode writes .opencode/plugin/libra-hooks.js; opencode --pure disables 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 --raw and 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.