Reference
~2.9k tokens

Tools

Maki ships with 23 built-in tools in this reference (22 on by default, 1 opt-in via plugin options). Tools marked opt-in are off until you enable them under plugins in Configuration.

Permission is the plugin permission a tool declares. A plugin must hold it to hook the tool or to give the tool to a maki.agent session. A tool marked none reaches nothing past the conversation. A tool marked undeclared may reach anything, so it costs every permission except agent and input.

File Operations

bash

Execute a bash command. Commands run in the session's working directory (see Environment) by default.

Permission: run

ParameterTypeRequiredDefaultDescription
backgroundbooleannoRun in the background. The result arrives as a message. Prefer for slow commands whose result your next step doesn't need.
commandstringyesThe bash command to execute
descriptionstringnoWhat the command does in 3-5 words, not the command itself
timeoutintegerno120Timeout in seconds
workdirstringnocwdWorking directory

list

List directory contents. Returns entry names sorted alphabetically, directories first with a trailing /.

Permission: fs_read

ParameterTypeRequiredDescription
pathstringyesAbsolute path to the directory

read

Read a file. Returns contents with line numbers (1-indexed).

Permission: fs_read

ParameterTypeRequiredDescription
limitintegeryesMax number of lines to read. Use 0 to read until end of file (capped at 2000 lines).
offsetintegeryesLine number to start from (1-indexed). Use 1 for the first line.
pathstringyesAbsolute path to the file

write

Write content to a file, replacing existing content.

Permission: fs_write

ParameterTypeRequiredDescription
appendbooleannoAdd content to the end of the file instead of replacing it
contentstringyesThe complete file content to write
pathstringyesAbsolute path to the file

edit

Replace an exact string match in a file.

Permission: fs_write

ParameterTypeRequiredDefaultDescription
new_stringstringyesReplacement string
old_stringstringyesExact string to find (must match uniquely unless replace_all is true)
pathstringyesAbsolute path to the file
replace_allbooleannofalseReplace all occurrences

multiedit

Make multiple find-and-replace edits to a single file atomically. Prefer this over edit when making multiple changes to the same file.

Permission: fs_write

ParameterTypeRequiredDescription
editsarrayyesArray of edit operations to apply sequentially
pathstringyesAbsolute path to the file

edit_lines

Edit lines by number. Replaces lines from start to end (inclusive) with new_string. Use empty new_string to delete a range. Do not use with the batch tool.

Permission: fs_write

ParameterTypeRequiredDescription
endintegeryesLast line, inclusive
new_stringstringyesReplacement text
pathstringyesAbsolute path to the file
startintegeryesFirst line (1-indexed)

insert_lines opt-in

Insert new_string after line line, or at the top with 0. Only include new lines, never lines already in the file. Do not use with the batch tool.

Permission: fs_write

ParameterTypeRequiredDescription
lineintegeryesLine number to insert after (1-indexed). Use 0 to insert at the top.
new_stringstringyesText to insert
pathstringyesAbsolute path to the file

glob

Find files by glob pattern.

Permission: fs_read

ParameterTypeRequiredDefaultDescription
pathstringnocwdDirectory to search in
patternstringyesGlob pattern (e.g. /*.rs, src//*.ts)

grep

Search file contents using regex.

Permission: fs_read

ParameterTypeRequiredDefaultDescription
context_afterintegernoContext lines after match
context_beforeintegernoContext lines before match
includestringnoFile glob filter (e.g. *.c)
limitintegernoMax match groups to return
pathstringnocwdDirectory to search in
patternstringyesRegex pattern

index

Return a compact overview of a source file: imports, type definitions, function signatures, and structure with their line numbers surrounded by []. ~70-90% more efficient than reading the full file.

Permission: fs_read

ParameterTypeRequiredDescription
pathstringyesAbsolute path to the file

view_image

View an image file (png, jpeg, gif, webp) so you can actually see it; it is returned as vision input alongside the tool result. Use instead of read for images.

Permission: fs_read

ParameterTypeRequiredDescription
pathstringyesPath to the image file

Execution & Control

batch

Executes multiple independent tool calls concurrently to reduce round-trips.

Permission: undeclared

ParameterTypeRequiredDescription
tool_callsarrayyesArray of tool calls to execute in parallel

code_execution

Execute Python in a sandbox where every tool is an async function.

Permission: undeclared

ParameterTypeRequiredDefaultDescription
codestringyesPython code. Tools return strings, not objects, and you MUST await every call: result = await read(path='/file', offset=1, limit=0).
timeoutintegerno30Script execution timeout in seconds

question

Use this tool when you need to ask the user questions during execution. This allows you to:

  • Gather user preferences or requirements
  • Clarify ambiguous instructions
  • Get decisions on implementation choices as you work
  • Offer choices to the user about what direction to take

Permission: none

ParameterTypeRequiredDescription
questionsarrayyesList of questions to ask the user

Agent & Knowledge

task

Launch an autonomous subagent to perform tasks independently. Best combined with batch.

Permission: undeclared

ParameterTypeRequiredDescription
backgroundbooleannoRun in the background. The result arrives as a message. Default to true unless your next step needs the result. Launch all in one batch. Never sleep or poll, end your turn when idle.
descriptionstringyesShort (3-5 words) description of the task
model_tierstringnoModel tier (optional, omit to use current model, capped at current tier):
- "strong" (e.g. Opus): Deep reasoning, complex architecture, subtle bugs, most critical sections. ~5x cost of medium.
- "medium" (e.g. Sonnet): Balanced. Refactors, features, multi-file changes.
- "weak" (e.g. Haiku): Fast/cheap. Search, summarize, boilerplate, simple edits.
output_schemaobjectnoJSON Schema (object) the subagent's final result must match. When set, the result is returned as a validated JSON string.
promptstringyesDetailed task prompt for the agent
subagent_typestringnoSubagent type: "research" (read-only, default) or "general" (can modify files)
thinkinganynoThinking: off|adaptive|minimal|low|medium|high|xhigh|max|int budget. Omit to inherit parent; capped at parent.

task_stop

Stop a background task by id.

Permission: undeclared

ParameterTypeRequiredDescription
idstringyesTask id from its receipt

task_message

Message a running background subagent by id, e.g. a new fact, a changed scope or "wrap up now". It reads it after its current step. Set interrupt only when it must act now: it cuts the current step, running tools included.

Permission: undeclared

ParameterTypeRequiredDescription
idstringyesTask id from its receipt. A batch's id reaches every subagent in it
interruptbooleannoCut the current step short
messagestringyesWhat the subagent should know or do

todo_write

Create or update a structured todo list to track tasks.

Permission: none

ParameterTypeRequiredDescription
todosarrayyesThe updated todo list

memory

Persistent, project-scoped scratchpad for learnings, patterns, decisions, and gotchas across sessions.

Permission: undeclared

ParameterTypeRequiredDescription
commandstringyes- list: tag-grouped index, no bodies; optional tags.
- read: one body by path, or collated bodies by tags.
- write: create/overwrite path with content; optional tags.
- delete: path.
contentstringnoBody for write (frontmatter added automatically).
pathstringnoRelative path, e.g. 'architecture.md'.
tagsarraynosnake_case tags. Filter for list/read; assigned on write (defaults to filename stem).

skill

Load a skill that provides instructions and workflows for specific tasks.

Permission: fs_read

ParameterTypeRequiredDescription
namestringyesName of the skill to load

Web

webfetch

Fetch a URL and return its contents.

Permission: net

ParameterTypeRequiredDefaultDescription
formatstringnoOutput format: markdown (default), text, or html
timeoutintegerno30, max 120Timeout in seconds
urlstringyesURL to fetch (http:// or https://)

websearch

Search the web for real-time information using Exa AI.

Permission: net

ParameterTypeRequiredDefaultDescription
num_resultsintegerno8Number of results to return
querystringyesSearch query