Built-in Tools

Built-in tools are the tool set provided by Mirri Code alongside its core engine — no MCP server installation required. The Agent automatically selects and calls these tools based on the task at hand during each conversation; users can inspect the details of each tool call through the approval interface.

Compared to MCP tools, built-in tools are managed directly by the runtime, their lifecycle is bound to the session, and no external process is required. Both follow the same unified approval mechanism: read-only tools (such as Read, Grep, Glob) are automatically allowed by default, while write and execution tools (such as Write, Edit, Bash) require user approval by default. In YOLO mode, approval for regular tool calls is skipped; Plan mode exit approval is not affected.

File Tools

File tools handle reading, writing, and searching the local filesystem — the foundation for code analysis and modification tasks.

Tool	Default Approval	Description
Read	Auto-allow	Read a text file's contents
Write	Requires approval	Create or overwrite a file
Edit	Requires approval	Precise string replacement
Grep	Auto-allow	Full-text search powered by ripgrep
Glob	Auto-allow	Find files by glob pattern
ReadMediaFile	Auto-allow	Read an image or video file

Read accepts a file path (path) plus optional line_offset (starting line number; negative values count from the end) and n_lines (maximum number of lines to read). Returns at most 1000 lines or 100 KB per call; content beyond that limit is accompanied by a truncation notice. If the file is an image or video, the tool suggests using ReadMediaFile instead.

Write accepts path, content, and an optional mode (overwrite or append; defaults to overwrite). Missing parent directories are created automatically; append mode appends content to the end of the file without automatically adding a newline.

Edit accepts path, old_string (the exact text to replace), and new_string (the replacement text). By default it replaces only one unique match; if the same content appears multiple times in the file, the tool returns an error and suggests using replace_all: true. old_string and new_string must not be identical.

Grep invokes ripgrep to search file contents, supporting regular expressions (pattern), a search path (path), file type filtering (type, e.g., ts, py), glob filtering (glob), and output mode (output_mode: files / content / count; defaults to files). content mode supports context lines (-A, -B, -C), case-insensitive matching (-i), line numbers (-n, default true), and multiline matching (multiline). All modes support offset + head_limit pagination; head_limit defaults to 250 and 0 means unlimited. Sensitive files such as .env files and private keys are automatically filtered out; set include_ignored=true to search files ignored by .gitignore, though sensitive files remain filtered.

Glob matches files in a specified directory (path; defaults to the working directory) by glob pattern (pattern). Results are sorted by modification time in descending order, with a maximum of 100 entries. It respects .gitignore, .ignore, and .rgignore by default; set include_ignored=true to include ignored files such as build outputs, while sensitive files remain filtered. Brace patterns such as *.{ts,tsx} are supported, and broad wildcard patterns are allowed but usually truncate at the match cap.

ReadMediaFile sends an image or video to the model as multimodal content. Accepts only path; the file size limit is 100 MB. Availability depends on the current model's vision capabilities (image_in / video_in).

Shell

Tool	Default Approval	Description
Bash	Requires approval	Execute a shell command
PowerShell	Requires approval	Execute a PowerShell command (Windows only)

Bash is the most permission-demanding tool and also the most general-purpose. Parameters:

• command (required): the shell command to execute
• cwd: working directory
• timeout: timeout in milliseconds; foreground default is 60 seconds, maximum is 5 minutes
• run_in_background: whether to run as a background task; background tasks default to a 10-minute timeout
• description: background task description; required when run_in_background=true
• disable_timeout: whether to remove the timeout limit for background tasks

Foreground mode blocks the current turn until the command completes or times out, and the UI streams stdout and stderr into the running Bash tool card while the command is still active. Background mode returns a task ID immediately and automatically notifies the Agent when the task finishes. stdin is always closed — interactive commands receive EOF immediately. A two-phase termination strategy (SIGTERM → 5-second grace period → SIGKILL) ensures reliable process cleanup after a timeout. On Windows, the Bash tool runs through Git Bash (erroring with actionable guidance when unavailable); a separate PowerShell tool covers native Windows commands.

Web Tools

Tool	Default Approval	Description
WebSearch	Auto-allow	Web search
FetchURL	Auto-allow	Fetch the content of a specified URL

WebSearch accepts query (search terms). Requires the host to provide a search implementation; when not injected, the tool does not appear in the tool list.

FetchURL accepts a single url parameter and returns the page content. For HTML pages, the host extracts the body text rather than returning the full HTML; plain text or Markdown pages are passed through directly. Also requires a host-provided implementation.

Plan Mode

Tool	Default Approval	Description
EnterPlanMode	Auto-allow	Enter Plan mode
ExitPlanMode	Auto-allow (requires user to confirm the plan)	Exit Plan mode and submit the plan

Plan mode is a constrained working state: once entered, Write and Edit are restricted to writing the current plan file only, and TaskStop is blocked entirely. All other tools (including Bash) are still governed by the current permission rules.

EnterPlanMode accepts no parameters; upon success it returns workflow guidance and the plan file path.

ExitPlanMode reads the current plan file, presents the plan to the user for approval, then exits Plan mode. The optional options parameter lets the Agent offer 1–3 alternative approaches (each with a label and description; label max 80 characters) for the user to choose from during approval. Labels must be unique and cannot use reserved words such as Approve, Reject, Reject and Exit, or Revise.

State Management

Tool	Default Approval	Description
TodoList	Auto-allow	Manage a task to-do list

TodoList maintains a visible subtask list across multi-step operations; state is stored within the Agent session. The todos parameter accepts an array where each item has a title and status (pending / in_progress / done). Omitting todos queries the current list; passing an empty array clears it.

Collaboration Tools

Collaboration tools handle inter-Agent coordination, user interaction, and Skill invocation.

Tool	Default Approval	Description
Agent	Auto-allow	Spawn a sub-Agent to execute a subtask
AgentSwarm	Auto-allow in swarm mode; otherwise requires approval	Launch item-based subagents or resume existing subagents
AskUserQuestion	Auto-allow	Ask the user a question to gather structured input
Skill	Auto-allow	Invoke a registered inline Skill

Agent delegates a subtask to a sub-Agent. Required parameters: prompt (complete task description) and description (a 3–5 word short summary). Optional parameters: subagent_type (defaults to coder), resume (ID of an existing Agent to resume; mutually exclusive with subagent_type), and run_in_background (defaults to false). Agent tasks have a fixed 30-minute timeout. In foreground mode the parent Agent waits for the sub-Agent to complete before continuing; in background mode a task ID is returned immediately and the result is automatically delivered back to the main Agent via a synthetic User message when done. When several foreground Agent calls run in the same step, the UI groups them and shows each subagent's running, waiting, completed, or failed status with elapsed time. See Agent & Sub-Agents for details.

AgentSwarm launches subagents from a shared prompt_template and an items array, resumes existing subagents through resume_agent_ids, or combines both in one call. The template must contain the placeholder; each item replaces that placeholder and launches one new subagent. Pass subagent_type to choose the profile used by every spawned subagent in the swarm, or omit it to use coder. Without resume_agent_ids, the tool requires at least 2 items; with resume_agent_ids, it can resume one or more existing subagents. By default the tool supports up to 3 subagents per call (a deliberate Rust-engine deviation from the TS engine's hardcoded 128); raise or remove the cap with the [subagent] maxSwarmItems config key, or set MIRRI_AGENT_SWARM_MAX_ITEMS (or the MIRRICODE_AGENT_SWARM_MAX_ITEMS alias) to a positive integer to override both — 0 means no limit, and an invalid value is ignored with a warning. The tool waits for all subagents to finish and returns an aggregated report. Foreground swarms show a live Agent swarm progress panel in the UI. If a model response calls AgentSwarm, that call must be the only tool call in the response; to run multiple swarms, call one AgentSwarm, wait for its result, then call the next, or combine the work into one swarm when a single template can cover it. In manual permission mode, AgentSwarm calls outside active swarm mode request approval unless a permission rule allows them; while swarm mode is active, AgentSwarm itself is auto-approved. Permission rules match AgentSwarm by tool name only — argument patterns such as AgentSwarm(swarm) are not supported. By default the tool ramps up concurrency without an upper limit (5 subagents start immediately, then 1 more every 700 ms); set MIRRICODE_AGENT_SWARM_MAX_CONCURRENCY to a positive integer to cap how many subagents run at the same time during that ramp, or leave it unset for no cap. If it is set to a value that is not a positive integer, the AgentSwarm call fails fast.

AskUserQuestion asks the user a structured multiple-choice question — useful for disambiguation or option selection. The questions parameter accepts 1–4 questions; each question requires question (ending with ?), options (2–4 choices, each with a label and description), and optional header (max 12 characters) and multi_select (defaults to false). An "Other" option is appended automatically. Setting background to true starts a background question task and returns a task ID immediately. When the host does not support interactive questioning, a failure message is returned and the Agent should ask the user directly in a text reply instead.

Skill allows the Agent to actively invoke a registered inline-type Skill. Accepts skill (the Skill name) and optional args (additional argument text). Only type = "inline" Skills can be called via this tool; Skills with disableModelInvocation: true are rejected. Maximum nesting depth is 3 levels. See Agent Skills for details.

Background Tasks

Background task tools manage tasks started via Bash, Agent, or AskUserQuestion. When a task reaches a terminal state, its status and saved output path are automatically delivered back to the Agent; use TaskOutput to check progress early.

Tool	Default Approval	Description
TaskList	Auto-allow	List background tasks
TaskOutput	Auto-allow	View the output of a background task
TaskStop	Requires approval	Stop a running background task

TaskList returns the list of background tasks. Optional parameters: active_only (defaults to true; lists only running tasks) and limit (defaults to 20; range 1–100).

TaskOutput returns the status and output of a task given its task_id. The inline preview includes at most the most recent 32 KB of content; the full log is saved to disk, and the tool also returns an output_path with a suggestion to use Read for paginated access. Optional block (defaults to false) and timeout (seconds to wait; defaults to 30; range 0–3600) parameters allow waiting for the task to complete before returning.

TaskStop accepts a task_id and optional reason (defaults to Stopped by TaskStop). Safe to call on tasks that are already in a terminal state.

Scheduled Tasks

"Do this later" has two shapes, each with its own tool:

• Timer (SetTimer) — a one-shot delayed callback inside the CURRENT session. For conversational follow-ups such as "check the CI result in 10 minutes".
• Scheduled task (CreateScheduledTask) — a routine in the task's workspace, with its own identity and run history. For daily patrols, weekly reports, deployment monitoring, and other long-lived jobs.

A timer needs no approval; every new scheduled task asks you to confirm first. Created tasks are listed, edited, paused and deleted on the Scheduled Tasks page in settings. Set MIRRICODE_DISABLE_CRON=1 to disable both tools entirely; see Environment Variables.

Tool	Default Approval	Description
SetTimer	Auto-allow	Schedule a one-shot delayed callback in the current session
CreateScheduledTask	Requires approval	Create a scheduled task in the task's workspace

SetTimer accepts two arguments: delay_minutes (how many whole minutes from now; under a minute rounds up to one) and message (the text injected into the session when it fires — write it as the instruction you want to receive then). It fires exactly once and removes itself, so nothing is left to clean up. Detection ticks every 30 seconds, so delivery may land slightly off the requested minute; if a turn is still running at that moment, the message waits for the turn to end, and missed periods coalesce into one fire.

CreateScheduledTask requires cron (a standard 5-field expression: minute hour day-of-month month day-of-week) and prompt (the instruction each run executes — shown verbatim on the approval card so you approve exactly that text). Optional: recurring (defaults to true — reschedule after every fire; false runs once), timezone (an IANA name; defaults to the host), max_fires (a cap for a recurring task; unset means unbounded), permission_mode (manual / auto / yolo, the same three modes as a new session — under manual a run that reaches an action needing approval stops and waits for you — the run record shows "Waiting for approval", and you approve or reject inside that run's session), title, model, effort, and reason (a note shown on the approval card). Every call raises one approval card that spells out, in plain language, the task name, when it runs, the workspace, the model, the permissions and the instruction — in every permission mode it needs your approval. Approving creates the task right away and the call returns its id; rejecting creates nothing, and the agent sees your reason in that call's result.

To prevent all users from firing at the same time on the hour, the scheduler applies deterministic jitter: recurring tasks are shifted forward by min(10% of the period, 15 minutes); one-time tasks that fall exactly on :00 or :30 are moved earlier by up to 90 seconds. If the scheduler misses several fire times (e.g., because the laptop was sleeping), it fires only once on wake-up — the prompt is wrapped in a <cron-fire> envelope with a coalescedCount. Recurring tasks that have been alive for more than 7 days fire one final time with stale="true" and are then automatically deleted.

The Scheduled Tasks page

Besides asking the Agent to schedule work, you can manage the workspace's tasks directly on the Scheduled Tasks page in the web settings panel.

• List: two-column cards; each card carries the title, an excerpt of the instructions, and a footer line of the repeat rule, the next run and the run count. Clicking a card opens its detail view. Status is a filter row above the list (All / Active / Paused / Failed) — cards carry no status badge and no per-card buttons.

Note: the create and edit form currently shows workspace, permission mode, model and thinking effort; the create API still accepts the legacy posture field for older clients.

• Create: four stacked blocks — the task title; the schedule (a structured picker: every hour / day / weekday / week / month / custom, no expression to write, plus an optional fire cap for recurring tasks); the prediction timeline; and the instructions each run executes. The bottom row holds four pickers side by side — workspace, permission mode, model and thinking effort — the same choices as starting a session; untouched fields follow the workspace defaults.
• Prediction timeline: "theoretical previous → next → next-next", each point labelled with its timezone. The theoretical previous run is computed, not recorded, so it is de-emphasised and marked "theoretical"; what actually ran lives in the detail view's History tab only.
• Detail: the Settings tab reuses the create form (pre-filled; the task keeps its identity and history), the History tab shows the run records. A task can be paused and resumed; runs missed while paused are not replayed.
• Run records: each run in the History tab shows what triggered it (scheduled / run now / queued follow-up), how late it started versus the plan, and its current status (including "Waiting for approval"). A run only counts as succeeded when its turn actually produced output.

Custom schedules support "every N days/weeks/months" elapsed intervals and an end date (the last day still fires); an end date that equals the first run day makes it a one-off. Actual deliveries may jitter slightly against the planned moments (up to a few minutes for recurring tasks) — both the form and the list show the ideal planned times.

Next steps

• Agent & Sub-Agents — Scheduling mechanics and context isolation for the Agent tool
• Hooks — Trigger local scripts before and after tool calls
• Slash Commands — Quick reference for built-in control commands in the input box