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.

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.