Tool reference

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 exceptions, computer_use and the coding-agent tools, are 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, skills, and sandbox for policy and trust details.

The table below lists every built-in tool. Most ship unconditionally; two families are conditional. computer_use 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. The coding agents tools register only when the coding harness is enabled and the matching vendor CLI is installed, and none of them is advertised to the model until the owner approves coding agents in setup (see the section below). 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)
place_search	web	network	Structured place lookup — hours, ratings, addresses, links (advertised only when the Brave key is set)
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)
codex_run	harness	exec	Run a background coding task in a repository via the Codex CLI (registered when the coding harness is enabled and the Codex CLI is installed; advertised once approved)
claude_code_run	harness	exec	Run a background coding task in a repository via the Claude Code CLI (same registration and approval gate)
codex_cloud_run	harness	exec	Submit a coding task to a Codex cloud environment (registered only when cloud_enabled = true)
list_coding_runs	harness	read_only	List coding runs, their status, and delivery state
get_coding_run	harness	read_only	Fetch one coding run’s full status, diagnostics, and delivery
cancel_coding_run	harness	read_write	Cancel an active coding run by id
stop_tracking_coding_run	harness	read_write	Stop tracking a Codex cloud run (registered only when cloud_enabled = true)
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
event_store	reminders	read_write	Store a personal date and its reminder plan (attended owner turns only)
event_list	reminders	read_only	List or search stored dates and their reminders (attended owner turns, or a scheduled job the owner created)
event_update	reminders	read_write	Edit a stored date, its plan, or its delivery channel (attended owner turns only)
event_remove	reminders	read_write	Cancel a stored date and its unsent reminders (attended owner turns only)
reminder_snooze	reminders	read_write	Defer one delivered reminder to a later time (attended owner turns only)
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. Any other subcommand is refused before git runs.

branch lists only. Arguments that would modify a ref are refused — the flags that delete, rename, copy, force, or retarget a branch (--delete, --move, --copy, --force, --set-upstream, --set-upstream-to, --unset-upstream, --edit-description), and bare operands too, because git branch <name> creates a ref with no flag at all. Since a bare operand is refused, a branch flag’s value goes in the = form: --contains=HEAD, not --contains HEAD. The check covers every spelling git accepts — an unambiguous long-flag abbreviation (--dele=x), a short flag bundled with others (-aD), and a value glued to a short flag (-uorigin/main). So “list the branches merged into main” works; “delete the old branch” is refused, and the refusal names the rule rather than the argument that tripped it.

A shared, prefix-aware argument denylist — applied to every git tool, so abbreviated and --flag=value forms are caught too — blocks --no-index, --git-dir, --work-tree, --exec-path, --output, --output-directory, --upload-pack, --receive-pack, --man-path, and --info-path. Positional arguments that point outside the repository — absolute paths, ~/…, and any path containing .. — are refused as well. Every one of these is code-enforced and fails closed: the command does not run.

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; push is refused by name, with an error saying this tool cannot push. It enforces the same shared, prefix-aware argument denylist git_read does, so an argument like git pull --upload-pack=<cmd> cannot point git at another program.

It additionally refuses any flag that makes git read a file of the caller’s choosing and fold its bytes into the repository: --file, --pathspec-from-file, and -F on commit. Only the repository path is sandbox-checked, never the arguments, so without this a commit message could be filled from a file the daemon can read and then read back out with git_read log. Every spelling is refused — -F <path>, -F<path>, a bundle such as -aF <path>, --file=<path>, the abbreviation --fil=<path>, and --pathspec-from-file=<path> — and the refusal tells the caller to pass the message inline with -m. A message that merely starts with F (-mFixed the crash) is a value, not a flag, and commits normally.

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)

When an answer draws on web_search, web_fetch, or place_search evidence, the agent is instructed to keep the exact returned URLs beside the claims they support (or in a short sources list) and never to invent or rebuild a link. This is an instruction-level contract on the model, not a deterministic rewriter.

place_search

Look up real-world places — businesses, landmarks, addresses — and get structured records back instead of web-page snippets: name, address, coordinates, weekly opening hours, rating and review count, price range, contact details, distance, categories, one thumbnail link, and a link to the place’s own page. The backend is Brave Place Search. The tool is advertised only when a Brave Search API key is configured under [fermix_core.tools.web_search] — the same key the Brave web-search backend uses, and Brave does not need to be the selected web_search backend. Without the key the tool is hidden from the model entirely, and execution re-checks the key either way. Each lookup is exactly one Brave request, billed separately from web-search calls, with no follow-up calls. Results are transient: Fermix stores no place data, and only the final answer persists as ordinary chat history. Returned links are never fetched.

Parameter	Type	Required	Description
query	string	yes	What to look for (“quiet coffee shop”, “pharmacy open now”); max 400 characters
location	string	no	Area to search, as you would say it (“SoHo, New York”, “10115”); mutually exclusive with coordinates
latitude / longitude	number	no	Explicit coordinate anchor; both must appear together
radius_meters	integer	no	Ranking bias around the coordinates (1–50000), not a hard geographic filter; valid only with coordinates
count	integer	no	Results to return, 1–10 (default 5)
country	string	no	Two-letter country code
language	string	no	Result language code
units	string	no	metric or imperial for distances

For a “near me” question the agent fills location itself from the area you named in the conversation or a coarse remembered fact (a neighborhood, city, or zip — never a street address), and asks which area to search when it knows neither; that is the agent’s instructed behavior, not a code gate, and the tool itself never reads memory. A lookup with no usable anchor refuses with a typed location_required error rather than guessing, and provider failures (bad key, rate limit, malformed response, oversized body) each surface as their own named error — the tool never falls back to web_search, another provider, or the browser.

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 primarily by the ref handles returned in a snapshot (an accessibility-tree view of the page). A CSS selector is used in exactly two places: act with kind: "get", field: "rect" returns the viewport box {x, y, width, height} of the first matching element — in the same CSS-pixel space click_coords clicks in — which is the deterministic route onto a board, map, chart, or canvas that exposes no accessibility elements (a selector that matches nothing returns a typed not_found error); and act with kind: "wait", wait_until: "element" waits for a selector or ref to appear. A ref click scrolls the element into view before reading its click box, so a target below the fold is clicked where it really is. A snapshot rebuilds the accessibility tree from the current document — it never serves the previous page after a navigation or single-page-app swap — and reports the document’s ready_state (loading, interactive, or complete), so a thin snapshot reads as a page still building, not a page with nothing on it. The screenshot action returns the captured page as an image the model can see, not just a saved file path, and its result includes the page’s device_pixel_ratio. Browser errors name their recovery: a blocked JavaScript dialog points to the dialog action, a stale ref points to taking a fresh snapshot, and an element with no rendered box (typically a visually hidden styled input, like a custom radio or checkbox) points to clicking its visible label ref or using click_coords with coordinates from get field=rect.

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
selector	string	context-dependent	CSS selector: the element to measure (get with field: "rect") or wait for (wait with wait_until: "element")
text	string	context-dependent	Text to type or fill, wait target, or dialog prompt input
field	string	context-dependent	For get: url, title, html, text, count, ready_state, or rect (viewport box of the first selector match); also the field name for storage actions
value	string	context-dependent	Value for storage writes
x, y	number	context-dependent	Coordinates for the click_coords kind, in CSS-pixel page-viewport space (what get field=rect returns) — not computer_use screen pixels, and not raw browser-screenshot pixels (those are device pixels; divide by device_pixel_ratio)
wait_until	string	context-dependent	For the wait kind: text, url, element, or load, each with its required argument; there is no plain-pause mode
key	string	context-dependent	Keyboard key for the press 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 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 — or, with file, load one of the skill’s named reference files (extra Markdown files in the skill’s references/ directory that the skill body points at). Each loaded view, body or reference, is capped at 64 KiB (65,536 bytes); an oversized file is refused, not truncated. Reference reads are confined to the skill’s own references/ directory — path traversal and symlinks are refused with typed errors.

Parameter	Type	Required	Description
name	string	yes	Skill name
file	string	no	Reference file name without its .md extension (lowercase letters, digits, underscore; max 64 characters) to load instead of the skill body

---

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).

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. The scope argument is a request, never an authorization: a scheduled job always searches its own job memory and a guest is always limited to the conversation it is in, whatever scope is named — the search succeeds, scoped down, rather than erroring.

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 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

---

Events and reminders

See reminders for reminder plans, delivery, and the boundary against scheduled jobs. Every tool in this section is offered and executable only on an attended, top-level owner turn — an interactive chat or CLI turn, or a live voice call — with one exception: event_list also runs inside a scheduled job the owner created, so a digest job can read upcoming dates. Guests, background work, delegated sub-agents, and coding-run continuations are refused with a typed error at both the advertisement and the dispatch step, tagged not_attended, and so are scheduled jobs on every tool here except event_list.

event_store

Store a personal date and the finite reminder plan Fermix will deliver for it. The tool owns the clock, the timezone, and the delivery snapshot; the model supplies a title, a kind, and one time form. With no [fermix_core.jobs] default_delivery_target set, Fermix derives the owner’s inbox from the first channel configured with an explicit owner id — Telegram, then Signal, then WhatsApp — and the call fails (no_default_target) only when there is neither a configured target nor a derivable channel. A configured target that is itself invalid fails instead of falling through to derivation, and a default_delivery_mode of none, origin, or local is refused ahead of both. It never falls back to the current chat. An ambiguous local time is refused (ambiguous_local_time) so the agent can ask which instant you meant. Storing the same date twice returns the existing event instead of a duplicate.

Parameter	Type	Required	Description
title	string	yes	Short event title, for example Sarah's birthday
kind	string	yes	One of birthday, anniversary, appointment, deadline, event, follow_up, explicit_reminder
when	object	yes	One tagged time form: {"type":"date","date":"YYYY-MM-DD"}, {"type":"datetime","date":"YYYY-MM-DD","time":"HH:MM:SS"} with an optional utc_offset when the local time is ambiguous, {"type":"relative","amount":2,"unit":"days"} (also "weeks") with an optional time, or {"type":"annual","month":9,"day":14} for a yearly date
description	string	no	Extra detail stored with the event
timezone	string	no	IANA zone, only when the owner named one; otherwise the configured personalization timezone is used
leap_day_policy	string	no	feb_28 or mar_1; required for a yearly February 29 date
reminders	array of objects	no	Explicit plan that replaces the defaults, at most 10 rules: {"type":"days_before","days":7,"at":"09:00:00"}, {"type":"duration_before","minutes":60}, or {"type":"at_time"}
no_reminders	boolean	no	Store the date with no notifications at all
followup	boolean	no	Mark the date for a follow-up check-in: after each reminder is delivered, a separate short agent turn may offer help or ask one question. The confirmation names the check-in when set

event_list

List or search stored dates: what is coming up, when a birthday falls, which reminders are planned, and whether one failed to deliver. With no window and no status it answers “what is coming up” and starts at today; history needs an explicit from/to or status. Results page with an opaque cursor passed back verbatim.

Parameter	Type	Required	Description
text	string	no	Match against title and description
kind	string	no	Restrict to one event kind
status	string	no	active (default), completed, cancelled, or any. Naming a status also drops the from-today floor, so past dates become visible
from	string	no	Earliest occurrence date, YYYY-MM-DD. Without it the list starts at today
to	string	no	Latest occurrence date, YYYY-MM-DD; at most two years after from
limit	integer	no	Rows per page (default 25, max 100)
cursor	string	no	Opaque next-page cursor from a prior call

event_update

Change a stored date: title, time, recurrence, timezone, or reminder plan. Fields left out keep their stored values, and a replacement plan replaces the stored one entirely. Reminders already delivered are immutable; only unsent ones are regenerated. Changing the date also requires owner_direction: a when with no quoted direction is refused (overwrite_unconfirmed), and a quote over 240 bytes is refused rather than trimmed (owner_direction_too_long). A reminder that is mid-send blocks the edit (delivery_in_progress) because a channel send cannot be recalled.

Parameter	Type	Required	Description
event_id	string	yes	The stored event’s id, from event_list
title	string	no	New title
description	string	no	New description
kind	string	no	New event kind
when	object	no	New time, in the same tagged forms event_store accepts
owner_direction	string	with when	The owner’s words that explicitly directed this date change, quoted near-verbatim as just the directing clause. Required whenever when is present; the call is refused without it. When the owner only restated a date under a name already stored there is nothing to quote — leave it out, and Fermix asks which event they mean instead of overwriting
timezone	string	no	New IANA zone for the event
leap_day_policy	string	no	feb_28 or mar_1
reminders	array of objects	no	Replacement reminder plan; it replaces the stored one entirely
no_reminders	boolean	no	Drop every reminder for this date
rebind_delivery_to_default	boolean	no	Re-snapshot the current configured default delivery target and regenerate unsent reminders on it. Only on the owner’s explicit request
followup	boolean	no	Set or clear the follow-up check-in for this date; changing it never requires owner_direction

event_remove

Cancel a stored date and its unsent reminders. Cancellation is soft: the delivered reminder history stays queryable. Omitting event_id is the “cancel that” path — the event behind the most recent reminder delivered into this exact conversation within the last 24 hours. With nothing delivered there the tool returns no_recent_reminder and the agent asks which date you meant, rather than guessing across conversations. The result carries the whole event, including its recurrence, so the reply can say that a yearly date took every future occurrence with it.

Parameter	Type	Required	Description
event_id	string	no	The stored event’s id, from event_list. Leave it out for “cancel that” or “stop reminding me about this”

reminder_snooze

Defer one reminder to a later time. Without reminder_id the tool resolves the reminder Fermix most recently delivered into this exact conversation within the last 24 hours, the same lookup event_remove uses. It never moves the event itself — that is event_update. One snooze is active per reminder: re-snoozing replaces the previous one, and an identical repeat changes nothing. Both time forms are capped at 90 days out.

Parameter	Type	Required	Description
snooze	object	yes	One tagged form: {"type":"duration","amount":2,"unit":"hours"} relative to now, where unit is minutes, hours, or days, or {"type":"datetime","date":"YYYY-MM-DD","time":"HH:MM:SS"} with an optional utc_offset when the local time is ambiguous
reminder_id	string	no	The reminder to defer, from event_list. Leave it out for “snooze that”
confirm_past_boundary	boolean	no	Set only after the owner confirms a reminder that would arrive at or after the event itself

---

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

Each backend carries a curated model list: the setup Media tab offers exactly these, and the first is the default used when neither [fermix_core.tools.generate_image] model nor the tool’s model argument names one.

Backend	Default model	Also selectable
openai	gpt-image-2	gpt-image-1.5
openai_codex	gpt-image-2	—
xai	grok-imagine-image-2.0	grok-imagine-image-quality
google	gemini-3.1-flash-image	gemini-3-pro-image, gemini-2.5-flash-image

The two SpaceXAI entries are distinct, separately priced models, not aliases of one another. On openai_codex the image model is fixed; the GPT-5.x model that carries the image tool is a separate config key (router_model), not a value for model.

---

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), elements lists the clickable elements each with a click point, and windows lists the open windows — front-most first, each with its bounds already shaped as a region to pass to screenshot and follow-up clicks, so on a large display the model crops to the app instead of aiming inside a downscaled full screen. A screenshot with marks: true badges the accessibility click targets with numbered marks drawn on the image and lists them; the model then acts with mark: N instead of pixel coordinates and the daemon resolves the badge’s exact point — no pixel estimation. Marks expire when the view changes; a stale or unknown mark is refused with a typed error, never guessed. 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.

Aiming mistakes are caught rather than executed, and each of these checks is code-enforced. After a zoomed look — a screenshot or elements call that carried a region — a coordinate action without that same region is refused with the exact region to re-send, never silently read in full-screen space. Coordinates plausible on both live grids (inside the on-screen region rectangle while the current view is a magnified crop) are refused with the exact conversion arithmetic; re-sending the same action with confirm_grid: true after re-reading the image executes it, and an action addressed by mark bypasses this check because its point is copied, not read off an image. A click or drag the OS did not deliver is reported in the result as not delivered instead of success, and when the action carried a region, the post-action check screenshot is of that same magnified crop — verification happens in the space the model acted in. When the macOS Accessibility permission is missing, the session detects it at start and refuses every mutating action with a typed error naming the fix (System Settings → Privacy & Security → Accessibility) while screenshots keep working — one loud refusal instead of a run of silent no-ops.

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).

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, windows, 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, from the latest coordinate source
y	integer	context-dependent	Y pixel for click/move/scroll/inspect, from the latest coordinate source
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 latest full-screen screenshot’s pixel space. On screenshot it returns a magnified crop; on elements, points in that crop’s space. Pass the same region with any follow-up action that uses coordinates from that crop or those points
confirm_grid	boolean	no	Re-send an action refused for ambiguous coordinates, after re-reading the magnified image and confirming x, y are pixels of that image
marks	boolean	no	For screenshot: badge the accessibility click targets with numbered marks and list them
mark	integer	no	Act on a numbered mark from the latest marks screenshot instead of x, y; the exact point is resolved daemon-side, and marks expire when the view changes

---

Coding agents

These tools hand repository work — reviewing changes, diagnosing and fixing bugs, implementing or refactoring features — to the Codex CLI or the Claude Code CLI installed on the machine, run inside the target repository on its live branch. The runtime prompt and fermix doctor call the same feature the coding harness. See coding agents for the full consent, authorization, environment, and delivery model.

The whole family is gated twice, and both gates are code-enforced. The tools exist only while the harness is enabled ([fermix_core.harness] enabled, default true) and the matching vendor CLI was on the daemon’s PATH at boot — installing a CLI takes effect on the next daemon restart. And none of them is advertised to the model until the owner approves coding agents once on this machine, on the setup Coding Agents tab or with [fermix_core.harness] approved = true. Until then the family is absent from the prompt and Fermix does coding work with its own file and shell tools; there is no in-chat consent prompt, and Fermix can never grant the approval itself. The tools stay dispatchable by name while unadvertised, so a run recorded earlier can still be read or cancelled; a by-name launch on an unapproved machine is refused with a typed error naming the fix. With both CLIs installed and default_vendor set, only that vendor’s run tool is advertised — the other stays callable by name. codex_cloud_run and stop_tracking_coding_run are not registered at all unless cloud_enabled = true.

Every harness tool is also authorized at execute time, before anything is written: the caller must be a live attended operator turn, or a scheduled job that names the exact tool in its persisted allowed_tools. Guests, delegated subagents, unattended runs, and voice calls are refused, each with its own typed error. Runs are background-only — there is no inline wait path: a run tool returns a run id (hr_ plus 12 lowercase hex characters) immediately, and when the run finishes the outcome re-enters the conversation on its own. At most 2 runs execute at once (default) and one per git worktree (the repository checkout); a launch past either bound is refused with a typed error.

codex_run

Run a coding task through the Codex CLI (codex exec) inside a repository. cwd and every path in add_dirs, images, and output_schema must clear the workspace sandbox first; a denied path is refused with a typed error naming the remedy (request_directory_access, or fermix grant path <dir>). Omitting sandbox sends no posture flag at all, so the run inherits the operator’s own Codex configuration — with nothing configured, codex exec defaults to read-only. danger-full-access is refused at the tool boundary: Fermix admits the run’s directories through its own sandbox but does not confine the child process at the OS level, so the vendor’s sandbox is the only confinement. Prompts up to 200 KB (default) travel as the CLI’s command-line argument; a larger prompt spills to a brief file the CLI is pointed at. On a resume, add_dirs and profile are refused, and a resumed thread inherits the sandbox policy it was started with unless sandbox is passed to change it.

Parameter	Type	Required	Description
prompt	string	yes	The coding task for Codex to carry out
cwd	string	yes	Absolute path of the repository or working directory
model	string	no	Codex model override
effort	string	no	Reasoning-effort override
sandbox	string	no	Codex sandbox mode: read-only or workspace-write. Omit to inherit the operator’s configured posture; workspace-write writes freely inside the admitted directories without prompting (danger-full-access is refused)
add_dirs	array of strings	no	Extra writable directories, each sandbox-checked and locked; refused on resume
ephemeral	boolean	no	Write no session files (the run is not resumable); conflicts with resume
profile	string	no	Named Codex profile; refused on resume
images	array of strings	no	Image file paths to attach; sandbox-read-checked
output_schema	string	no	Path to a JSON output-schema file; sandbox-read-checked
resume	string	no	Resume a prior Codex thread by id
timeout_minutes	integer	no	Wall-clock timeout in minutes (default 30, max 240)
progress	string	no	quiet (default) or milestones — throttled progress notices to the origin chat, at most one per 60 s

claude_code_run

Run a coding task through the Claude Code CLI (claude -p) inside a repository. The same sandbox admission applies to cwd, add_dirs, and append_system_prompt_file. Omitting permission_mode sends no posture flag, so the run inherits the operator’s own Claude Code settings; bypassPermissions is refused at the tool boundary for the same reason danger-full-access is on codex_run, and dangerously_skip_permissions is not a parameter the model can pass at all. bare: true skips the CLI’s OAuth and keychain login and reads ANTHROPIC_API_KEY only.

Parameter	Type	Required	Description
prompt	string	yes	The coding task for Claude Code to carry out
cwd	string	yes	Absolute path of the repository or working directory
model	string	no	Claude model override
effort	string	no	Reasoning effort: low, medium, high, xhigh, or max
permission_mode	string	no	acceptEdits, auto, manual, dontAsk, or plan. Omit to inherit the operator’s configured posture; auto runs with the least friction while keeping the sandbox (bypassPermissions is refused)
allowed_tools	array of strings	no	Tool names to allow in the run
disallowed_tools	array of strings	no	Tool names to disallow
append_system_prompt	string	no	Extra system-prompt text to append
append_system_prompt_file	string	no	Path to a file whose contents append to the system prompt; sandbox-read-checked
add_dirs	array of strings	no	Extra writable directories, each sandbox-checked and locked
max_turns	integer	no	Maximum agent turns
json_schema	string	no	JSON schema for structured output
resume	string	no	Resume a prior Claude session by id; mutually exclusive with continue
continue	boolean	no	Continue the most recent session
bare	boolean	no	Skip the OAuth/keychain login and read ANTHROPIC_API_KEY only
timeout_minutes	integer	no	Wall-clock timeout in minutes (default 30, max 240)
progress	string	no	quiet (default) or milestones — throttled progress notices to the origin chat, at most one per 60 s

codex_cloud_run

Registered only when cloud_enabled = true in [fermix_core.harness]. Submits a coding task to a pre-configured Codex cloud environment (codex cloud exec); nothing runs locally. Fermix tracks the task by bounded polling — every 120 s up to a 90-minute deadline by default; past the deadline, tracking stops and the task URL is delivered. The query rides one command-line argument under the same 200 KB cap; an oversized query is refused, never truncated. There is no timeout_minutes — the poll deadline bounds the tracking instead.

Parameter	Type	Required	Description
query	string	yes	The coding task for the Codex cloud run to carry out
env_id	string	yes	The Codex cloud environment id to run in
branch	string	no	Branch to run against (defaults to the environment’s)
attempts	integer	no	Number of vendor attempts, 1–4

list_coding_runs

List coding runs, their status, and their delivery state. Dead-lettered runs — terminal outcomes whose delivery exhausted its retries (20 attempts or 24 hours by default) — are grouped separately so the model raises them to the owner.

Parameter	Type	Required	Description
status	string	no	Status filter, e.g. running, completed, failed

get_coding_run

Fetch one coding run in full: vendor, rail (local or cloud), status and reason, working directory, resumability, delivery state and attempts, timestamps, token usage, exit code, and a diagnostics tail. result_tail carries the run’s harvested text — the deliverable when it completed, the vendor’s own error text when it failed — bounded to 4,096 bytes.

Parameter	Type	Required	Description
run_id	string	yes	The coding run id (hr_…)

cancel_coding_run

Cancel an active local coding run. The run terminalizes as cancelled and its outcome arrives as a plain message — a cancelled run never auto-continues the conversation. An unknown id and an already-finished run each return their own typed error. A Codex cloud run cannot be cancelled (the vendor exposes no cancel); the tool refuses and points to stop_tracking_coding_run.

Parameter	Type	Required	Description
run_id	string	yes	The coding run id (hr_…) to cancel

stop_tracking_coding_run

Registered only when cloud_enabled = true. Stops Fermix’s tracking of an active Codex cloud run and delivers the task URL. The vendor-side task keeps running on ChatGPT; the result never claims it stopped.

Parameter	Type	Required	Description
run_id	string	yes	The cloud coding run id (hr_…) to stop tracking

---

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. A capability outside the caller’s ceiling answers with the same “Unknown capability” error as one that does not exist, so the answer never confirms what the caller may not see.

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. Results are limited to tools the current caller could actually dispatch — a guest or a policy-narrowed run cannot discover tools outside its own ceiling.

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. A deferred tool outside the caller’s ceiling answers with the same “Unknown capability” error as one that does not exist, so the answer never confirms what the caller may not see.

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