Monogram Reference - Monolex Docs

This is the public command reference for the OpenCLIs release monogram 0.98.6. In a non-TTY agent process, bare monogram and monogram help print a compact entry brief. Pull the full installed manual with monogram help --full or monogram docs initiate; monogram mcp-schema is the machine-readable authority for the MCP-visible command contract.

monogram --version
monogram mcp-schema
monogram verify

For index ownership and freshness, see Scope & Index Management. For coupling, semantic evidence, and possibility bands, see Audit & Correctness.

Contract preflight

Use these commands before ordinary code search when the task is a behavioral contract rather than a simple location question.

`monogram spec-audit`

Turns a public task or specification into leak-safe edge bands and executable Monogram follow-ups.

monogram spec-audit instruction.md --against .
cat instruction.md | monogram spec-audit --stdin --against . --json

It is a preflight, not a hidden-test oracle. Use the leading band to define an edge test, then return its named connection point to region, context, chain, and coupling.

`monogram sequence`

Runs the stateful contract loop: locate code, deepen the structural fork, define connection points, and close the ordered review after the final edit.

monogram sequence start "<task>" --from spec.md
monogram sequence status current
monogram sequence deepen current
monogram sequence define current
monogram sequence finish current
monogram sequence list
monogram sequence resume <id>

Subcommand	State and output boundary
`start`	Creates a session under `$MONOGRAM_HOME/problem-definitions/` when the override is set, otherwise under repo-local `.monogram/problem-definitions/`; persists `spec.md`, `scope.json`, metadata and the current pointer, records `source_path` plus a task-content `source_digest` when `--from` is used, then runs `define` automatically
`deepen`	Adds the next bounded problem-definition document and advances the sequence depth
`define`	Writes or refreshes `connection-points.md` for the current evidence set
`finish`	Re-presents the final review, writes `finish.json`, and changes the session phase to `finished`
`resume`	Changes the repo-local current-session pointer
`status`, `list`	Read session state only

sequence define writes connection-points.md. It joins the spec bands, IAW-SOP contract gates, advisory trigram structure, and embedded fix-shape knowledge. Its leading [IAW-SOP] ORDER chain is binding: bind the contract, consult the Book before the first Edit/Write when knowledge is present, implement and test, then run sequence finish after the last Edit/Write. sequence finish re-presents the saved spec.md and available Book section, writes a finish.json witness, and sets meta.json phase to finished. It does not edit product source. JSON output from start, define, and status carries the same order contract, while status and resume re-emit the phase and next position after context loss. The generated documents remain substrate for proof; the agent still decides which contract applies and must satisfy each gate with source and test evidence. Use MONOGRAM_HOME for benchmark and disposable-worktree isolation. Since 0.98.2 the sequence session follows that override as well as the index databases, so start, deepen, define, finish, and resume do not introduce a repo-local .monogram/ directory in an isolated run. Human-readable stats, search, and region results and every packaged discovery guide use session and task identity to choose at most one inbound hint. TASK.md, PLAN.md, BUG.md, .task.md, cwd .monobench-task-instruction.md, and the historical /tmp/monobench-task-instruction.md path are recognized task sources. A task whose FNV-1a 64-bit content digest is absent from existing session metadata gets a runnable sequence start task --from <path> hint. The digest is an identity gate, not a security hash. When the current session is open and no checked scope file is newer than its UTC start, the hint reports ORDER OPEN (<id>), the exact connection-points.md path to re-read after compaction, and sequence finish as the closing verb after the final Edit/Write. Once a saved scope-file mtime crosses that start boundary, the hint escalates to edits detected in its scope and the final-close wording. Missing or malformed session/scope data and unresolvable files fail quiet rather than breaking a search. Successful stats --json, search --json, and region --json responses carry the same decision in sequence_hint: a string when the edge exists, otherwise null. MCP always invokes these commands through JSON, so it inherits that field. Finishing the session suppresses the same task; a different recognized task digest triggers entry again. Legacy sessions with no digest remain readable and suppress only the generic placeholder. This adds a response field, not a 51st MCP command.

`monogram format-trace`

Treats a data or configuration format as a language plane with symbols, references, scopes, branches, and runtime behavior.

monogram format-trace json-schema schema.ts
monogram format-trace openapi api.yaml
monogram format-trace openapi-yaml api.yaml
monogram format-trace hcl modules/
monogram format-trace cargo-toml Cargo.toml

The public planes are json-schema, openapi, openapi-yaml, hcl, and cargo-toml; generic yaml and toml are intentionally not public planes. JSON Schema output includes reference cycles, generator/runtime markers, completion_gate, and required positive/negative probes. A blocked gate is unfinished work, not informational decoration.

Locate

`monogram search`

Ranks files and symbols using trigram, compound-identifier, coverage, and size evidence.

monogram search "terminal font size"
monogram search "session manager" -n 5 --file src --lang ts
monogram search "ownership handoff" --explain --score-debug

Useful controls include -n, --cwd, --file, --lang, --explain, --score-debug, --bands, --json, and -r. Ranking is lexical/structural relevance, not root-cause proof. Follow the printed file-scoped region or symbol proof rather than repeatedly broadening the same search.

`monogram region`

Fuses fuzzy search, raw hits, structural references, graph, coupling, and metrics into ranked functional source regions.

monogram region "session reconnect lifecycle" -n 5
monogram region "create session invoke" --domain tauri-ipc --score-debug

-n caps displayed regions, not the evidence scan. --file and --lang retain scope; --domain can bias http, sql, pubsub, tauri-ipc, ffi, event, css-token, or export-import. A close-score contrast lock asks you to compare bounded candidates before choosing one.

`monogram symbols`

Lists exact definitions with kind, signature, and file:line evidence.

monogram symbols createSession
monogram symbols "retry with backoff" --comments --file src

`monogram grep` and `monogram refgrep`

grep combines native indexed code-line hits with structural references; refgrep restricts the query to reference targets.

monogram grep "conn.execute" -C 3 --file src
monogram grep "emit(" --raw
monogram refgrep "conn.execute" --chain --depth 2

Single-line alternation and simple regex forms are supported. Use -C, -A, or -B for bounded context inside Monogram rather than piping the result through shell filters. Broad lifecycle/ownership terms are guarded and redirected toward file-scoped regions before expensive caller fan-out.

Navigate and prove

`monogram context`

Returns relevant entry symbols, one-hop graph evidence, and line-numbered source in one call.

monogram context reconnect_session --code 40
monogram context "SessionActor at 812" --file src/lib.rs --code 80

Inline source is capped at 80 lines. Large types expose member follow-ups instead of dumping an entire definition.

`monogram trace` and `monogram investigate`

monogram trace reconnect_session
monogram investigate reconnect_session --file session

trace is the bounded composite: definition, callers, callees, and a coupling-boundary cue. investigate also runs the coupling boundary and identifies the highest fan-in edit anchor. Use trace for a quick role view; use investigate when the boundary must be present in the same report.

`monogram chain` and `monogram tree`

monogram chain reconnect_session --callers --depth 2
monogram tree reconnect_session --callees --depth 3

chain is a flat BFS view; tree is a hierarchical DFS view. --file, --lang, --through, and bounded depth keep homonyms and fan-out under control. Broad roots are staged into smaller expansions rather than returning an unbounded graph.

`monogram provenance`

Traces where a value originates: writers, writer callees, and the raw-source versus transformed-view fork.

monogram provenance session_token
monogram provenance getSessionToken

It requires a verified deep index. Use it for field/getter origin questions; use chain for call ownership.

`monogram deps`, `monogram rdeps`, and `monogram css`

monogram deps src/main.ts
monogram rdeps src/session.ts
monogram css src/styles/main.css

deps follows outgoing imports, rdeps follows the reverse dependency radius, and css flattens a stylesheet’s @import graph in cascade order while marking duplicate imports.

Complete 50-tool MCP inventory

The following CLI names map to the 50 tools returned by the live Monogram MCP server (MCP names use the monogram_ prefix and underscore-normalized command names). This count excludes local index administration and terminal integration commands.

Command	What it returns
`monogram search`	Ranked files and symbols for a fuzzy query
`monogram symbols`	Exact symbol definitions and signatures
`monogram grep`	Indexed raw code hits plus structural references
`monogram region`	Ranked functional regions from fused evidence
`monogram spec-audit`	Public-spec terms, edge bands, and follow-up commands
`monogram sequence`	Stateful locate/deepen/define/finish ORDER-contract workflow
`monogram refgrep`	Structural reference hits and containing functions
`monogram chain`	Flat caller or callee graph
`monogram trace`	Bounded definition + callers + callees + boundary cue
`monogram tree`	Hierarchical caller or callee tree
`monogram deps`	Outgoing file dependencies
`monogram rdeps`	Reverse dependencies and impact radius
`monogram coupling`	Cross-boundary binding findings
`monogram context`	Entry points, one-hop graph, and source context
`monogram provenance`	Value writers and raw-versus-transformed origin
`monogram investigate`	Locate + blast radius + executed coupling boundary

Structural, index, and format audits: 12 tools

Command	What it returns
`monogram metrics`	Per-symbol size, fan-in/out, depth, parameter, recursion, and coupling metrics
`monogram uncalled`	Functions with no inbound indexed call edge
`monogram unused-imports`	Local import candidates unused outside their import line
`monogram css`	CSS import/cascade order and duplicates
`monogram important`	Report-only `!important` classifications and migration plans
`monogram errors`	Compiler-error categories joined to symbols and impact radius
`monogram stats`	Core index counts, identity, schema/corpus state, and optional deep status
`monogram semantic`	Semantic-core modes such as status, references, drift, effects, and compiler facts
`monogram format-trace`	Format-language references, scopes, runtime markers, and completion gates
`monogram list`	Registered projects, freshness, size, and GC health
`monogram boot`	Read-only boot/entry trace from the configured or supplied entry
`monogram inspect`	Per-symbol meaning, effects, roles, and reachability evidence

Deep graph and possibility bands: 22 tools

Command	What it returns
`monogram effect`	Functions carrying one named semantic effect
`monogram hubs`	Resolved graph fan-in/fan-out hubs
`monogram lifecycle`	Lifecycle or teardown closure evidence
`monogram unsafe-reach`	Functions transitively reaching unsafe operations
`monogram modules`	Semantic module/import/export graph
`monogram injection`	Resolved source-to-sink taint candidates
`monogram blocking-in-async`	Known blocking calls inside Rust/Python async code
`monogram lock-across-await`	Rust or C# lock/guard spans across await
`monogram select-sites`	Complete `tokio::select!` review worklist
`monogram worklist`	Named Tier-0 worklist, such as `banned-libc`
`monogram panic-reach`	Tauri commands that transitively reach panic/abort
`monogram unsafe-send`	Explicit hand-written Rust `unsafe impl Send/Sync` rows
`monogram async-void`	C# `async void` candidates
`monogram rescue-exception`	Ruby `rescue Exception` candidates
`monogram throwing-dtor`	C++ destructors that may throw
`monogram floating-promise`	TS/JS async calls without completion/error ownership
`monogram mutable-defaults`	Python collection-literal parameter defaults
`monogram contract-pair`	Java or Python equality/hash pair asymmetry
`monogram is-literal`	Python value comparisons using identity
`monogram bitwise-precedence`	C bitwise/comparison precedence candidates
`monogram bridges`	Resolved frontend-invoke to Tauri-command bridges
`monogram types`	Semantic type declarations and members

All deep graph and possibility-band tools require monogram index . --deep and a healthy monogram semantic status. Their rows are evidence leads or complete worklists, not automatic bug verdicts.

CLI-only administration and integration

These commands are real public CLI functions but are intentionally outside the 50-tool MCP investigation inventory:

Command	Boundary
`monogram index <path>`	Incrementally writes the project index and, by default, its semantic companion
`monogram reindex <path>`	Crash-safe full rebuild; rejects `--files-from`
`monogram prune`	Removes dead rows from the current index; supports dry-run
`monogram prune --registry`	Plans or performs registry/database cleanup
`monogram scope`	Shows or changes `.monogram/scope.json`; `scope apply` purges excluded index rows
`monogram boot init`	Writes `.monogram/boot.toml` after detecting entry, priority arrays, and guards
`monogram docs`	Lists six embedded topics: four progressive guides plus `initiate` (full reference) and `skill` (agent map)
`monogram help --full`	Prints the complete reference even when stdout is not a TTY
`monogram version` / `monogram --version`	Prints the executing version; `version --json` is rejected
`monogram verify`	Checks this binary’s embedded initiate tree and Book snapshot consistency
`monogram hook claude`	Fail-quiet single-file core-index refresh carrier; no deep pass or schema migration
`monogram mcp`	Starts the 50-tool stdio MCP server
`monogram mcp-schema`	Prints wrapper schema JSON without starting the server

MONOGRAM_PREPARED_INDEX=1 blocks index-mutating commands, -r, prune, and boot init for harnesses that pin a prepared database.

Shared output controls

Many commands support the same evidence controls:

Control	Purpose
`--file <substring>`	Preserve a known file boundary
`--lang <extension>`	Restrict a language family
`-n <count>`	Bound displayed rows, not necessarily the evidence scan
`--score-debug`	Show score-family terms, coverage, and rank evidence
`--bands`	Attach navigation-enabled CWE/Book matches; off by default and needs deep index
`--json`	Structured output with `next_hint` and budget/truncation metadata on guarded paths
`-r` / `--reindex`	Incrementally refresh before the requested investigation

Avoid shell-side head, grep, or ad hoc file discovery when the command provides a bounded option or printed [NEXT]. Keeping the scope and proof inside Monogram preserves its candidate ordering and guard rails.

End-to-end examples

# Public behavior -> contract bands -> implementation -> boundary proof
monogram spec-audit instruction.md --against .
monogram region "reconnect stale token" -n 5 --score-debug
monogram investigate reconnect_session --file session
monogram coupling --domain event --pattern reconnect --all

# Value-origin question
monogram context getSessionToken --file session --code 60
monogram provenance session_token

# Format contract
monogram format-trace json-schema src/schema.ts
monogram context parseSchema --file schema
monogram chain parseSchema --callees --depth 2

# Deep worklist -> concrete proof
monogram semantic status
monogram lock-across-await --lang rust -n 20
monogram context acquire_session_lock --code 80
monogram chain acquire_session_lock --callers --depth 1

​Contract preflight

​monogram spec-audit

​monogram sequence

​monogram format-trace

​Locate

​monogram search

​monogram region

​monogram symbols

​monogram grep and monogram refgrep

​Navigate and prove

​monogram context

​monogram trace and monogram investigate

​monogram chain and monogram tree

​monogram provenance

​monogram deps, monogram rdeps, and monogram css

​Complete 50-tool MCP inventory

​Contract, locate, and navigation: 16 tools

​Structural, index, and format audits: 12 tools

​Deep graph and possibility bands: 22 tools

​CLI-only administration and integration

​Shared output controls

​End-to-end examples