Agent Tools Reference

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

Categories:

• File: file_read, file_write, file_edit
• Shell: bash
• Search: grep, glob, list_files
• Interaction: ask_user
• Task Management: todo_read, todo_write
• Web: web_search, web_fetch
• HTTP: http_request
• SMS: sms_send, sms_status, sms_schedule
• Multi-Edit: patch_apply
• Plan Mode: plan_enter, plan_exit
• Sub-Agent: task
• Pipeline: parallel
• Version Control: git_status
• Memory: memory_read, memory_write
• Logging: log_read
• Scheduling: schedule_task, schedule_list, schedule_cancel
• Custom Tools: tool_create, tool_register, tool_list_custom
• Second Opinion: consult
• Hub: hub_discovery, hub_dispatch
• Thinking: think
• LSP: lsp, go_lsp

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
}

glob

Find files by glob pattern with ** recursive directory matching. Results are sorted by modification time (newest first).

Parameters

Limits

• Maximum 500 results returned.
• Scans up to 50,000 files as a safety limit.
• Skips hidden directories/files and generated directories (.git, node_modules, etc.).

Details

• Supports ** for recursive directory matching (Go's filepath.Glob does not).
• Pattern is split on ** to get prefix and suffix. For example, src/**/*.go searches recursively under src/ for *.go files.
• Also supports simple glob patterns without ** (e.g. *.json), delegating to filepath.Glob.
• Results are sorted by modification time, newest first — useful for finding recently changed files.

Example

{
  "pattern": "**/*.go",
  "path": "internal"
}

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

http_request

Make an HTTP request to any URL. A generic REST API caller that supports all common HTTP methods.

Parameters

Limits

• Response body is truncated at 100 KB.
• Timeout is capped at 120 seconds.

Details

• Returns the HTTP status code, selected response headers (Content-Type, Location, X-Request-Id, X-RateLimit-Remaining, Retry-After), and the response body.
• JSON responses are automatically pretty-printed.
• Sets a muxd/1.0 User-Agent header by default.
• Use this instead of bash with curl — the output is cleaner and the agent can parse it more reliably.
• The agent should confirm with the user before making requests that modify external state (POST, PUT, DELETE).

Example

{
  "method": "POST",
  "url": "https://api.example.com/webhooks",
  "headers": {
    "Authorization": "Bearer sk-abc123",
    "Content-Type": "application/json"
  },
  "body": "{\"event\": \"deploy\", \"status\": \"success\"}"
}

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."
}

sms_send

Send an SMS message via the Textbelt API.

Parameters

Details

• Requires a Textbelt API key configured via /config set textbelt.api_key <key>.
• Returns the text ID (for status checks) and remaining quota on success.
• Get an API key at textbelt.com.

Example

{
  "phone": "5555555555",
  "message": "Hello from muxd!"
}

sms_status

Check the delivery status of a previously sent SMS using its text ID.

Parameters

Details

• Returns the delivery status: DELIVERED, SENT, SENDING, FAILED, or UNKNOWN.
• No API key required for status checks.

Example

{
  "text_id": "12345"
}

sms_schedule

Schedule an SMS for later sending via the scheduler.

Parameters

Details

• Requires a Textbelt API key and scheduler support.
• When using HH:MM format, the time auto-advances to the next day if the specified time has already passed.
• Schedules sms_send as the underlying tool call.

Example

{
  "phone": "5555555555",
  "message": "Daily reminder",
  "time": "09:00",
  "recurrence": "daily"
}

parallel

Run multiple tasks as a DAG pipeline. Tasks with no dependencies run simultaneously. Tasks with depends_on wait for prerequisites to complete and receive their output as context.

Parameters

Each task object:

Details

• Minimum 2 tasks, maximum 8 tasks per pipeline.
• Maximum dependency chain depth of 4.
• No cycles allowed. The DAG is validated before execution.
• Fail fast: if any task fails, remaining tasks are cancelled or skipped.
• Each task runs as a sub agent with the same model and tools, except: parallel, task, consult, tool_create, tool_register, tool_list_custom, and ask_user are not available.
• Dependent tasks receive predecessor output injected into their prompt.
• Output per task capped at 50 KB.
• Progress shown in the TUI with status icons and a DAG visualization.
• Not available to sub agents (prevents nested pipelines).
• See Parallel Pipeline for full documentation.

Example

{
  "tasks": [
    { "id": "1", "description": "refactor auth", "prompt": "Refactor the auth module to use JWT..." },
    { "id": "2", "description": "update docs", "prompt": "Update the API documentation..." },
    { "id": "3", "description": "write tests", "prompt": "Write tests for the auth module...", "depends_on": ["1"] }
  ]
}

Tasks 1 and 2 run in parallel. Task 3 waits for task 1 to complete.

git_status

Get git status in short format (-s).

Parameters

Limits

• Output is truncated at 50 KB.

Example

{
  "path": "."
}

memory_read

Read all project memory facts. Returns key-value pairs persisted across sessions in .muxd/memory.json.

Parameters

None. This tool takes no parameters.

Details

• Returns all stored facts as key: value lines, sorted alphabetically by key.
• Returns "No project memory facts stored." if no facts exist.
• Facts are also automatically injected into the system prompt at the start of every turn.
• See Project Memory for full details.

Example

{}

memory_write

Write or remove a project memory fact. Facts persist across sessions in .muxd/memory.json.

Parameters

Details

• set adds or overwrites a fact. Both key and value are required.
• remove deletes a fact by key. Returns a message if the key doesn't exist (not an error).
• Facts are stored in .muxd/memory.json in the project root.
• Writes are atomic (temp file + rename) to prevent corruption.
• See Project Memory for full details.

Example

{
  "action": "set",
  "key": "auth",
  "value": "JWT with refresh tokens, not sessions"
}

log_read

Read recent daemon log entries. Returns timestamped log lines from the muxd daemon.

Parameters

Details

• Returns log entries from the daemon's in-memory log buffer, newest first.
• Log entries include timestamps and cover events like: server start/stop, session creation, agent errors, scheduled task execution.
• Useful for debugging daemon behavior, checking scheduled task results, or diagnosing connection issues.
• Returns "No log entries." if the log buffer is empty.

Example

{
  "lines": 20
}

schedule_task

Schedule a multi-step agent task for future execution. At the scheduled time, a full agent loop is spawned with the given prompt and all available tools.

Parameters

Details

• Unlike scheduling a single tool call (e.g. sms_schedule), this spawns a full agent loop capable of multi-step reasoning and multiple tool calls.
• The scheduled agent runs headless — the ask_user tool is disabled since no one is present to answer.
• The agent has the same model, provider, and credentials as the parent session.
• Agent tasks bypass the scheduler.allowed_tools allowlist. The spawned agent enforces its own tool policy.
• Output is capped at 50 KB.
• The agent loop is capped at 60 iterations to prevent runaway execution.
• Scheduled task sessions are tagged with project_path = "__scheduled_task__" for easy identification.
• Not available to sub-agents (prevents recursive scheduling).

Example

{
  "prompt": "Search for recent Go blog posts and write a summary of the top 5",
  "time": "16:00",
  "recurrence": "daily"
}

schedule_list

List all scheduled jobs. Returns job IDs, tool names, scheduled times, recurrence, and status.

Parameters

Details

• Returns all scheduled jobs ordered by scheduled time.
• Each entry includes: ID, tool name, scheduled time, recurrence, status, and prompt preview (for agent tasks).
• Agent tasks are displayed as agent_task instead of the internal tool name.
• Returns "No scheduled jobs." if no jobs exist.
• Use this to check the current schedule before creating new tasks or to find job IDs for cancellation.

Example

{
  "limit": 10
}

schedule_cancel

Cancel a scheduled job by ID. Only pending or failed jobs can be cancelled.

Parameters

Details

• Marks the job as cancelled. It will not execute.
• Only jobs with pending or failed status can be cancelled.
• Use schedule_list to find the job ID first.

Example

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

tool_create

Create a new custom tool from a shell command template. The tool becomes immediately available to the agent.

Parameters

Details

• Use {{param_name}} placeholders in the command for parameter substitution.
• Parameter values are shell-escaped to prevent injection.
• The tool name must not conflict with any built-in tool.
• Ephemeral tools (default) exist only for the current session. Persistent tools are loaded on every startup.
• Custom tools execute through the same bash infrastructure as the bash tool. If bash is disabled (e.g., safe profile), custom tools are also blocked.
• Not available to sub-agents.

Example

{
  "name": "check_port",
  "description": "Check if a port is open on localhost",
  "command": "nc -zv localhost {{port}} 2>&1",
  "parameters": {
    "port": {"type": "string", "description": "Port number to check"}
  },
  "required": ["port"],
  "persistent": true
}

tool_register

Register an existing script file as a custom tool. Write the script first with file_write, then register it here.

Parameters

Details

• The script file must exist at the specified path.
• Parameters are passed to the script as environment variables: PARAM_NAME=value (uppercased).
• Use for complex multi-line tools that don't fit in a single command template.
• Same security model as tool_create — blocked when bash is disabled.
• Not available to sub-agents.

Example

{
  "name": "deploy_staging",
  "description": "Deploy the current branch to staging",
  "script": "/home/user/.config/muxd/tools/deploy_staging.sh",
  "parameters": {
    "branch": {"type": "string", "description": "Git branch to deploy"}
  },
  "required": ["branch"],
  "persistent": true
}

tool_list_custom

List all custom tools (both ephemeral and persistent) with their definitions.

Parameters

None. This tool takes no parameters.

Details

• Shows each tool's name, persistence status, description, and command or script path.
• Returns "No custom tools registered." if none exist.
• Use this to check what custom tools are available before creating duplicates.
• Not available to sub-agents.

Example

{}

consult

Ask a different AI model for a second opinion on a problem or approach. The response is shown to the user in a separate styled view, not fed back to the primary agent.

Parameters

Details

• Requires model.consult to be configured: /config set model.consult <model> (e.g., openai/gpt-4o, anthropic/claude-haiku).
• The consult model receives a single-turn request with no tools and no conversation history. Only the focused summary is sent.
• The response is displayed with a crystal ball emoji in a separate styled block, independent from the main conversation.
• The primary agent does not see the consult response. It receives only "Second opinion delivered to user."
• Users can also trigger this with the /consult slash command.
• Not available to sub-agents.

Example

{
  "summary": "I'm debugging a race condition in the session store. I think the issue is concurrent writes to the SQLite WAL, but I'm not sure if adding a mutex around the write path is the right fix or if I should use connection pooling with MaxOpenConns(1) instead."
}

hub_discovery

List all nodes connected to the hub with their capabilities.

Parameters

None. This tool takes no parameters.

Details

• Returns each node's name, status (online/offline), platform, architecture, provider, model, and available tools.
• Only available when connected to a hub.
• Use this to see what remote machines are available before dispatching work.
• Not available to sub-agents.

Example

{}

hub_dispatch

Send a task to a remote node for execution via the hub.

Parameters

Details

• Creates a session on the target node, submits the prompt, and collects the agent's text output.
• The remote agent runs a full agent loop with its own tools and model.
• Output is capped at 50 KB.
• Only available when connected to a hub. The target node must be online.
• Not available to sub-agents (prevents infinite dispatch chains).

Example

{
  "node": "dev-server",
  "prompt": "Run the test suite and report any failures"
}

think

Expose the agent's internal reasoning before responding.

Parameters

Details

• The thought is shown to the user as a reasoning block and included in context.
• No length limit.
• Use freely whenever a task is ambiguous, complex, or benefits from explicit planning before tool use.

Example

{
  "thought": "The user wants to add a new API endpoint. I need to: 1) Add the route handler, 2) Update the router, 3) Add tests. Let me check the existing patterns first."
}

lsp

Multi-language code intelligence via Language Server Protocol. Supports go-to-definition, references, hover, diagnostics, and symbol search. Auto-detects the language from file extension.

Parameters

Supported Languages

Details

• Auto-detection: If you pass a .py file, Python is selected automatically. No need to specify language.
• Persistent servers: Each language server is started lazily on first use and stays warm for the entire session. One process per language.
• Aliases: golang → Go, ts/js/javascript → TypeScript, py → Python, cpp/c++/cc → C.
• Only call once per action per turn.

Example

{
  "action": "definition",
  "file": "src/main.go",
  "line": 10,
  "column": 5
}

go_lsp

Go language intelligence via gopls. Provides the same 7 actions as lsp (definition, references, diagnostics, hover, implementation, symbols, workspace_symbol) but scoped to Go files only.

Parameters

Details

• Uses gopls under the hood. Requires go install golang.org/x/tools/gopls@latest.
• Supports all 7 LSP actions: definition, references, diagnostics, hover, implementation, symbols, workspace_symbol.
• The lsp tool is the recommended replacement — it supports Go plus TypeScript, Python, Rust, and C/C++ with auto-detection.
• Only call once per action per turn.

Example

{
  "action": "references",
  "file": "internal/tools/lsp.go",
  "line": 10,
  "column": 5
}