Agent Tools Reference

muxd's agent has 18 built-in tools organized across 11 categories. This document describes each tool, its parameters, and constraints.

Categories:

• File: file_read, file_write, file_edit
• Shell: bash
• Search: grep, list_files
• Interaction: ask_user
• Task Management: todo_read, todo_write
• Web: web_search, web_fetch
• Social Media: twitter_post, twitter_schedule
• Multi-Edit: patch_apply
• Plan Mode: plan_enter, plan_exit
• Sub-Agent: task
• Version Control: git_status

file_read

Read the contents of a file. Returns the file content with line numbers.

Parameters

Limits

• Output is truncated at 50 KB.
• Line numbers are formatted as %4d | content.

Example

{
  "path": "main.go",
  "offset": 10,
  "limit": 30
}

file_write

Write content to a file. Creates parent directories if they don't exist. Overwrites the file if it already exists.

Parameters

Details

• Parent directories are created with permissions 0755.
• Files are written with permissions 0644.
• Prefer file_edit when modifying existing files to avoid rewriting unchanged content.

Example

{
  "path": "src/utils.go",
  "content": "package main\n\nfunc hello() string {\n\treturn \"hello\"\n}\n"
}

file_edit

Edit a file by replacing an exact string match.

Parameters

Details

• The old_string must appear exactly once in the file unless replace_all is true.
• If there are multiple matches and replace_all is false, the tool returns an error with the match count and suggests using replace_all.
• Zero matches also returns an error.
• The agent should always read a file before editing to get the exact text.

Example

{
  "path": "main.go",
  "old_string": "fmt.Println(\"hello\")",
  "new_string": "fmt.Println(\"hello, world\")"
}

bash

Run a shell command and return the output.

Parameters

Details

• On Windows, uses cmd /C. On Unix, uses sh -c.
• Captures both stdout and stderr.
• Output is truncated at 50 KB.
• Timeout is capped at 120 seconds. On timeout, "(command timed out after Ns)" is appended.
• On non-zero exit, "(exit code: N)" is appended.
• Working directory is set to the session's current directory.

Example

{
  "command": "go test ./...",
  "timeout": 60
}

grep

Search files for a regex pattern. Returns matching lines in file:line:content format.

Parameters

Limits

• Maximum 200 matches returned.
• Skips hidden directories and files (names starting with .).
• Skips files larger than 1 MB.
• Skips binary files (detected by null bytes in the first 512 bytes).
• context_lines is capped at 10.
• In context mode, -- separates non-contiguous groups, : prefixes match lines, and a space prefixes context lines.

Example

{
  "pattern": "func Test",
  "include": "*.go",
  "context_lines": 2
}

list_files

List files and directories. Returns entries with a / suffix for directories.

Parameters

Limits

• Maximum 500 entries returned.
• Skips hidden directories/files and these directories: .git, .hg, .svn, .idea, .vscode, node_modules, __pycache__, .DS_Store.
• If path contains glob metacharacters (*, ?, [), uses glob matching instead of directory listing.
• Recursive mode sorts results alphabetically and uses forward slashes in output.

Example

{
  "path": "src",
  "recursive": true,
  "include": "*.go"
}

ask_user

Ask the user a question and wait for their response. The agent loop pauses until the user replies.

Parameters

Details

• The agent loop is paused until the user replies. No other tools execute in the meantime.
• Use when you need clarification, a decision, or confirmation before proceeding.
• This tool is always executed sequentially (never in parallel with other tools).

Example

{
  "question": "Should I refactor the database layer to use transactions, or keep the current approach?"
}

todo_read

Read the current todo list. Returns all items with their ID, title, status, and optional description.

Parameters

None. This tool takes no parameters.

Details

• The todo list is in-memory and per-session: it resets when the session ends.
• Returns items in the format: [id] status: title (description).
• Returns "Todo list is empty." if no items exist.
• Use this to check progress before planning next steps.

Example

{}

todo_write

Overwrite the todo list with a new set of items. Use this to track multi-step plans.

Parameters

Each todo item object has:

Details

• Overwrites the entire todo list: always send the full list, not just changes.
• Only one item may be in_progress at a time. If multiple items have in_progress status, the tool returns an error.
• The todo list is in-memory and per-session.
• Returns the updated list as confirmation.

Example

{
  "todos": [
    {"id": "1", "title": "Read existing code", "status": "completed"},
    {"id": "2", "title": "Implement new feature", "status": "in_progress"},
    {"id": "3", "title": "Write tests", "status": "pending"}
  ]
}

web_search

Search the web using the Brave Search API. Returns results with title, URL, and snippet.

Parameters

Details

• Requires the BRAVE_SEARCH_API_KEY environment variable to be set.
• Uses the Brave Search API free tier.
• Results are formatted as a numbered list with title, URL, and description.
• Returns "No results found." if the query yields no results.

Example

{
  "query": "Go context.WithTimeout best practices",
  "count": 5
}

web_fetch

Fetch a URL and return the text content. HTML pages are automatically stripped to plain text.

Parameters

Limits

• Reads up to 1 MB of raw content from the response.
• Output is truncated at 50 KB.
• HTTP timeout is 30 seconds.

Details

• HTML content is detected by Content-Type header or leading < character, and is automatically converted to plain text.
• HTML-to-text conversion strips tags, removes <script> and <style> blocks, decodes common HTML entities, and collapses whitespace.
• Non-HTML content (JSON, plain text, etc.) is returned as-is.
• Sets a muxd/1.0 User-Agent header.

Example

{
  "url": "https://pkg.go.dev/context"
}

patch_apply

Apply a unified diff patch to one or more files. Use this for making multiple related changes across files in a single operation.

Parameters

Details

• Accepts standard unified diff format with ---/+++ file headers and @@ hunk headers.
• Strips a/ and b/ prefixes from file paths.
• Context lines are validated: if the file content doesn't match the expected context, the patch fails.
• Hunks are applied in reverse order (bottom-up) to preserve line numbers.
• Creates parent directories if needed.
• Returns a summary of applied hunks per file.
• Prefer file_edit for simple single-location changes. Use patch_apply when making multiple coordinated changes across files.
• Disabled in plan mode.

Example

{
  "patch": "--- a/main.go\n+++ b/main.go\n@@ -10,3 +10,4 @@\n func main() {\n \tfmt.Println(\"hello\")\n+\tfmt.Println(\"world\")\n }\n"
}

plan_enter

Enter plan mode. Disables write tools so you can safely explore and analyze before making changes.

Parameters

None. This tool takes no parameters.

Details

• In plan mode, the following tools are disabled: file_write, file_edit, bash, patch_apply.
• Read and search tools remain available: file_read, grep, list_files, web_search, web_fetch, todo_read, todo_write, ask_user.
• If already in plan mode, returns "Already in plan mode.".
• This tool is always executed sequentially (never in parallel with other tools).
• Use plan_exit to leave plan mode and re-enable write tools.

Example

{}

plan_exit

Exit plan mode and re-enable all write tools.

Parameters

None. This tool takes no parameters.

Details

• Re-enables file_write, file_edit, bash, and patch_apply.
• If not in plan mode, returns "Not in plan mode.".
• This tool is always executed sequentially (never in parallel with other tools).

Example

{}

task

Spawn a sub-agent to handle an independent subtask. The sub-agent gets a fresh conversation with the same model and provider.

Parameters

Details

• The sub-agent runs to completion and returns its output.
• Sub-agents have all tools except task (no recursion / nested sub-agents).
• Sub-agents do not persist messages to the database.
• Output is capped at 50 KB.
• This tool is always executed sequentially (never in parallel with other tools).
• Use for independent subtasks that don't need the main conversation's context.

Example

{
  "description": "find unused imports",
  "prompt": "Search all Go files in the project for unused imports and list them with file paths and line numbers."
}

twitter_post

Post a tweet via X API v2. Requires twitter.bearer_token or TWITTER_BEARER_TOKEN.

Parameters

Limits

• HTTP timeout is 20 seconds.
• Text is capped at 280 characters (rune count).

Example

{
  "text": "Hello from muxd!"
}

twitter_schedule

Schedule a tweet for later posting.

Parameters

Details

• When using HH:MM format, the time auto-advances to the next day if the specified time has already passed.
• Requires scheduler support.

Example

{
  "text": "Good morning!",
  "time": "08:00",
  "recurrence": "daily"
}

git_status

Get git status in short format (-s).

Parameters

Limits

• Output is truncated at 50 KB.

Example

{
  "path": "."
}