Custom Tools

muxd lets you register your own tools that the agent can call, without restarting the daemon. You can define simple command templates with placeholder substitution or register full scripts that the agent can invoke.

Creating a Tool

Command Templates (`tool_create`)

tool_create defines a tool backed by a shell command with {{param}} placeholders. When the agent calls the tool, each placeholder is replaced with the corresponding argument (shell-escaped) before the command is run.

Example — create a tool that checks whether an HTTP endpoint is healthy:

/tool_create name=health_check description="Check if an HTTP endpoint returns 200" \
  command="curl -o /dev/null -s -w '%{http_code}' {{url}}" \
  params=url

The agent can now call health_check with a url argument and get back the HTTP status code.

Script Tools (`tool_register`)

tool_register binds a tool name to an existing script file — typically one the agent just wrote with file_write. The script receives its parameters as environment variables named after each parameter in uppercase.

Example — after writing a deploy script to /tmp/deploy.sh:

/tool_register name=deploy description="Deploy to staging" \
  script=/tmp/deploy.sh params=env,version

When the agent calls deploy with env=staging version=1.4.2, the script runs with ENV=staging and VERSION=1.4.2 set in its environment.

Listing Custom Tools

/tool_list_custom

Prints the name, description, type (command or script), and persistence of every registered custom tool.

Ephemeral vs. Persistent

By default, tools are ephemeral — they exist only for the current session and are gone when you start a new one.

To persist a tool across all future sessions, pass persist=true:

/tool_create name=health_check ... persist=true

Persistent tools are stored in ~/.config/muxd/tools/ as JSON files and are loaded automatically at daemon startup.

Parameters

Command tools — parameters are shell-escaped and substituted into the command string at the {{param_name}} position.

Script tools — parameters are passed as environment variables. The variable name is the parameter name uppercased: url becomes URL, api_key becomes API_KEY.

Security

Constraint	Detail
Bash disabled	Custom tools cannot be called if `bash` is disabled in the agent's tool policy
Sub-agents	Custom tools are not forwarded to sub-agents spawned via `agent_dispatch`
Shell escaping	Command template arguments are shell-escaped before substitution
Script path	The script path is resolved at registration time; moving the file will break the tool

Example: API Health Check Tool

Here is a complete walkthrough:

Ask the agent to write a health check script:

"Write a shell script to /tmp/health.sh that accepts BASE_URL and PATH as env vars and prints the HTTP status code"

/tool_register name=api_health description="Check HTTP endpoint status" \
  script=/tmp/health.sh params=base_url,path persist=true

The agent can now call api_health during any future session:

"Check whether the /api/v1/users endpoint on staging is up."