Using omp

Anatomy of an interactive session

Bare omp opens an interactive session. The screen has four regions, top to bottom:

Header The OMP logo on first launch, then a compact session header once the conversation starts: title, current branch in the session tree, and any active mode banner (plan, loop, goal). Messages User prompts, assistant turns, and tool-call cards. Each tool call renders as a one-line summary; Ctrl+O expands the card to show full output, full diff, or full bash transcript. Editor Multi-line input with file references, path completion, image paste, shell escapes, and an external-editor handoff. Footer Two dim lines (three when an extension publishes status). Line one: working directory and current git branch. Line two: token counters, cost, context usage, and the active model.

Editor features

Feature	How	What it does
File reference	`@`	Fuzzy-search project files (respects `.gitignore`). At send time each reference is replaced with the file’s contents inlined into the prompt.
Path completion	Tab	Completes relative paths, `../`, `~/`, and similar prefixes.
Multi-line	Shift+Enter / Alt+Enter	Insert a newline. On Windows Terminal use Alt+Enter (it doesn’t deliver Shift+Enter).
Image attach	Ctrl+V, drag-and-drop, or `@image.png`	Paste from clipboard, drag from the OS file manager, or inline a path. The active model must accept image input or the attachment is dropped on send with a warning.
Shell escape (visible)	`!`	Prefix a prompt with `!` to execute as a shell command and include the output in context. Streams in real time. Escape cancels.
Shell escape (hidden)	`!!`	Same as `!`, but excludes the output from LLM context. Output still streams to your terminal.
Python escape	`$` / `$$`	Run in a shared Python kernel. `$$` hides output from context the same way `!!` does for bash.
External editor	Ctrl+G	Open the current draft in `$VISUAL` / `$EDITOR`; saves back into the editor on exit.
Prompt actions	#	Open the prompt-actions menu over the current draft.

The full chord list (history search, line motions, copy chords, model cycling) lives on Keybindings.

Message queue

Type while the agent is working and nothing is dropped. Messages submitted mid-turn queue and drain in two lanes.

Chord	Lane	Delivered
Enter	Steering message	After the current assistant turn finishes its tool calls. Use to course-correct in flight.
Ctrl+Q / Ctrl+Enter	Follow-up	After the agent finishes all queued work and yields. Use for “and then this”.
Escape	—	Aborts the active turn. Queued steering and follow-up messages are restored to the editor stack rather than discarded.
Alt+Up	—	Dequeue the most recent queued message back into the editor.

Three settings shape the behaviour, under /settings → Interaction or as top-level keys in ~/.omp/agent/config.yml.`:

steeringMode — all or one-at-a-time (default).
followUpMode — all or one-at-a-time (default).
interruptMode — immediate (default) or wait.

Modes

Interactive is the default. The other modes are non-interactive surfaces selected with --print or --mode <mode>.

Mode	Invoke	Output	Use for
Interactive (default)	`omp`	TUI	Day-to-day work.
Print	`omp -p "prompt"`	Plain text on stdout, no TUI.	Scripts, CI, shell pipelines.
JSON	`omp --mode json -p "prompt"`	Newline-delimited JSON events on stdout.	Stable shape for piping into other tools.
RPC	`omp --mode rpc`	JSON-RPC over stdio.	SDK and programmatic clients. See RPC mode.
ACP	`omp --mode acp` (or `omp acp`)	Agent Client Protocol over stdio.	Editors and other ACP-aware hosts. See ACP.

--mode rpc-ui is a variant of rpc that surfaces the in-TUI tool-call UI to the client. The full flag inventory lives on the CLI page.

Plan mode

Reach for plan mode before changes that touch more than one file or have non-obvious sequencing. /plan sandboxes a planning turn against a separate planner model held to read-only work (it may write only its plan file); on approval you choose to execute and purge, keep the transcript, or compact context. Full walkthrough on the Plan mode page.\n