> ## Documentation Index
> Fetch the complete documentation index at: https://docs.monolex.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# MonoCLI

> Browse, search, export, resume, translate, and relate local AI sessions from Claude Code, Codex, Grok, OpenCode, and Agy/Antigravity.

MonoCLI is the local, cross-CLI session browser built on `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`.*

<Warning>
  The public `0.2.13` release supports exactly **five providers**: Claude Code,
  Codex, Grok, OpenCode, and Agy/Antigravity. Its installed guide and public
  registry both hash to
  `de83afbb4753362f5e83919e06f9be38798225eab262186f06995ccb42b956ef`
  and do not advertise Cursor. The current development checkout still carries
  version `0.2.13`, but its dispatcher and guide add a read-only Cursor adapter;
  that source guide hashes to
  `823138fb49aa0d4e998e032b65cb3b80aa054b8a02d50b76ea79543a5bfc0d33`.
  Cursor is therefore development-only and is not part of the command or
  provider contract documented on this page.
</Warning>

<Note>
  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.
</Note>

*Registry ownership: the canonical `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

```bash theme={null}
openclis install monocli

monocli --version
monocli providers
monocli list --provider codex --limit 10
monocli show codex/<short-id>
monocli read codex/<short-id>
monocli search "kernel-cli" --provider codex
```

Use the public discovery guide and command-aware next-step wrapper when an
agent should receive the curated workflow after native output:

```bash theme={null}
openclis init monocli
OPENCLIS_NEXT=1 openclis monocli providers
```

The wrapper preserves MonoCLI's output and adds bounded routes for `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.

| Command            | What it does                                                                             | Important controls or effect                                                                                    |
| ------------------ | ---------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| `tui`              | Opens the interactive two-panel browser.                                                 | `--cwd`, `--provider`, `--limit`, `--all`; alias: `browse`.                                                     |
| `list`             | Enumerates canonical session metadata.                                                   | `--provider`, `--cwd`, `--since`, `--until`, `--limit`, `--all`, `--json`, `--include-sidechains`; alias: `ls`. |
| `show <id>`        | Shows metadata plus first/last message preview.                                          | Read-only; `monocli provider/id` is an implicit `show`.                                                         |
| `read <id>`        | Renders the full canonical conversation as Markdown.                                     | Read-only human view.                                                                                           |
| `cat <id>`         | Passes through raw native JSONL.                                                         | Supported for file-backed Claude and Codex sessions.                                                            |
| `export <id>`      | Produces a share or archive representation.                                              | Markdown, JSON, JSONL, or text; optional output-file write and redaction.                                       |
| `search <pattern>` | Searches text and tool blocks across sessions.                                           | FTS5 BM25 when indexed, otherwise linear scan; aliases: `grep`, `find`.                                         |
| `index`            | Populates the sidecar FTS5 index.                                                        | Incremental by default; `--rebuild` replaces derived search rows.                                               |
| `watch [id]`       | Live-tails one or more provider sessions.                                                | Poll loop until Ctrl+C; aliases: `tail`.                                                                        |
| `stats`            | Aggregates activity by provider, cwd, or model.                                          | Read-only dashboard with optional JSON.                                                                         |
| `timeline`         | Joins sessions, time ranges, Git context, overlap, and lineage.                          | Read-only; alias: `tl`.                                                                                         |
| `test`             | Runs the Unix PTY TUI harness.                                                           | `auto`, `spawn`, `screen`, or `key <key>`; `auto` currently has 23 assertions.                                  |
| `resume <id>`      | Prints a provider-native resume command.                                                 | Does not launch it; `--copy` writes the clipboard.                                                              |
| `fork <id>`        | Prints a native fork command and stages expected lineage.                                | Sidecar pending-intent write; the emitted command is not run automatically.                                     |
| `translate <id>`   | Strictly transcodes the complete session into another provider's native resumable store. | Dry-run temporary output unless `--native`; `--target-cwd`, `--launch`; alias: `xlate`.                         |
| `link <child>`     | Creates an explicit parent edge.                                                         | Cross-provider sidecar mutation; optional child title/reason.                                                   |
| `unlink <child>`   | Removes the child's sidecar parent edge.                                                 | Convenience form of `link <child> --unlink`.                                                                    |
| `pending`          | Lists or deletes staged fork/translate intents.                                          | Read-only unless `--delete <n>` is supplied.                                                                    |
| `reconcile`        | Matches new sessions to pending intents.                                                 | Dry-run by default; `--apply` writes only unambiguous matches.                                                  |
| `title <id>`       | Reads, sets, or clears the effective title.                                              | Sidecar write by default; `--native` can also alter supported provider storage.                                 |
| `tree <id>`        | Walks parent-first lineage.                                                              | `--depth <n>`; read-only.                                                                                       |
| `backlinks <id>`   | Walks children and optional siblings.                                                    | `--depth`, `--siblings`, `--json`; alias: `bl`.                                                                 |
| `providers`        | Reports adapter availability and expected roots.                                         | Read-only; alias: `p`.                                                                                          |

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.

| Provider        | Primary local source                                                    | Raw `cat`                          |
| --------------- | ----------------------------------------------------------------------- | ---------------------------------- |
| Claude Code     | `~/.claude/projects/<encoded-cwd>/<uuid>.jsonl`                         | Yes                                |
| Codex           | `~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl`                          | Yes                                |
| Grok            | `~/.grok/sessions/<encoded-cwd>/<uuid>/`                                | No; canonical read/export only     |
| OpenCode        | `~/.local/share/opencode/opencode.db`, then platform data-dir fallbacks | No; canonical read/export only     |
| Agy/Antigravity | Canonical mirror beneath `~/.gemini/antigravity-cli/brain/`             | No; opaque state is owned by `agy` |

`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.

| View         | Keys                                            | Action                                                                                  |
| ------------ | ----------------------------------------------- | --------------------------------------------------------------------------------------- |
| Session list | arrows or `j` / `k`, PageUp/PageDown, `g` / `G` | Navigate rows                                                                           |
| Session list | Enter                                           | Open the full conversation inside the TUI                                               |
| Session list | `r`, `f`, `t`, `e`                              | Resume, fork, lineage tree, or edit sidecar title                                       |
| Session list | `x`                                             | Open the universal native-transcode provider picker; there is no text-handoff downgrade |
| Session list | `a`, `/`, `R`                                   | Toggle cwd/all scope, filter, or reload                                                 |
| Read view    | `n` / `p`, `]` / `[`, Space, PageUp/PageDown    | Jump prompts/tool calls or scroll                                                       |
| Any view     | `q`, Esc                                        | Back or quit                                                                            |

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.

| Export option                                      | Meaning                                           |                                |                       |                                    |
| -------------------------------------------------- | ------------------------------------------------- | ------------------------------ | --------------------- | ---------------------------------- |
| \`--format md                                      | json                                              | jsonl                          | text\`                | Output shape; Markdown is default. |
| `--out <path>`                                     | Writes a file instead of stdout.                  |                                |                       |                                    |
| `--redact`                                         | Masks common credential shapes and the home path. |                                |                       |                                    |
| \`--filter-role user                               | assistant\`                                       | Keeps one conversational role. |                       |                                    |
| \`--tools full                                     | summary                                           | skip\`                         | Controls tool blocks. |                                    |
| `--tail <n>`, `--max-chars <n>`                    | Bounds long exports.                              |                                |                       |                                    |
| `--no-frontmatter`, `--no-system`, `--no-thinking` | Removes selected metadata or blocks.              |                                |                       |                                    |

`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

```bash theme={null}
monocli watch codex/<id> --poll 1000
monocli watch --all --provider claude
monocli stats --by-cwd --top 20 --since 2026-07-01
monocli timeline --providers claude,codex --gantt --all
```

`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.

| Operation               | Controls and provider boundary                                                                                                                                                                                                    |
| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `resume <id>`           | `--copy` also writes the command to the clipboard; `--prompt` appends an initial prompt. Grok alone supports `--new-worktree` and `--checkout-commit`.                                                                            |
| `fork <id>`             | `--name`, `--reason`, and `--prompt` describe the pending child; `--copy` copies the emitted native command. Claude uses `--fork-session`, Codex uses `codex fork`, and Grok uses `--start-new-worktree` in that emitted command. |
| `link <child>`          | Requires `--parent <id>` unless removing an edge; accepts `--name`, `--reason`, and `--resolve-pending <n>`. `--unlink` removes the edge, and the root `unlink` command is its convenience form.                                  |
| `pending` / `reconcile` | `pending --delete <n>` removes one intent. `reconcile` previews matches; only `--apply` persists unambiguous matches.                                                                                                             |
| `title <id>`            | With no new value, reads the effective title. A string writes the sidecar, `--clear` removes it, and `--native` also updates Codex or OpenCode native storage where supported.                                                    |

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.

| Invocation                                | Result                                                         | Write boundary                                               |
| ----------------------------------------- | -------------------------------------------------------------- | ------------------------------------------------------------ |
| `translate <id> --to <provider>`          | Builds and validates a temporary native target representation. | Dry-run; does not change the target store.                   |
| `translate <id> --to <provider> --native` | Writes the complete validated native session.                  | Target-store mutation only after all blocks pass validation. |
| Add `--target-cwd <dir>`                  | Selects the destination resume directory.                      | Defaults to the source cwd.                                  |
| Add `--launch`                            | Resumes the translated session after the native write.         | Valid only with `--native`; launches the target CLI.         |

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 and
`monocli 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`.

| Public platform   | CDN archive SHA-256                                                | Release proof                                   | Runtime proof in this audit                                                                |
| ----------------- | ------------------------------------------------------------------ | ----------------------------------------------- | ------------------------------------------------------------------------------------------ |
| `darwin-aarch64`  | `b06cc34cdb3c2222167a313ed623b703b773bc320d6832b0162560c002c7fc46` | Published                                       | Five provider smokes and 23/23 PTY tests                                                   |
| `linux-x86_64`    | `4ce8d067890d9dcd562a2445a5fd430f078c7607d542403fb28aa0b770322d4b` | Published by Linux CI and directly downloaded   | Installed in Ubuntu 24.04 under WSL; version/build and strict-lossless image help verified |
| `linux-aarch64`   | `f37c3e9f4672a0525b7102d077b6d106bc13a53576f8ce09b99a774412c80bc9` | Published by Linux CI and directly downloaded   | Archive inspected; not executed in this audit                                              |
| `windows-x86_64`  | `095ebed60a8950f60e9838c88cea5c4a8f2007e62e324f20af084c51d214ee74` | Published by Windows CI and directly downloaded | Installed on Windows 11; version, providers, and a native session row verified             |
| `windows-aarch64` | `218ad34b09fd6d8c3305727162a025e374bc64fc6606a715f2d1ad7e5ffdbacf` | Published by Windows CI and directly downloaded | Archive inspected as an ARM64 PE executable; not executed in this audit                    |

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`.

## Relationships

| Tool                            | Ownership                                                          |
| ------------------------------- | ------------------------------------------------------------------ |
| [Monometer](/ai-clis/monometer) | Token, cost, quota, and usage aggregates over related sessions     |
| [MonoFlow](/ai-clis/monoflow)   | Temporal code/Git/work joins rather than conversation rendering    |
| [Monolog](/ai-clis/monolog)     | Persisted PTY activity rather than provider-native conversations   |
| [Work Wiki](/ai-clis/work-wiki) | Project knowledge composition across session and activity evidence |