# Apache Maka Built-in Tools: A Complete Guide to the Core Agent Toolbox

> Explore Apache Maka's seven core built-in tools including Read, Write, Edit, Bash, Glob, and Grep for file operations and code management. Enhance agent capabilities now.

- Repository: [The Apache Software Foundation/maka](https://github.com/apache/maka)
- Tags: how-to-guide
- Published: 2026-09-04

---

**Apache Maka provides seven core built-in tools—Read, Write, Edit, FormatJson, Bash, Glob, and Grep—that enable agents to perform file operations, execute shell commands, and search codebases, with optional tools like `apply_patch` available when specific runtime capabilities are detected.**

Apache Maka is an open-source framework for building model-driven agents that interact with external systems. The **Apache Maka built-in tools** defined in the runtime's `builtin-tools` module constitute the default toolbox every agent receives, exposing functionality for filesystem manipulation, command execution, and text search through a standardized TypeScript API.

## How Built-in Tools Are Assembled

All built-in tools are constructed by the `buildBuiltinTools()` factory function located in [`packages/runtime/src/builtin-tools.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/builtin-tools.ts) (lines 94‑133). This function returns an array of `MakaTool` objects that the runtime automatically injects into agent sessions. According to the Apache Maka source code, these tools form the **default tool surface** available to any model-driven agent, regardless of the specific hosting environment.

## File Operation Tools

The core filesystem utilities handle reading, writing, and structured editing of files within the session's working directory.

### Read Tool

**Purpose:** Retrieve file contents or image snapshots from disk.

Defined at lines 54‑58 of [`builtin-tools.ts`](https://github.com/apache/maka/blob/main/builtin-tools.ts), the **Read** tool (kind: `read`) accepts a file path and returns the content string or binary representation. It respects session permissions and can handle both text files and image resources.

### Write Tool

**Purpose:** Create new files or overwrite existing content.

The **Write** tool (kind: `edit`) is implemented at lines 52‑53. It writes arbitrary text to a specified path, honoring session permission constraints. Depending on the runtime configuration, it may return a diff representation of the changes rather than the full file content.

### Edit Tool

**Purpose:** Perform precise search-and-replace modifications.

Located at lines 76‑78, the **Edit** tool (kind: `edit`) requires a unique string match within the target file. It searches for the specified pattern and rewrites only the matched section, ensuring atomic modifications without affecting surrounding content.

### FormatJson Tool

**Purpose:** Validate and canonicalize JSON structures.

The **FormatJson** tool (kind: `edit`, lines 82‑84) parses JSON files, optionally sorts object keys, and rewrites the content with consistent 2‑space indentation. This ensures standardized formatting across the codebase regardless of how the original file was structured.

## Search and Discovery Tools

These utilities enable agents to locate files and search content without loading entire directories into context.

### Glob Tool

**Purpose:** Find files matching glob patterns.

Defined at lines 92‑94, the **Glob** tool (kind: `search`) returns up to 200 file paths matching the specified pattern. It respects session permissions to ensure agents cannot access files outside their authorized scope.

### Grep Tool

**Purpose:** Search file contents using regular expressions.

The **Grep** tool (kind: `search`, lines 96‑98) leverages ripgrep for high-performance text search. It enforces strict limits: 50 matches per file and 200 total results, plus a wall‑clock timeout to prevent resource exhaustion during broad searches.

## Command Execution Tools

### Bash Tool

**Purpose:** Execute shell commands in the session environment.

The **Bash** tool (kind: `command`, lines 59‑63) runs arbitrary shell commands within the session's working directory. It supports configurable timeout parameters (in milliseconds) and sandbox enforcement to prevent unauthorized system access.

## Conditional and Optional Tools

Apache Maka dynamically extends the toolset based on runtime capabilities. These tools are only added when specific underlying implementations are detected.

### apply_patch Tool

**Purpose:** Apply provider-specific file patches.

Available only when the executor supports an `applyPatch` API (lines 28‑33), this tool (kind: `edit`) applies one or more file changes using a protocol specific to the hosting environment. It enables advanced refactoring operations beyond simple text replacement.

### Process Control Tools

When the runtime supplies `backgroundTasks` or `ptyControls` implementations, Maka exposes additional control utilities:

- **`stop_background_task`** (kind: `control`): Terminates previously initiated background processes (lines 24‑27).
- **`write_stdin`** (kind: `control`): Writes data to a running PTY's stdin stream (lines 24‑27).

## Working with Built-in Tools in Practice

The following example demonstrates how to instantiate and invoke built-in tools from a Maka session:

```typescript
// Example: invoke a built-in tool from a Maka session (pseudo-API)
import { buildBuiltinTools } from '@maka/runtime/builtin-tools';

// 1️⃣ Build the default tool set
const tools = buildBuiltinTools();

// 2️⃣ Find the Bash tool and run a command
const bash = tools.find(t => t.name === 'Bash');
await bash!.impl({ command: 'ls -l', timeout_ms: 30_000 }, ctx);

// 3️⃣ Read a file
const read = tools.find(t => t.name === 'Read');
const file = await read!.impl({ path: 'README.md' }, ctx);
console.log(file.content);

// 4️⃣ Search for a pattern
const grep = tools.find(t => t.name === 'Grep');
const matches = await grep!.impl(
  { pattern: 'TODO', path: '.', glob: '**/*.ts' },
  ctx,
);
console.log(matches.matches);

```

The `ctx` parameter represents a `MakaToolContext` supplied by the runtime, containing properties like `cwd` (current working directory) and `abortSignal` for cancellation.

## Key Source Files

Understanding the built-in tools requires familiarity with these core modules:

- **[`packages/runtime/src/builtin-tools.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/builtin-tools.ts)**: Central definition of all built-in tools and the `buildBuiltinTools()` factory function.
- **[`packages/runtime/src/tool-runtime.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/tool-runtime.ts)**: TypeScript type definitions for `MakaTool` and `MakaToolContext` used by each implementation.
- **[`packages/runtime-host/src/server/interactive-run-composer.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/server/interactive-run-composer.ts)**: Demonstrates how the host composes built-in tools into a session via the `builtinTools` option.
- **[`packages/runtime/src/__tests__/builtin-tools.test.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/__tests__/builtin-tools.test.ts)**: Comprehensive test suite exercising each tool's behavior and edge cases.

## Summary

- **Apache Maka built-in tools** are defined in [`packages/runtime/src/builtin-tools.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/builtin-tools.ts) and assembled by `buildBuiltinTools()` at runtime.
- The seven core tools cover **file reading** (Read), **file writing** (Write), **text editing** (Edit), **JSON formatting** (FormatJson), **command execution** (Bash), and **search operations** (Glob, Grep).
- **Optional tools** like `apply_patch`, `stop_background_task`, and `write_stdin` are conditionally added based on runtime capabilities (PTY controls, background task support, or patch APIs).
- All tools operate within **session permissions** and enforce **safety limits** (result caps, timeouts) to prevent resource abuse.
- Tools are invoked through a consistent TypeScript API requiring a `MakaToolContext` parameter that provides session state and cancellation signals.

## Frequently Asked Questions

### How do I enable optional tools like apply_patch in Apache Maka?

Optional tools are automatically added by `buildBuiltinTools()` when the runtime detects specific capabilities. For `apply_patch` (lines 28‑33), the underlying executor must expose an `applyPatch` API. For process control tools, the runtime must provide `backgroundTasks` or `ptyControls` implementations. You cannot manually enable these tools without the corresponding runtime support.

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

**Glob** caps results at 200 files maximum (lines 92‑94). **Grep** enforces three constraints: 50 matches per file, 200 total matches across all files, and a configurable wall‑clock timeout to prevent runaway regular expression searches (lines 96‑98). Both tools respect session permissions and will not return results from unauthorized directories.

### How does the Edit tool ensure safe file modifications?

The **Edit** tool (lines 76‑78) requires a unique string match before performing replacements. It verifies that the search pattern occurs exactly once in the target file, preventing ambiguous substitutions that could corrupt data. If the pattern appears zero times or multiple times, the operation fails, forcing the agent to use more specific search terms or the **Write** tool for full-file replacement.

### Where are the built-in tool definitions located in the source code?

All built-in tool definitions reside in **[`packages/runtime/src/builtin-tools.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/builtin-tools.ts)**. The `buildBuiltinTools()` function (lines 94‑133) serves as the central factory, while individual tool implementations are defined earlier in the same file (lines 24‑98). Type definitions for the tool interface are found in [`packages/runtime/src/tool-runtime.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/tool-runtime.ts).