# Tool reference

> Every built-in Fermix tool with its parameters, policy class, and category, grouped by function.

This page lists the built-in tools the Fermix agent can use, with the inputs each one takes. Fermix exposes its built-in capability set (its tools) through the same registry that backs MCP tools (tools from external servers, via the Model Context Protocol) and plugin integrations. Almost every tool shown here is always available when registered; users do not install or remove them (the one exception, `computer_use`, is noted below). Skills are a separate layer: they wrap a subset of tools inside their own allowed-tool boundary (a skill can only use the tools it is granted) and are managed with `skill_create`, `skill_reload`, `skill_list`, `skill_run`, and `skill_view`. See [capabilities and tools](/docs/capabilities-and-tools), [skills](/docs/skills), and [sandbox](/docs/sandbox) for policy and trust details.

The table below lists every built-in tool. Most ship unconditionally. `computer_use` is the exception: it is **experimental and off by default**. It drives the host desktop through a separate native helper program (the "computer-use helper," a small binary Fermix downloads and verifies), and it only becomes available to the model once an operator explicitly enables it and the helper is installed. Detailed parameter tables follow, grouped by category.

| Tool | Category | Policy | Description |
|------|----------|--------|-------------|
| `shell` | system | exec | Run a shell command |
| `file_read` | filesystem | read\_only | Read a text file |
| `file_write` | filesystem | read\_write | Write a text file |
| `file_edit` | filesystem | read\_write | Replace an exact string span in a file |
| `request_directory_access` | system | external\_api | Ask the owner to approve sandbox access to a directory (attended operator turns only) |
| `glob_search` | search | read\_only | Find files by glob pattern |
| `content_search` | search | read\_only | Regex-search file contents |
| `git_read` | git | read\_only | Inspect git history, status, diffs |
| `git_write` | git | read\_write | Stage, commit, checkout, pull (no push) |
| `web_fetch` | web | network | Fetch a public HTTP(S) URL |
| `web_search` | web | network | Search the web (DuckDuckGo by default; configurable backend) |
| `browser` | web | network | Drive a supervised local Chrome/Chromium browser |
| `computer_use` | computer | gui\_control | Drive the host desktop by screenshot and mouse/keyboard (experimental; off by default) |
| `subagents` | delegation | external\_api | Fan out work to temporary subagents |
| `skill_create` | skills | read\_write | Scaffold a new local skill |
| `skill_reload` | skills | read\_write | Reload skills from disk without a restart |
| `skill_list` | skills | read\_only | List installed skills |
| `skill_run` | skills | exec | Run an installed skill by name |
| `skill_view` | skills | exec | Show a skill's instructions and metadata |
| `model_routing_config` | config | read\_write | Read or update model-routing config |
| `tool_help` | meta | read\_only | Show docs for a registered capability |
| `memory_store` | memory | read\_write | Persist a keyed memory entry |
| `memory_recall` | memory | read\_only | Query stored memories |
| `memory_sources_list` | memory | read\_only | List configured memory sources |
| `schedule_job` | jobs | read\_write | Create a durable scheduled job |
| `list_jobs` | jobs | read\_only | List scheduled jobs |
| `update_job` | jobs | read\_write | Edit a scheduled job in place |
| `pause_job` | jobs | read\_write | Pause a scheduled job |
| `resume_job` | jobs | read\_write | Resume a paused scheduled job |
| `remove_job` | jobs | read\_write | Remove a scheduled job |
| `run_job_now` | jobs | read\_write | Run a scheduled job immediately, out of band |
| `list_job_runs` | jobs | read\_only | List a scheduled job's run history |
| `get_job_run` | jobs | read\_only | Fetch one scheduled-job run in full |
| `generate_image` | media | external\_api | Create or edit a raster image from a prompt |
| `send_attachment` | channel | read\_only | Send a local file through the active channel |
| `react` | channel | read\_only | React to the user's message with a single emoji instead of a text reply |
| `tool_search` | meta | read\_only | Keyword search over deferred plugin/MCP tool schemas (registered when tool-schema deferral is on) |
| `tool_describe` | meta | read\_only | Return the full schema for one deferred tool (registered when tool-schema deferral is on) |
| `tool_call` | meta | read\_only | Invoke a deferred tool by name (registered when tool-schema deferral is on) |

---

## Filesystem

### `shell`

Run a shell command. The sandbox hardline blocklist (a built-in list of obviously dangerous commands that are always refused) runs before execution. The working directory and environment are controlled by the sandbox. Processes run in a group and are killed on timeout.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `command` | string | yes | Shell command to execute |
| `working_dir` | string | no | Working directory (defaults to the sandbox mode's working directory) |
| `timeout_ms` | integer | no | Timeout in milliseconds (default 30 000) |

### `file_read`

Read a UTF-8 text file. Path is validated through `Sandbox.read_path/3`; protected paths and paths outside the sandbox roots are rejected.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `path` | string | yes | Absolute path to the file |
| `offset` | integer | no | 1-based starting line |
| `limit` | integer | no | Number of lines to return |

### `file_write`

Write a UTF-8 text file, creating intermediate directories as needed. Path is validated through `Sandbox.write_path/3`.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `path` | string | yes | Destination path |
| `content` | string | yes | File content to write |
| `mkdir` | boolean | no | Create parent directories if they don't exist (default true) |

### `file_edit`

Replace exactly one unique string anchor in an existing file, via an atomic temp-file-and-rename that preserves the file's mode. Fails if `old_string` is missing from the file, or if it appears more than once (make the anchor longer until it is unique).

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `path` | string | yes | Path to the file |
| `old_string` | string | yes | Exact, unique text to replace |
| `new_string` | string | yes | Replacement text |

### `request_directory_access`

Ask the owner, in chat, to approve access to a directory the sandbox denies. It is for the case where a filesystem operation was rejected for being outside the sandbox roots and the task genuinely needs that directory. The tool is only offered on attended, top-level operator turns — never to guests, subagents, or scheduled and unattended runs. It refuses up front to request roots the sandbox would never grant (your whole home directory, the Fermix home, `~/.ssh`, OS roots), so the owner is never prompted for something that would be rejected anyway. The owner sees the canonical path, the stated reason, and the exact config change, and approves with a single-use `/confirm TOKEN` that expires in 60 seconds. On Telegram and Discord the prompt also carries a one-tap **Approve** button; it sends the identical confirmation and rides the same single-use, time-limited, origin-bound, owner-only path. On approval the grant persists to `[sandbox] allowed_roots`, and on chat channels the original request resumes automatically.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `path` | string | yes | The directory to request access to (the path the sandbox denied) |
| `reason` | string | yes | Short, honest reason the task needs this directory, shown to the owner |

---

## Search

### `glob_search`

Find files matching a glob pattern within the sandbox roots. Results are bounded by `max_results`.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `pattern` | string | yes | Glob pattern, e.g. `"src/**/*.ex"` |
| `path` | string | no | Root directory to search from (defaults to the current directory) |
| `max_results` | integer | no | Upper bound on returned paths (default 200) |

### `content_search`

Search file contents for text (or, with `regex` set, a regular expression) without shelling out to `grep`. Binary files are skipped. Bounded by a deadline and a result cap.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `pattern` | string | yes | Text to find, or a regular expression when `regex` is true |
| `path` | string | no | Restrict search to this file or directory (defaults to the current directory) |
| `regex` | boolean | no | Interpret `pattern` as a regular expression |
| `max_results` | integer | no | Upper bound on matches (default 200) |
| `timeout_ms` | integer | no | Search deadline in milliseconds (default 30 000) |

---

## Git

### `git_read`

Run safe, read-only git subcommands: `status`, `log`, `diff`, `branch`, `show`. An argument denylist blocks `--no-index`, `--git-dir`, `--work-tree`, `--exec-path`, and absolute-path arguments.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `repo` | string | no | Repository directory (defaults to the current directory) |
| `command` | string | yes | Git subcommand (`status`, `log`, `diff`, `branch`, `show`) |
| `args` | array of strings | no | Flags and arguments for the subcommand |

### `git_write`

Run mutating git subcommands: `add`, `commit`, `checkout`, and `pull`. Other subcommands (including `branch`, `merge`, and `push`) are refused. Like `git_read`, it enforces a prefix-aware argument denylist that blocks `--no-index`, `--git-dir`, `--work-tree`, `--exec-path`, `--upload-pack`, `--receive-pack`, and absolute-path and output-redirection flags, so an arg like `git pull --upload-pack=<cmd>` cannot inject a command.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `repo` | string | no | Repository directory (defaults to the current directory) |
| `command` | string | yes | Git subcommand (`add`, `commit`, `checkout`, `pull`) |
| `args` | array of strings | no | Flags and arguments |

---

## Web

### `web_fetch`

Fetch a public HTTP(S) URL and return the body as markdown-light text. When the endpoint serves JSON, the JSON body is returned verbatim instead of being rendered as markdown-light text. A network guard blocks private and local IP ranges (so the tool cannot reach machines on your internal network) and pins the connection to the validated IP. Limits: 1 MB body cap, 5 redirects, 15 s receive timeout, 3 s connect timeout.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `url` | string | yes | Public HTTP(S) URL to fetch |

### `web_search`

Search the public web. The default backend is keyless DuckDuckGo. Configurable alternatives (Brave, DuckDuckGo, Exa, Firecrawl, Parallel, Perplexity, Tavily) are selected via `[fermix_core.tools.web_search]` in config, each with its own API-key entry. Up to 10 results are returned. If a configured non-DuckDuckGo backend becomes *unavailable* — a provider error (including out-of-credits / HTTP 402), a rate limit, a transport/network failure, or a changed-response parser error — the tool degrades once to DuckDuckGo loudly (a warning plus `degraded`/`primary_backend`/`fallback_reason` in the trace) so the broken backend stays visible. A missing or rejected API key (auth failure) and a bad query deliberately do **not** degrade — they surface so you fix them. Empty results do not trigger degradation either.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `query` | string | yes | Search query (max 1024 characters) |

### `browser`

Drive a supervised local Chrome or Chromium browser (over the Chrome DevTools Protocol) for JavaScript-rendered and interactive pages. Fermix manages the browser's lifecycle itself — launching it, capping how many tabs stay open, and closing idle profiles. This tool controls a browser process only; it does not control desktop applications or the wider GUI (that is `computer_use`). Each call runs one `action`. You target page elements by the `ref` handles returned in a `snapshot` (an accessibility-tree view of the page), not by CSS selectors. The `screenshot` action returns the captured page as an image the model can see, not just a saved file path.

The `action` names the operation: session control (`start`, `stop`, `status`, `doctor`), tabs and navigation (`open`, `navigate`, `tabs`, `focus`, `close`), reading (`snapshot`, `screenshot`, `pdf`, `console`), interacting (`act`), and page state (`dialog`, `cookies`, `storage`, `upload`, `download`). Most interaction goes through `act`, whose `kind` selects what to do.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `action` | string | yes | Browser action to run (see above) |
| `url` | string | context-dependent | URL for `open` or `navigate` |
| `kind` | string | context-dependent | For `act`: `click`, `fill` (replace the field value), `type` (append), `submit`, `press`, `hover`, `get`, `wait`, or `click_coords` |
| `ref` | string | context-dependent | Element handle from the latest `snapshot` |
| `text` | string | context-dependent | Text to type or fill, wait target, or dialog prompt input |
| `field` | string | context-dependent | Field name for `get` and storage actions |
| `value` | string | context-dependent | Value for storage writes |
| `x`, `y` | integer | context-dependent | Coordinates for the `click_coords` kind |
| `full_page` | boolean | no | For `screenshot`: capture the whole page |
| `format` | string | no | Screenshot format: `png` or `jpeg` |
| `quality` | integer | no | JPEG screenshot quality, 1–100 |
| `interactive`, `compact`, `depth`, `include_urls` | — | no | `snapshot` shaping options |
| `profile` | string | no | Browser profile name (defaults to the configured profile) |
| `timeout_ms` | integer | no | Per-action timeout in milliseconds |

---

## Agent and skills

### `subagents`

Fan out independent work to one or more temporary subagents (short-lived helper agents the main agent spins off) running concurrently. Each subagent runs at the parent turn's trust level but with `read_write` and `gui_control` policy classes removed: workers can read, search, browse the web, use MCP/plugin tools, and run skills, but cannot directly change local Fermix state and cannot drive the desktop. The caller must synthesize the returned results. `subagents` is main-agent-only; calling it from inside a subagent is rejected.

Default concurrency cap: 4 (regular mode), 12 (`/ultra` mode). Default per-subagent timeout: 300 s (max 900 s). Default task cap: 10 per call (50 in `/ultra` mode).

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `tasks` | array | yes | List of task objects, each with `id` (string) and `task` (string goal); optional `context` string |
| `shared_context` | string | no | Context passed to every subagent |
| `max_concurrency` | integer | no | Max concurrently running subagents (default 4, max 8 in regular mode) |
| `timeout_seconds` | integer | no | Per-subagent wall-clock timeout (default 300, max 900) |
| `result_format` | string | no | `concise`, `detailed`, or `structured` (default) |
| `model` | string | no | Override model for all subagents in this call |
| `provider` | string | no | Provider for `model`; inferred from the slug when omitted |
| `reasoning_effort` | string | no | Thinking level for the subagents in this call |

### `skill_create`

Scaffold a new local skill at `~/.fermix/skills/<name>/SKILL.md` (frontmatter plus a starter `evals/evals.json`). The scaffold starts with an empty allowed-tool list; you then write the skill's instructions into the `SKILL.md` body on disk, grant it tools in the frontmatter, and pick them up with `skill_reload`. Refuses a name whose directory already exists. See [skills](/docs/skills) for the full authoring workflow.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | yes | Skill name (used as the directory name) |
| `description` | string | yes | Short description of what the skill does |

### `skill_reload`

Re-scan the skill directories and refresh the running agent's skills without restarting the daemon. Use after creating or editing a `SKILL.md` on disk, or after installing a plugin that ships skills, so the new or changed skill becomes loadable in the session. Returns what changed: added, removed, and changed names, plus any load errors.

No parameters.

### `skill_list`

List installed skills available to run via `skill_run`. Returns names and descriptions from the skill registry (discovers skills from `priv/skills`, `~/.fermix/skills`, and plugin roots).

No required parameters.

### `skill_run`

Run an installed skill by name. The run executes inside the skill's allowed-tool confinement.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | yes | Skill name as returned by `skill_list` |
| `task` | string | yes | Work request to pass to the skill |
| `context` | string | no | Optional parent context for the skill |

### `skill_view`

Show an installed skill's system prompt, allowed tools, and metadata.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | yes | Skill name |

---

## Memory

### `memory_store`

Store a fact to the agent's long-term memory, keyed and scoped to the current conversation. Fermix's background memory review later consolidates stored facts into the durable user and work profiles it injects into the prompt (see [memory](/docs/memory)).

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `key` | string | yes | Unique key for this memory (e.g. `user_timezone`, `project_name`) |
| `value` | string | yes | The value to store |

### `memory_recall`

Recall a memory by exact key, or run a keyword (full-text) search over stored memories and, optionally, conversation history. With no arguments it returns all of the current conversation's memories.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `key` | string | no | Exact key to look up; omit it to return all of the conversation's memories |
| `search` | string | no | Keyword or phrase to search for |
| `scope` | string | no | Search scope: `current` (default), `owner`, or `all` |
| `source` | string | no | What to search: `memories` (default), `history`, or `all` |

### `memory_sources_list`

List configured memory sources, including scheduled jobs that back memory rows. Optional filters: `status` (string — filter by source status) and `source_type` (string — filter by source type).

---

## Scheduled jobs

See [scheduled jobs](/docs/scheduled-jobs) for delivery configuration and job lifecycle.

### `schedule_job`

Create a durable scheduled job. The model can narrow `allowed_tools` but cannot widen the capability policy class beyond the caller's trust level. Pinned `provider`/`model` must be set together.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | yes | Human-readable job name |
| `schedule` | string | yes | Interval (`every 15 minutes`), 5-field cron (`0 8 * * *`), or ISO 8601 UTC timestamp for a one-off run |
| `task` | string | yes | Work instructions for the future run; bake in any values the run needs (location, account, etc.) |
| `description` | string | no | Short description for the source catalog |
| `timezone` | string | no | IANA timezone label stored with the job |
| `expires_at` | string | no | ISO 8601 UTC datetime; Fermix marks the job expired when this is reached |
| `allowed_tools` | array of strings | no | Narrowing list of tool names; must be a subset of the caller's available tools |
| `skill_name` | string | no | Bind the run to an existing skill (confinement is intersected, never widened) |
| `provider` | string | no | Pin runs to a provider (must pair with `model`) |
| `model` | string | no | Pin runs to a model (must pair with `provider`) |
| `timeout_seconds` | integer | no | Wall-clock timeout for each run |
| `inactivity_timeout_seconds` | integer | no | Timeout when the provider/tool loop stops making progress |
| `delivery_mode` | string | no | `none`, `origin`, `channel`, or `local` |
| `delivery_target` | object | no | Delivery target for `channel` mode |

### `list_jobs`

List existing scheduled jobs. No required parameters.

### `update_job`

Edit a scheduled job's task instructions, schedule, description, skill binding, model pin, or delivery target in place, without removing and recreating it.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `job_id` | string | yes | Job id to edit |
| `task` | string | no | Replacement work instructions |
| `schedule` | string | no | Replacement schedule expression |
| `description` | string | no | Replacement short description |
| `skill_name` | string | no | Rebind to an existing skill (rejected if unknown) |
| `provider` | string | no | New provider pin (must pair with `model`) |
| `model` | string | no | New model pin (must pair with `provider`) |
| `clear_route_pin` | boolean | no | Un-pin the job's provider/model back to default routing; mutually exclusive with `provider`/`model` (set those to re-pin instead) |
| `delivery_mode` | string | no | `none`, `origin`, `channel`, or `local` |
| `delivery_target` | object | no | Replacement delivery target for `channel` mode |

### `pause_job`

Pause a running scheduled job by id.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `job_id` | string | yes | Job id to pause |

### `resume_job`

Resume a paused scheduled job by id.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `job_id` | string | yes | Job id to resume |

### `remove_job`

Remove a scheduled job permanently by id.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `job_id` | string | yes | Job id to remove |

### `run_job_now`

Run a scheduled job immediately, out of band, without waiting for its next scheduled time. The run executes through the normal scheduled-job runner (same isolation, delivery, and confinement) and the job's timed cadence is left unchanged. Use it to test a job or satisfy an on-demand request.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `job_id` | string | yes | Scheduled job id to run now |

### `list_job_runs`

List the execution history of a scheduled job: each run's status, trigger, timing, final response, and any error. Use it to confirm a job has been firing and to read what its runs produced.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `job_id` | string | yes | Scheduled job id whose runs to list |
| `status` | string | no | Filter by status: `queued`, `running`, `ok`, or `error` |
| `limit` | integer | no | Maximum runs to return, newest first (default 20, max 100) |

### `get_job_run`

Fetch one scheduled-job run in full: status, trigger, timing, the prompt snapshot it executed, token usage, output reference, final response, and any error. Use it to inspect a specific run found via `list_job_runs`.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `run_id` | string | yes | Job run id to fetch |

---

## Media

### `generate_image`

Create or edit a raster image (photo, illustration, render) from a text prompt. The result is written to the sandbox `media/` directory and sent to the current chat automatically (file-only when there is no active channel, such as in a subagent or scheduled job). Not for diagrams, charts, code assets, or live data. The backend is set by `[fermix_core.tools.generate_image] backend` in config and must be one of `openai`, `openai_codex`, `xai`, or `google`; image generation must be configured (`fermix setup`) before this tool can run. `openai_codex` runs on a connected ChatGPT/Codex login instead of an image API key — billed to that subscription. It is opt-in and fails loudly if the login is missing or not entitled; it never silently falls back to another backend. It can generate and edit, but does not support `mask`. Editing references a source image by sandbox path or `inbound:last` (the image just sent in chat), and the `edit` operation and `mask` field are gated against the chosen backend's declared capabilities and rejected when unsupported.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `prompt` | string | yes | What to create, or for an edit, how to change the source image |
| `operation` | string | no | `generate` a new image (default) or `edit` an existing one |
| `input_image` | string | no | For `edit` only: sandbox path to the source image, or `inbound:last` / `inbound:N` for an image sent in this turn's chat |
| `mask` | string | no | Sandbox path to a PNG-alpha mask (OpenAI backend only); only its transparent regions are edited |
| `size` | string | no | Output size (e.g. `1024x1024`); defaults to the configured size |
| `model` | string | no | Model override for this call |

---

## Computer use

### `computer_use`

**Experimental and off by default.** This is the most dangerous capability Fermix has — it controls your real, logged-in desktop, with no undo. It is enabled from the setup Plugins page (the "Computer Use" card) on **Apple Silicon (M-series) macOS and Linux x86_64** only; Intel Macs are not supported. Enabling downloads the native computer-use helper (fetched from its release and verified against a checksum baked into Fermix) and turns the feature on; the change applies on the next daemon restart. The tool is registered for the model only once it is both **enabled and the helper is installed**. Operating-system permission (macOS Screen Recording / Accessibility, or an X11 display on Linux) is a separate concern that `fermix doctor` reports on — it is not part of the enable gate.

Drive the **host desktop** GUI by screenshot and mouse/keyboard, one action per call. Take a `screenshot` to see the screen, then act on it (click, type, key, scroll, drag) using pixel coordinates from the latest screenshot. Every action that changes something returns a fresh screenshot the model can see, so it can verify the result and retry a missed click. For a small or dense target, the model can zoom: a `screenshot` with a `region` returns a magnified crop, and passing the same `region` on the follow-up click/drag maps the coordinates read in the crop back to the real pixel. On macOS a few read-only helpers make targeting more reliable: `inspect` reports the role and label of the on-screen element under a point (so the model can confirm it is about to click the right control before a consequential action), and `elements` lists the clickable elements each with a click point. `wait_for_change` blocks until the screen updates instead of polling with repeated screenshots, and `paste` enters long or unicode text quickly through the clipboard. There is no "browser mode" — web automation is the separate `browser` tool.

The tool is operator-only and is never delegated to subagents. It also refuses to start from an unattended origin: a host desktop session can only begin from an interactive chat, `fermix ask`, or the voice companion — scheduled and cron runs fail closed.

Its `:gui_control` policy class gets no sandbox protection; safety comes instead from an **access posture derived directly from the sandbox mode** (there is no separate computer-use knob). `strict` is look-only and refuses every action that changes something; `standard` acts directly but the agent confirms with the owner before anything irreversible; `open` acts on its own but still confirms a truly catastrophic action. The live posture is folded into the `action` parameter description each turn.

You and the agent share one cursor, so there is a second, softer check on top of the posture. Before any action that would move the pointer or type — clicking, dragging, scrolling, moving the mouse, typing, pressing a key, or pasting — Fermix checks how long the machine has been idle. If you are actively using it, the agent waits a few seconds for a gap, then either takes its turn or holds the action back and tells you it stepped aside. `mouse_move` counts as disturbing here even though the table below lists it as read-only: it changes nothing on screen, but it does move your pointer. Idle detection is macOS-only. Where it is unavailable the action proceeds, so this is a courtesy that keeps the agent from fighting you for the cursor, not a safety boundary; it is configured with `courtesy` and `courtesy_idle_ms` in `[fermix_core.computer_use]` (see [configuration](/docs/configuration)).

To take the machine back yourself, `/pause` hands the cursor and keyboard back to you. The computer-use session stays alive and refuses further actions until you `/resume` — unlike `/stop`, which tears the session down. Both are owner-only, and `/resume` only lets the agent act again; it does not restart the task on its own.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `action` | string | yes | GUI action. Read-only: `screenshot`, `inspect`, `elements`, `wait_for_change`, `mouse_move`, `wait`. Mutating: `left_click`, `right_click`, `double_click`, `left_click_drag`, `scroll`, `type`, `paste`, `key` |
| `x` | integer | context-dependent | X pixel for click/move/scroll/inspect (screenshot space) |
| `y` | integer | context-dependent | Y pixel for click/move/scroll/inspect (screenshot space) |
| `display` | integer | no | Display index; defaults to the configured display |
| `modifiers` | array of strings | no | Held modifier keys for a click (e.g. `["cmd"]`) |
| `from` | object | context-dependent | Drag start point (`{x, y}`) |
| `to` | object | context-dependent | Drag end point (`{x, y}`) |
| `direction` | string | context-dependent | Scroll direction: `up`, `down`, `left`, `right` |
| `amount` | integer | no | Scroll amount (positive) |
| `text` | string | context-dependent | Text to type or paste (for `action=type` / `action=paste`) |
| `chord` | string | context-dependent | Key chord for `action=key`, e.g. `"ctrl+s"` (supports `f1`–`f12`) |
| `ms` | integer | context-dependent | Milliseconds to wait (for `action=wait`) |
| `timeout_ms` | integer | no | Max ms to wait for a change (for `action=wait_for_change`; default 10 000) |
| `poll_ms` | integer | no | Check interval in ms (for `action=wait_for_change`; default 250) |
| `region` | object | no | Zoom rectangle `{x, y, w, h}` in the current screenshot's pixel space; see above |

---

## Channel

### `send_attachment`

Send a local file through the active channel reply port. URL paths are refused; send links as text instead.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `path` | string | yes | Local file path to send |
| `kind` | string | no | `image`, `document`, `audio`, `video`, or `voice` (default `document`) |
| `caption` | string | no | Optional caption |
| `filename` | string | no | Override the filename shown to the recipient |
| `mime_type` | string | no | Override the detected MIME type |

### `react`

React to the user's current message with one fitting emoji through the active channel, instead of sending a text bubble — for pure acknowledgements ("ok", "thanks", 👍). The tool is only offered when the active channel supports message reactions; on a channel without them the model simply sends a short text acknowledgement instead. On a channel with a restricted emoji set, the `emoji` parameter is narrowed to exactly that channel's allowed emojis, so the model's choice is always valid. A delivered reaction with no accompanying text ends the turn without a further model call.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `emoji` | string | yes | A single emoji to react with, chosen to fit the message |

---

## Meta

### `model_routing_config`

Read or change which model delegated **sub-agents** run on — never the main agent's own model. It reads and writes exactly three keys in `[fermix_core.routing]`: `subagent_provider`, `subagent_model`, and `subagent_reasoning_effort` (for example, to run sub-agents on a smaller, cheaper model). Writes are validated and applied live — no daemon restart needed. (The parallel `cron_*` keys for scheduled jobs are read here but can only be set by editing `config.toml`.)

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `action` | string | yes | `read`, `set`, or `delete` |
| `key` | string | context-dependent | For `set`/`delete`: `subagent_provider`, `subagent_model`, or `subagent_reasoning_effort` |
| `value` | string | context-dependent | New value, for `set` |

### `tool_help`

Return the full documentation for one registered capability as visible to the current trust level and tool filters. Useful for the agent to inspect its own tool schema at runtime.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | yes | Tool name to describe |

---

## Tool-schema deferral bridges

When tool-schema deferral is enabled (the default; disable with `[fermix_core.tools.tool_search] enabled = false`), the full definitions of plugin and MCP tools are not sent to the model up front, to save room in the prompt. Tool names remain listed in the runtime prompt. Three bridge tools are registered in their place so the agent can look up and invoke these deferred tools on demand.

### `tool_search`

Keyword search over the deferred plugin and MCP tool catalog. Use it when you know roughly what you need but not the exact tool name.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `query` | string | yes | Keywords describing the capability you need |
| `limit` | integer | no | Maximum results to return (default 5, max 20) |

### `tool_describe`

Return the full schema for one deferred tool by name. Use after `tool_search` to read a tool's parameters before calling it.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | yes | Deferred tool name to describe |

### `tool_call`

Invoke a deferred tool by name. The loop unwraps the call so traces and policy enforcement see the real tool name, not `tool_call`. Direct calls to the real tool name also work when the schema has been fetched via `tool_describe`.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | yes | Deferred tool name to invoke |
| `arguments` | object | yes | Arguments object matching the tool's schema |