usage.md

Usage

cd ~/code/my-app
openmax

On the first interactive run, inspect the project and answer the trust prompt: y trusts it in auto mode, a in ask, and r in readonly. Change the mode later with /approvals or Shift+Tab. See configuration for headless and stdio trust.

Command line

openmax --continue                    # resume latest session here
openmax -c
openmax --provider ollama --model qwen2.5-coder:7b
openmax -p "summarize the top level layout of this repo"
openmax -p --json "list public modules in crates/core"
openmax --check                       # validate extension files and the session index
openmax --spec hooks                  # print an extension surface's contract
openmax --recall "deploy port"        # search past sessions and memories
openmax --stdio                       # full session over JSONL pipes
openmax --mcp-list -- <server>        # list an MCP server's tools

openmax --mcp-list and openmax --mcp-call are a one-shot MCP stdio client, used by the proxy tool an MCP server is adopted through; see extending and openmax --spec mcp.

openmax --check --json prints the same findings as one JSON array of {surface, path, status, message} objects (status ok, warn, or err), with the same exit code, so the agent can parse its own verification.

openmax --check --run-examples adds one example surface row per declared [example], in text and in JSON, and fails the check when one fails. It is the only --check mode that executes anything, so it needs a trusted project and follows the saved project mode. Auto runs valid examples without content approval; ask uses the documented approval and sandbox rules. It honors permission rules, pre_tool_use hooks, and approval_mode exactly as a turn does. See extending.

In print mode, text goes to stdout and tool progress to stderr. With --json, each AgentEvent is one JSON line on stdout. Mutating tools honor the project's approval mode, and a print run declines every approval request, so unattended runs need auto: the mode a trust grant records unless you pick another. For a project in ask, select /approvals auto once.

openmax --stdio is the contract for custom frontends, editor integrations, and one openmax driving another. It is specified in stdio protocol.

A writable session can be open in only one process at a time, including while it is idle. Close it in the other process or start a new session to continue working. /new and switching sessions release the old attachment after any in-flight work settles. A process exit releases its session locks. Read-only history and recall remain available.

A damaged or unreadable transcript stops continuation with its path and the failure reason. Open Max preserves the original bytes and does not silently skip records or replace the transcript. Repair or recover a copy explicitly before resuming. A crash or power loss mid-save is not damage. A final record it cut off never became a message, so the session resumes from the last complete record and the next save removes the fragment. A session whose first save it interrupted has no transcript yet, and like any session that has never saved messages, starts fresh.

A damaged or unreadable session index (~/.openmax/sessions/index.json) refuses new sessions and continuation with its path, and the app keeps running. Open Max never replaces it with an empty index. Run openmax --check for the repair: close every openmax, then move the file aside.

Keys

Input	Action
Enter	Send (queues if the agent is busy)
/	Slash commands · Tab or Enter completes
@	Mention a project file
Mouse drag	Select transcript or prompt text
Double / triple click	Select the word under the pointer · the whole logical line
y or Ctrl+C	Copy selected text (Ctrl+C cancels when nothing is selected)
Click in the prompt	Put the cursor there in a wrapped draft
Wheel	Scroll the conversation · over the prompt, a long draft
Shift+Tab	Cycle and save project approvals: ask → auto → readonly
Esc	Clear selection · close menu · cancel turn · return to composer
Ctrl+C twice	Quit

Slash commands

Slash command	Action
/help	Keybindings and commands
/model	Search configured providers and select a model
/model <id>	Set an exact model id on the active endpoint
/copy	Copy the latest assistant response
/provider [name]	List or switch providers
/approvals auto|ask|readonly	Save this project's execution mode
/new · /resume	Fresh session · pick an earlier one
/reload	Force a re-freeze now (it also happens automatically when extension files change)
/tools · /skills · /context	Session tools, skills, token budget
/compact	Compact the context now instead of waiting for the budget to force it
/export [path]	Write the transcript as markdown (default openmax-<session>.md in the project)
/<template> [args]	Run a prompt template from .agents/prompts/
/status	Endpoint, cache, performance, privacy, and network details
/quit	Exit

The persistent status line stays limited to model, context use, and approval mode so the transcript remains readable; /status is where the full runtime detail lives.