lib-monosession. It
normalizes Claude Code, Codex, Grok, OpenCode, and Agy/Antigravity history into
one canonical model while retaining provider ids, text, thinking, tool calls,
tool results, timestamps, Git context, lineage, and unknown native data.
Published contract: monocli 0.2.13, OpenCLIs/CDN build
2026-07-16-155428, source commit
81e4569579ba89f781ad43f6011ac3b7d1fd74c0. Installed state, the executing
payload, latest.json, and release metadata agree on this identity. The signed
macOS ARM executable has SHA-256
2b3590686083a30ae2ece9bf4f695bdf436634b08cf73d9c0907a1f1248152ee.
Verify this release with the immutable path in
openclis list --json (.installed.monocli.path), not command -v alone. In
this audit ~/.openclis/bin/monocli resolved to that immutable payload and the
hashes agreed; the docs checker still executes the installed-state path
directly so a future shadow copy cannot silently change the proof target.docs_url is this page, the public product
homepage is https://monolex.ai, and MonoCLI pairs with Monometer, MonoFlow,
MonoLog, and Work Wiki. Repository ownership remains monolex/monolex; no
public source URL is advertised while that repository is private.
Quick Start
list,
search, translate, fork, reconcile, and test, plus lossless-refusal
and session-id recovery paths. Run monocli directly when no wrapper guidance
is needed.
Bare monocli opens the two-panel TUI when stdout is a terminal and prints a
non-interactive list when stdout is piped or redirected. Set
MONOCLI_DEFAULT=list|tui to override that decision.
Complete Command Map
The published payload exposes 23 operational root commands in addition to the bare default action, help, and version forms.
Root aliases are
ls, bl, grep, find, tl, xlate, browse, tail,
and p. help <command> dispatches to the same command-specific help as
<command> --help; --version, -V, and version print payload identity.
An unknown value containing / is treated as a session id and passed to
show; other unknown commands fail non-zero.
List, IDs, and Provider Stores
IDs use<provider>/<short> such as claude/7244c5a3, codex/019de9e0,
grok/05f90c2e, opencode/ses_54c2, or agy/67c5c950. A full native UUID is
also accepted when it resolves uniquely.
list applies provider, cwd-prefix, local-time --since/--until, and
sidechain filters before the default 30-row cap. --all removes that cap and
--json emits the canonical metadata envelope.
TUI Scope and Keys
The TUI defaults to sessions whose cwd is at or below the directory where it was launched. If that scope has no sessions, it widens to all sessions with a notice.--cwd sets an explicit subtree, --all removes cwd scope, and
MONOCLI_TUI_PROVIDER sets the default provider filter.
Key bindings can be reassigned in
~/.monolex/monocli-keymap.json or through a
file named by MONOCLI_KEYMAP. Navigation fallback keys and Esc/Ctrl+C remain
fixed safety controls.
Export and Search
export is the archival/share surface; read is the fast human stdout view.
search accepts --provider, --cwd, --since, --until,
--role user|assistant|tool, --limit, --per-session, --scan-limit,
--case-sensitive, --no-text, --no-tools, and --json. index writes
flattened canonical rows to the fts_sessions table in
~/.monolex/monocli.db; it supports --provider, --cwd, --limit,
--rebuild, and --verbose.
Live Watch, Statistics, and Timeline
watch selects a specific id, the most recent matching session, or the five
most recent sessions with --all. It polls every 500 ms by default and accepts
--provider, --cwd, and --poll.
stats groups by provider by default and selects the axis explicitly with
--by-provider, --by-cwd, or --by-model. It accepts --top, the list
time/cwd filters, --json, and --include-sidechains.
timeline supports provider/cwd/time filters, --min-msgs, --all, --gantt,
--by-cwd, --by-start, and --json; overlap markers require at least 30
seconds of intersecting session time.
Resume, Lineage, and Titles
resume and fork print commands; they do not silently execute an AI CLI.
fork also records a pending intent so a later link or reconcile --apply
can connect the new native id. pending --delete <n>, link, unlink,
reconcile --apply, and title writes mutate only the MonoCLI sidecar unless an
explicit native operation is requested.
The title precedence is sidecar over provider-native title.
title --clear
reveals the native title again. title --native appends a Codex
thread_name_updated event or updates OpenCode’s session title; Claude has no
post-hoc native rename layer.
Universal Native Transcode and Safety
translate has no fidelity levels, text fallback, or partial-session mode in
0.2.13. It consumes the complete canonical transcript—roles, timestamps, text,
thinking, tool calls/results, and images—and encodes it into the target’s native
resumable store. Use monocli export when the intended result is textual,
filtered, or truncated.
Claude, Codex, Grok, and OpenCode receive native image blocks with embedded
bytes. Local or temporary image paths are materialized before any target write;
the target does not retain that path as its only image source. Antigravity mints
and hydrates native
.pb/.db state through agy, writes byte-identical image
files beneath that conversation’s .user_uploaded directory, and links each
canonical image block to its durable file. A missing path, invalid payload,
unsupported URL-only image, or unproven target attachment surface aborts the
complete translation before mutation.
For Agy native seeding, 0.2.13 captures the direct agy --print child’s
stdout and stderr through temporary regular files. A short-lived Agy helper can
therefore inherit those descriptors without making MonoCLI wait forever for
pipe EOF after the direct child has already completed; the capture directory is
cleaned up on both success and error paths, with cleanup itself best-effort.
Unknown provider tool calls remain
Unknown { provider, raw_name, raw_args } in the canonical model rather than
being silently discarded. A pending lineage intent is staged only for a
successful translation workflow.
Verification and Platform Boundary
The installed macOS payload passed all five provider list smokes andmonocli test auto reported 23 passed / 0 failed during this audit,
including explicit checks that the picker exposes universal lossless transcode
and cannot downgrade to a text handoff. Every one of the 23 operational
commands also returned its command-specific help with exit code 0.
The clean 0.2.13 release source additionally passed 15 MonoCLI unit tests and
56 lib-monosession tests. Those engine tests cover local/file image-byte
materialization, native image round-trips, repeated cross-provider hops,
unknown tool preservation, Agy URL-only fail-closed behavior, and verified
Grok-prefix append safety. The added Agy regression proves the direct child
returns without waiting for a descendant that still owns an inherited stream.
The required five CDN platforms are darwin-aarch64, linux-x86_64,
linux-aarch64, windows-x86_64, and windows-aarch64.
The completed 0.2.13 release metadata declares all five CDN platforms and the
binary names
monocli and monocli.exe. Every immutable platform archive was
downloaded and its SHA-256 matched the metadata. Every platform builds from
commit 81e4569579ba89f781ad43f6011ac3b7d1fd74c0 with
source_dirty: false. This patch release also removes the obsolete
--command-only example from the packaged platform guide and documents Agy’s
.user_uploaded image-byte boundary. Build, publication, packaged-guide, and
local runtime proof remain separate in the table.
The WSL-managed Linux payload has SHA-256
a2eea3adbad38f8fbd820f49cf356f293df03ed9a022596b529de22fbc6e0801.
Its Claude and Codex provider list smokes returned sessions, while Grok and
OpenCode were not installed and Agy had no session. The Unix PTY self-test is
hard-wired to launch the Grok TUI, so monocli test auto exited before its
assertions in that provider-less environment. The successful macOS 23/23 PTY
run is not projected onto Linux; archive, installed payload, provider data, and
PTY-harness proof remain distinct.
The OpenCLIs-managed Windows x86_64 payload has SHA-256
c7990fd33ef9794802f779e1837323aeb788978e29996b1bd08ff510c7fd1740.
It reported 0.2.13, found Claude, Codex, Grok, and Antigravity stores, correctly
reported the absent OpenCode store, and returned a native Claude session through
list --json --limit 1. The Windows ARM64 executable has SHA-256
7ab961489dcf1c65937170395638eef8befa149fe0e3ef70ff657202651f2b71;
its PE architecture was inspected but no ARM64 Windows runtime was available.
Windows resolves ~ through the user profile. OpenCode additionally checks
platform data directories such as %LOCALAPPDATA%\\opencode and
%APPDATA%\\opencode.