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

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 (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, 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:

// 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: Central definition of all built-in tools and the buildBuiltinTools() factory function.
• 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: Demonstrates how the host composes built-in tools into a session via the builtinTools option.
• 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 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. 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}