nanobot/workspace/TOOLS.md

Available Tools

This document describes the tools available to nanobot.

File Operations

read_file

Read the contents of a file.

read_file(path: str) -> str

write_file

Write content to a file (creates parent directories if needed).

write_file(path: str, content: str) -> str

edit_file

Edit a file by replacing specific text.

edit_file(path: str, old_text: str, new_text: str) -> str

list_dir

List contents of a directory.

list_dir(path: str) -> str

Shell Execution

exec

Execute a shell command and return output.

exec(command: str, working_dir: str = None) -> str

Safety Notes:

• Commands have a configurable timeout (default 60s)
• Dangerous commands are blocked (rm -rf, format, dd, shutdown, etc.)
• Output is truncated at 10,000 characters
• Optional restrictToWorkspace config to limit paths

Web Access

web_search

Search the web using Brave Search API.

web_search(query: str, count: int = 5) -> str

Returns search results with titles, URLs, and snippets. Requires tools.web.search.apiKey in config.

web_fetch

Fetch and extract main content from a URL.

web_fetch(url: str, extractMode: str = "markdown", maxChars: int = 50000) -> str

Notes:

• Content is extracted using readability
• Supports markdown or plain text extraction
• Output is truncated at 50,000 characters by default

Communication

message

Send a message to the user (used internally).

message(content: str, channel: str = None, chat_id: str = None) -> str

Background Tasks

spawn

Spawn a subagent to handle a task in the background.

spawn(task: str, label: str = None) -> str

Use for complex or time-consuming tasks that can run independently. The subagent will complete the task and report back when done.

Scheduled Reminders (Cron)

Use the exec tool to create scheduled reminders with nanobot cron add:

Set a recurring reminder

# Every day at 9am
nanobot cron add --name "morning" --message "Good morning! ☀️" --cron "0 9 * * *"

# Every 2 hours
nanobot cron add --name "water" --message "Drink water! 💧" --every 7200

Set a one-time reminder

# At a specific time (ISO format)
nanobot cron add --name "meeting" --message "Meeting starts now!" --at "2025-01-31T15:00:00"

Manage reminders

nanobot cron list              # List all jobs
nanobot cron remove <job_id>   # Remove a job

Heartbeat Task Management

The HEARTBEAT.md file in the workspace is checked every 30 minutes. Use file operations to manage periodic tasks:

Add a heartbeat task

# Append a new task
edit_file(
    path="HEARTBEAT.md",
    old_text="## Example Tasks",
    new_text="- [ ] New periodic task here\n\n## Example Tasks"
)

Remove a heartbeat task

# Remove a specific task
edit_file(
    path="HEARTBEAT.md",
    old_text="- [ ] Task to remove\n",
    new_text=""
)

Rewrite all tasks

# Replace the entire file
write_file(
    path="HEARTBEAT.md",
    content="# Heartbeat Tasks\n\n- [ ] Task 1\n- [ ] Task 2\n"
)

---

Adding Custom Tools

To add custom tools:

1. Create a class that extends Tool in nanobot/agent/tools/
2. Implement name, description, parameters, and execute
3. Register it in AgentLoop._register_default_tools()