Tools

Tools carry out concrete external actions for the Bub app, such as reading and writing files, running commands, and managing sessions.

Built-in tools

The Bub app ships with the following core tools:

Category	Tool	Purpose
Process management	bash	Run Shell commands; supports a working directory, timeouts, and background runs
	bash.output, bash.kill	Read background output incrementally, or terminate a running process
File operations	fs.read, fs.write, fs.edit	Paged reads, whole-file writes, and precise text replacement
Web fetch	web.fetch	Issue GET requests to fetch pages (Markdown preferred)
Capability discovery	skill	List skills discovered in the workspace, or read a specified skill’s body
	tool.describe	Load the full definition of a deferred tool
Session management	tape.info, tape.search	Check token usage and search conversation records
	tape.handoff, tape.reset	Move the context start point to compact the session, or archive and reset the context
	spill.read	Read large tool results that exceed the context limit in chunks
Multi-task coordination	subagent	Start a subagent to handle tasks in parallel in a separate session
Code mode	run_code	Compose multiple tools in Python when code mode is on

Built-in tool parameters and defaults are listed in the tools reference.

Use tools

In the Bub app, tools can be called in two ways:

1. The model picks them: ask a question as usual, and the model selects and calls tools based on the task intent and tool descriptions.
2. Call from the command line: use the comma prefix in a terminal to call a tool directly (no model call, no token usage):

   bub run ",fs.read path=README.md"

To constrain or standardize how the model uses tools:

• Workspace conventions: write general rules in AGENTS.md at the project root;
• Task procedures: package multi-step operations as skills that walk the model through the right tools in order.

Enable code mode

For complex logic or batch data processing, repeated tool round-trips consume a lot of context. With code mode on, the model writes Python directly (executed through the run_code tool) and composes several tools in a single pass:

,code_mode enable=true

Note:

• The setting takes effect from the next turn and is persisted in the current session record.
• Use ,code_mode enable=false to turn it off and return to the default mode.
• For the Python syntax for calling tools in code mode, see the run_code reference.

Execution environment and security

Built-in tools such as Shell commands (bash), file access (fs.*), and code execution (run_code) run directly with the current local user’s permissions and can have irreversible effects on your system or data. Keep the following in mind:

• Not securely isolated: the default environment is not an isolated sandbox; commands the model runs have real read/write and process side effects on the local system.
• Permissions and interception: use tool interception hooks when you need human approval or extra conditions before high-risk commands run.
• Containers and isolated environments: provide a separate execution environment through a plugin when you need isolated execution.

Integrate and extend tools

If the built-in tools are not enough, extend them in these ways:

• Install community plugins: browse community plugins to find plugins or third-party MCP services (see MCP integration);
• Write your own plugin: write Python functions and register them as Bub tools, then ship them with a plugin; see Provide tools.