# Available Local Tools in Maka's Tool Runtime: Complete Reference

> Discover Maka's eight core local tools including Bash Read Write Edit FormatJson Glob Grep and Apply Patch Explore this complete reference for Maka's tool runtime.

- Repository: [The Apache Software Foundation/maka](https://github.com/apache/maka)
- Tags: api-reference
- Published: 2026-08-22

---

**Maka's tool runtime ships with eight core local tools—Bash, Read, Write, Edit, FormatJson, Glob, Grep, and optional Apply Patch—defined in [`packages/runtime/src/builtin-tools.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/builtin-tools.ts) and exposed through the `buildBuiltinTools` factory.**

Maka's local tool runtime provides a sandbox-aware execution environment that allows agents to interact with the filesystem, execute commands, and process data without external service dependencies. These tools are defined in the Apache Maka repository and implement the uniform `MakaTool` interface for consistent parameter handling and result formatting.

## Core Local Tool Inventory

The canonical list of available local tools resides in [`packages/runtime/src/builtin-tools.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/builtin-tools.ts). Each tool is registered with an **activity kind** (command, read, edit, or search) and implements safety constraints appropriate for autonomous execution.

### Bash (command)

The **Bash** tool executes shell commands within the session's working directory. Located at approximately lines 25-33 in [`builtin-tools.ts`](https://github.com/apache/maka/blob/main/builtin-tools.ts), it respects the active permission profile and operates within the session's sandbox constraints.

### File System Operations (Read, Write, Edit)

Three distinct tools handle file manipulation with different granularity:

- **Read**: Retrieves text content from disk with optional `offset` and `limit` parameters for pagination (lines 50-57). Returns raw file content or runtime resources.
- **Write**: Creates or overwrites files entirely, returning either a `file_write` result or a `file_diff` when the underlying filesystem supports diff reporting (lines 18-26).
- **Edit**: Performs surgical string replacement using `old_string` and `new_string` parameters. It validates unique matches before applying changes and returns detailed diagnostics (lines 42-50).

### JSON Processing (FormatJson)

The **FormatJson** tool validates JSON syntax and optionally sorts keys alphabetically. It rewrites the target file with canonical 2-space indentation and returns diagnostic information without transmitting raw content back to the agent (lines 86-94).

### Search Operations (Glob, Grep)

Two search tools provide filesystem discovery capabilities with built-in result limits:

- **Glob**: Returns file paths matching a glob pattern, capped at 200 results (lines 29-38).
- **Grep**: Executes regular expression searches using ripgrep across file contents. Returns up to 50 matches per file with a total limit of 200 results (lines 62-71).

## Optional and Conditional Tools

Beyond the core set, Maka's runtime conditionally exposes additional tools based on executor capabilities and caller configuration.

### Apply Patch

The **Apply Patch** tool becomes available only when the underlying executor supports the `applyPatch` capability. It applies file changes using provider-specific protocols (OpenAI-Apply-Patch or Codex V4a) and is defined around lines 26-36 in [`builtin-tools.ts`](https://github.com/apache/maka/blob/main/builtin-tools.ts).

### Background Task Controls

When callers supply `backgroundTasks` or `ptyControls` implementations, the runtime injects two additional tools: `stop_background_task` and `write_stdin`. These enable interaction with long-running background processes (constructed at lines 21-24).

## Tool Architecture and Type Safety

All local tools conform to the **MakaTool** interface defined in [`packages/runtime/src/tool-runtime.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/tool-runtime.ts), which serves as the single source of truth for tool shapes throughout the codebase. The `buildBuiltinTools` factory function in [`builtin-tools.ts`](https://github.com/apache/maka/blob/main/builtin-tools.ts) instantiates these tools with consistent parameter schemas, execution facts, and result handling.

The runtime serializes tool definitions using `ModelToolDefinition` and `ModelToolSet` types declared in [`packages/runtime/src/model-protocol.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/model-protocol.ts), producing JSON representations suitable for LLM provider consumption. Additionally, [`packages/mcp/src/tool-definition.ts`](https://github.com/apache/maka/blob/main/packages/mcp/src/tool-definition.ts) handles fingerprinting of these definitions for the Maka Control Protocol (MCP).

## Practical Usage Examples

Invoke local tools through the tool runner using the factory-defined names:

```typescript
// Execute shell commands
await toolRunner.invoke('Bash', { command: 'ls -la' });

// Read file content with pagination
await toolRunner.invoke('Read', { path: 'README.md', limit: 10 });

// Write new files
await toolRunner.invoke('Write', { path: 'notes.txt', content: 'Hello, Maka!' });

// Perform surgical edits
await toolRunner.invoke('Edit', {
  path: 'config.yaml',
  old_string: 'debug: false',
  new_string: 'debug: true',
});

// Format and sort JSON
await toolRunner.invoke('FormatJson', { path: 'package.json', sort_keys: true });

// Search files by pattern
await toolRunner.invoke('Glob', { pattern: '**/*.md' });

// Grep for TODOs in TypeScript
await toolRunner.invoke('Grep', { pattern: 'TODO', path: 'src', glob: '**/*.ts' });

```

## Key Implementation Files

Understanding the local tool runtime requires familiarity with these specific source files:

- [`packages/runtime/src/builtin-tools.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/builtin-tools.ts): Central definition of all local tools and the `buildBuiltinTools` factory.
- [`packages/runtime/src/tool-runtime.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/tool-runtime.ts): Exports the `MakaTool` interface, establishing the contract for tool parameters and results.
- [`packages/runtime/src/model-protocol.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/model-protocol.ts): Declares `ModelToolDefinition` and `ModelToolSet` for LLM serialization.
- [`packages/mcp/src/tool-definition.ts`](https://github.com/apache/maka/blob/main/packages/mcp/src/tool-definition.ts): Manages tool fingerprinting for the Maka Control Protocol.
- [`packages/eval/src/toolchain-verification.ts`](https://github.com/apache/maka/blob/main/packages/eval/src/toolchain-verification.ts): Validates experiment toolchains against the built-in tool list.

## Summary

- Maka provides **eight core local tools** (Bash, Read, Write, Edit, FormatJson, Glob, Grep) plus optional Apply Patch and conditional background controls.
- All tools are defined in [`packages/runtime/src/builtin-tools.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/builtin-tools.ts) and implement the `MakaTool` interface from [`tool-runtime.ts`](https://github.com/apache/maka/blob/main/tool-runtime.ts).
- Tools operate within sandbox-aware environments with built-in safety constraints like result caps (200 files for Glob, 50 matches/file for Grep).
- The `buildBuiltinTools` factory ensures uniform parameter handling and result formatting across all local operations.
- Optional tools require specific executor capabilities (`applyPatch`) or caller-provided implementations (`backgroundTasks`/`ptyControls`).

## Frequently Asked Questions

### What is the difference between Write and Edit tools in Maka?

The **Write** tool performs wholesale file replacement, overwriting entire contents and returning either a write confirmation or diff summary. The **Edit** tool performs targeted string replacement using `old_string` and `new_string` parameters, validating unique matches before modification to prevent ambiguous changes.

### How does Maka's Bash tool handle security and sandboxing?

According to the source code in [`builtin-tools.ts`](https://github.com/apache/maka/blob/main/builtin-tools.ts) (lines 25-33), the Bash tool executes within the session's active permission profile and working directory constraints. It is sandbox-aware, meaning it respects filesystem and network restrictions configured for the current session rather than executing with full system privileges.

### Can I add custom local tools to Maka's runtime?

The current implementation in [`packages/runtime/src/builtin-tools.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/builtin-tools.ts) defines a fixed set of local tools through the `buildBuiltinTools` factory. While the `MakaTool` interface in [`tool-runtime.ts`](https://github.com/apache/maka/blob/main/tool-runtime.ts) provides the extension contract, adding custom tools would require modifying the factory or implementing additional tool providers that conform to the `ModelToolDefinition` protocol specified in [`model-protocol.ts`](https://github.com/apache/maka/blob/main/model-protocol.ts).

### What are the search limits for Glob and Grep tools?

The **Glob** tool caps results at 200 file paths maximum. The **Grep** tool returns up to 50 matches per individual file with a total result limit of 200 matches across all files searched, as implemented in lines 29-38 and 62-71 of [`builtin-tools.ts`](https://github.com/apache/maka/blob/main/builtin-tools.ts) respectively.