Omux defines 17 tools with explicit schemas, descriptions, and parameter types. Most tools follow verb_noun naming (send_to_agent, inspect_agent, memory_search). Descriptions are detailed and context-aware, averaging ~150 - 250 chars. However, several tools lack output schema documentation, and some parameter descriptions could be more prescriptive about constraints. Error handling guidance is minimal, tools return success/failure but rarely guide recovery. Tool composition is strong: agent-tools chain well (send → inspect → interrupt), and memory-tools support pagination (memory_get with from/lines). Security is reasonable: no credentials in params, but audit logging and permission gates are not visible in definitions.
Create a new coding agent in a tmux session. The agent runs asynchronously in the background. You can send instructions to it with send_to_agent, inspect its state with inspect_agent, and interrupt it with interrupt_agent. Returns the agent_id (name) and initial status.
Escalate the current situation to the human operator and return to idle state. Use when proceeding autonomously would be riskier than pausing: destructive/irreversible operations, ambiguous user intent, major architectural trade-offs, scope expansion beyond the original request, security-sensitive changes, or production/shared resource modifications.
Execute a bash command directly for read-only reconnaissance. Use for reading files, browsing directories, searching code, and checking environment info. NEVER use for modifications, tests, builds, git operations, or any command with side effects — those MUST go through send_to_agent. Large-file pre-flight: bare reads such as `cat <file>` / `less <file>` / `more <file>` / `bat <file>` / `view <file>` / `nl <file>` are intercepted before execution. If the target exceeds 500 lines or 50 KB, the command is REFUSED and you receive file metadata plus paging hints (head/tail/sed). Add an output limiter (`| head -200`, `head -n 200 file`, `sed -n '1,200p' file`, etc.) to bypass the check. For memory/ files, prefer memory_get which pages natively.
Inspect the current state and recent logs of a coding agent. Returns the agent's status, current task (if any), and the last N lines of its tmux pane output. If agent_id is omitted, routes to the most recently used agent.
Output schemas not documented for any tool. LLMs cannot plan downstream calls or extract required fields without knowing response structure.
memory_edit and memory_write are duplicate tools with identical signatures. Reduces clarity and forces LLM to reason about which to use.
Error handling descriptions are absent. Tools return success/failure but do not guide LLM on recovery (retry, ask user, escalate). E.g., send_to_agent says 'returns immediately' but does not explain what happens if agent crashes.
Inferred effective spec: <=2025-11-25.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-23 | C | 65 | <=2025-11-25 | v2 |
Interrupt a coding agent that is going off track by sending an Escape key to its tmux session. This immediately interrupts the agent's current operation without destroying the session. Use when the agent is deviating from the goal and you want to regain control before sending a corrected instruction. If agent_id is omitted, routes to the most recently used agent.
Terminate a coding agent and clean up its tmux session. Use when an agent is stuck or no longer needed. If agent_id is omitted, routes to the most recently used agent.
List all active coding agents and their current status. Returns agent names, types, project directories, and task states.
Mark the current task as failed and return to idle state. Use when the task cannot be accomplished.
Edit a file in the SEARCHABLE memory store (memory/*.md, indexed for memory_search / memory_get). Supports append (default), overwrite, search-and-replace, and delete. Only memory/*.md files are allowed. This is NOT the always-in-prompt MEMORY.md — to edit the global/project MEMORY.md snapshot, use persistent_memory.
Read a specific memory file. Returns at most 500 lines by default (hard cap 2000). The output starts with a metadata header showing `lines X-Y/total | N bytes`; when truncated, the trailer tells you the exact `from=` to pass next call to continue. Use after memory_search to read full context around a search hit, and page through large files instead of asking for one giant blob.
Search project memory for relevant information. Use this before answering questions about prior work, decisions, dates, people, preferences, or todos.
Edit a file in the SEARCHABLE memory store (memory/*.md, indexed for memory_search / memory_get). Supports append (default), overwrite, search-and-replace, and delete. Only memory/*.md files are allowed. This is NOT the always-in-prompt MEMORY.md — to edit the global/project MEMORY.md snapshot, use persistent_memory.
Read or update a persistent MEMORY.md file. (This is the ALWAYS-in-system-prompt memory; for the separate searchable memory/*.md store use memory_edit / memory_search.) Global scope (`~/.omux/MEMORY.md`) is loaded into your system prompt under {{memory}} ONCE per session and is intentionally NOT hot-reloaded after writes — this keeps the system prompt byte-stable for prompt-cache hits. The {{memory}} snapshot is refreshed only at /clear, /compact, or /reset. So a successful `update` writes to disk immediately (authoritative), but your in-prompt view stays as it was at session start; rely on this tool's return value (and on `read` calls) to confirm effects, not on the system prompt changing. Project scope (`<project_dir>/.omux/MEMORY.md`) is NEVER in your system prompt — it's surfaced to you only when you `create_agent` against that project, so you can decide what to forward to the sub-agent. Use this when the user asks you to remember/forget something, or when you need to review current memories. When scope is 'project', you MUST pass project_dir (absolute path to the project root) — omux runs as a global service, so the agent owns the choice of which project receives the write.
Read the full instructions of a skill by name. Use this when you need detailed guidance on how to use a specific skill (e.g., command usage, workflow, tips).
Respond to an agent waiting for input. Only callable when the agent has an active task in waiting_input status. Returns immediately — you will receive a callback when the agent settles again. The `value` grammar is STRICT (malformed directives are rejected with an explanatory error — do not invent other forms): • `Enter` — press Enter (confirm current selection). Case-sensitive. • `Escape` — press Escape. Case-sensitive. • `arrow:up` | `arrow:down` | `arrow:up:N` | `arrow:down:N` — press Up/Down N times (N a positive integer, default 1) then Enter. Direction MUST be exactly `up` or `down`. • `keys:<K1>,<K2>,...` — send a sequence of named keys (e.g. `keys:Down,Enter`). Each K must be a known key name (Enter, Escape, Up, Down, Left, Right, Tab, Space, Backspace, …), a single character, or a tmux key token like `C-c`, `S-Tab`, `F5`. • `y` / `yes` / `n` / `no` — confirm/deny a genuine y/n or permission prompt (falls back to literal text on a numbered menu). • anything else — sent as literal text then Enter (including menu option numbers like `2`). If agent_id is omitted, routes to the most recently used agent.
Send an instruction prompt to the coding agent. Returns immediately with a task_id. The agent executes asynchronously — you will receive a callback message when the agent finishes, encounters an error, or needs input. If the target agent is busy, returns the current task info and recent agent logs instead. If agent_id is omitted, routes to the most recently used agent.
Block until all specified agents have settled (completed their current tasks or encountered errors). Returns a summary of each agent's final status. Useful for synchronizing multi-agent workflows.
Parameter constraints not fully specified. E.g., agent_id accepts 'alphanumeric + hyphens, max 30 chars' but no enum or pattern validation shown. memory_search minScore is 0-1 but no guidance on typical values.
persistent_memory parameter 'section' enum is incomplete, only 'user_profile' and 'project_conventions' shown, but description hints at more sections. Ambiguous for LLM.