Using the harness

Tools & permissions

The agent gets things done by calling tools. Each tool call passes through a permission gate before it runs, so nothing touches your files or shell without approval (or a standing grant).

Built-in tools

Tool	What it does	Class
`read`	Read a file's contents	read
`ls`	List a directory	read
`glob`	Match files by glob pattern	read
`grep`	Search file contents by regex	read
`web_search`	Search the web (Exa when `EXA_API_KEY` is set, else keyless DuckDuckGo)	read
`web_fetch`	Fetch and parse an HTTP URL	read
`write`	Create a new file	write
`edit`	Modify an existing file	write
`apply_patch`	Apply a multi-file patch	write
`bash`	Run a shell command (with timeout + abort). `background: true` launches it detached and returns a job handle (`MINIMA_TUI_BGJOBS=0` removes that option)	dangerous
`todowrite`	Maintain the plan/todo list — when plan verification is active, marking a step complete is gated on its verify check passing	write
`task`	Delegate subtasks to cost-routed sub-agents (see Sub-agents)	orchestration
`bgjob`	Poll, read output from, or kill a background `bash` job. Every background job is killed at session end (`MINIMA_TUI_BGJOBS=0` removes the tool)	orchestration
`checkpoint`	Mark a point in the conversation a later `rewind` can return to (`MINIMA_TUI_REWIND=0` removes the pair)	orchestration
`rewind`	Drop context back to a checkpoint when a line of work turns out to be a dead end. Only the model's context is trimmed — the session transcript in SQLite keeps every row	orchestration

Large tool results don't get truncated into oblivion: output over the inline budget spills to a content-addressed artifact file and the result carries a reference the model can read back (MINIMA_TUI_ARTIFACTS=0 opts out; see Harness features). read and grep also stamp the lines they showed, so an edit aimed at content this session never actually saw is rejected with a re-read instruction instead of writing blind.

The permission model

Approval depends on the tool's class:

read / ls prompt the first time a new directory is accessed — the working directory is not pre-approved. Granting "always" approves that directory tree, so future reads there are silent.
Write tools (write, edit, todowrite) always prompt. You can grant "always" for the tool.
Dangerous tools (bash) always prompt. You can grant "always" for the tool.
Everything else (glob, grep, web_fetch, task) prompts per call, with the same per-tool "always" grant.

When a tool needs approval, the TUI shows an inline prompt: approve once (y), approve always (a), or deny (n / Esc).

ℹ️Note

Use /perms to see the grants active in the current session.

Sub-agents (the `task` tool)

The lead agent carries one orchestration tool: task. The model calls it with a JSON array of delegations — subtasks with a required contract (objective, output_format, boundaries) plus optional depends_on, effort (light | standard | deep), difficulty, tool_allowlist, budget_usd, and isolation. The harness validates the graph (unique step ids, no dangling depends_on, no cycles) and executes it as a DAG: independent steps run concurrently (up to 4 at a time), dependents wait for their prerequisites, and a failed dependency blocks its dependents.

Each child is its own cost-routed agent: it gets a per-step model recommendation (the delegation's difficulty reaches the recommender), its own cost meter and budget slice, a tool set scoped by the delegation's allowlist and confined to its working directory, and effort-scaled turn and wall-clock caps. Children cannot delegate further — the task tool is excluded from their toolset. Sub-agent spend and decisions are recorded under their own agent id, so they demux cleanly from the lead's.

Git worktree isolation

A delegation with isolation: "workdir" runs in a temporary git worktree created from HEAD, so parallel children editing the same files can't clobber each other's writes. The worktree is removed automatically when the child finishes. If the working tree is dirty when the child spawns, its result carries a note that uncommitted changes weren't visible to it; if the worktree can't be created (e.g. not a git repo), the child falls back to the parent's directory.

Watching it live

/tree in the TUI toggles a live sub-agent panel — one row per child showing its step id, status (running / done / aborted / failure), and accumulated spend. See Interactive TUI.

Permission modes

Shift+Tab (or /mode) cycles four permission modes:

build (default) — tools prompt per the model above.
accept — edits are auto-approved; bash still prompts.
plan — read-only: write, edit, and bash are blocked, so the agent can read, search, and design without changing anything. /plan also drives the planning council, which produces a step-by-step plan with verify checks.
bypass — no prompts at all. Trusted repos only.

💡Tip

/undo restores the pre-change git-shadow checkpoint (and stacks), and /rewind jumps back to any earlier prompt — conversation, code, or both. An unwanted edit is always one command away.

Restricting tools from the CLI

In non-interactive runs (and to constrain the interactive agent), narrow the toolset with flags:

minima -t read,ls,grep     -p "trace how requests are authenticated"   # allowlist
minima -xt bash,write      -p "summarize the module"                    # denylist
minima -nt                 -p "just answer, no tools"                   # no tools at all

⚠️Warning

bash runs arbitrary commands in your shell. Grant "always" only in repos you trust, and prefer an allowlist (-t) or plan mode when you only need the agent to look, not act.

See the flags reference in CLI usage.