Apache Maka Built-In Tools: Complete Catalog for LLM Agents

Apache Maka provides 10 built-in tools covering file system operations, shell execution, search capabilities, and background task management, all defined in packages/runtime/src/builtin-tools.ts and exposed to LLM agents at runtime.

These tools form the foundational capability layer that Apache Maka agents use to interact with the host environment. Each tool is implemented with sandbox-aware security controls and returns structured, machine-parseable outputs that LLMs can reason over during multi-turn conversations.

Core File System Tools

Apache Maka's file system tools follow a consistent pattern: they operate within active sandbox boundaries and return diagnostic payloads with optional diffs.

Read

The Read tool retrieves file contents or runtime resources via reference. It supports partial reads through offset and limit parameters, making it efficient for large files.

{
  "name": "Read",
  "arguments": { "path": "src/main.ts", "offset": 0, "limit": 10 }
}

When encountering binary files, Read returns an image snapshot rather than raw bytes. Implementation: builtin-tools.ts: L54-L58.

Write

The Write tool performs raw file creation or overwrite operations. It returns a file diff when the underlying filesystem reports changes.

{
  "name": "Write",
  "arguments": { "path": "config.json", "content": "{ \"debug\": true }" }
}

Source: builtin-tools.ts: L21-L25.

Edit

The Edit tool performs precise string replacement with safety guarantees. It validates that old_string appears exactly once and detects whitespace drift between the provided string and actual file content.

{
  "name": "Edit",
  "arguments": {
    "path": "scripts/run.sh",
    "old_string": "node app.js",
    "new_string": "node server.js"
  }
}

Implementation: builtin-tools.ts: L45-L48.

FormatJson

The FormatJson tool validates and canonicalizes JSON files. It supports optional key sorting and returns only diagnostic payloads without raw content.

{
  "name": "FormatJson",
  "arguments": { "path": "package.json", "sort_keys": true }
}

Source: builtin-tools.ts: L89-L95.

Shell Command Tools

Bash

The Bash tool executes arbitrary shell commands within the session's current working directory. All execution respects active sandbox boundaries configurable per-session.

{
  "name": "Bash",
  "arguments": { "command": "ls -l", "timeout_ms": 5000 }
}

Implementation: builtin-tools.ts: L28-L31.

Search Tools

Glob

The Glob tool finds files matching patterns with case-insensitive matching. Results are capped at 200 entries to prevent resource exhaustion.

{
  "name": "Glob",
  "arguments": { "pattern": "docs/**/*.md" }
}

Source: builtin-tools.ts: L32-L36.

Grep

The Grep tool searches file contents using ripgrep with a approximately 2-minute timeout and a maximum of 50 matches per file.

{
  "name": "Grep",
  "arguments": { "pattern": "TODO", "path": "src" }
}

Implementation: builtin-tools.ts: L65-L70.

Extended and Optional Tools

apply_patch (Provider-Specific)

The apply_patch tool applies file changes using provider-specific patch protocols—most commonly the OpenAI apply-patch format. This tool is conditionally enabled: it only appears when the executor implements the applyPatch interface.

{
  "name": "apply_patch",
  "arguments": "diff --git a/file.txt b/file.txt\n--- a/file.txt\n+++ b/file.txt\n@@ -1 +1 @@\n-old\n+new"
}

Source: builtin-tools.ts: L28-L34.

Background Task Management Tools

Apache Maka supports long-running processes through PTY-based background tasks launched via Bash with the background flag. Two dedicated tools manage these tasks:

stop_background_task

Gracefully terminates a previously launched background task using its assigned task_id.

{
  "name": "stop_background_task",
  "arguments": { "task_id": "bg-12345" }
}

Source: builtin-tools.ts: L24-L26.

write_stdin

Sends data to the standard input of a running PTY-based background process, enabling interactive automation scenarios.

{
  "name": "write_stdin",
  "arguments": { "task_id": "bg-12345", "data": "some input\n" }
}

Source: builtin-tools.ts: L24-L26.

Tool Assembly and Runtime Integration

All built-in tools are assembled by the buildBuiltinTools() function at the end of builtin-tools.ts. This function returns a MakaTool[] array that the runtime injects into every LLM conversation turn.

Key supporting files in the tool chain:

• packages/runtime/src/tool-runtime.ts — defines MakaTool and MakaToolContext types used throughout the runtime
• packages/runtime/src/shell-tools.ts — helper functions for constructing Bash and background-task utilities
• packages/runtime/src/filesystem-executor.ts — sandboxed worker that performs read, write, edit, glob, and grep operations

Each tool's arguments are validated against Zod schemas defined alongside the implementations, ensuring type safety at the boundary between LLM output and system execution.

Summary

• Apache Maka built-in tools are defined centrally in packages/runtime/src/builtin-tools.ts and exposed to agents via buildBuiltinTools()
• File system tools (Read, Write, Edit, FormatJson) operate within sandbox boundaries and return structured diffs
• Search tools (Glob, Grep) provide pattern matching with resource limits: 200 results for Glob, 50 matches/file and 2-minute timeout for Grep
• Shell execution via Bash respects sandbox constraints and supports configurable timeouts
• Background task tools enable PTY-based long-running processes with stdin feeding and graceful termination
• apply_patch is conditionally available based on executor capabilities, supporting provider-specific patch formats
• All tools return structured, machine-parseable results that LLM agents can forward or reason over

Frequently Asked Questions

What is the difference between Write and Edit in Apache Maka?

Write performs complete file overwrite operations with raw content, while Edit performs surgical string replacements with uniqueness validation. Edit fails if old_string appears multiple times or if whitespace drift is detected between the provided string and actual file content. Both return file diffs on success.

How does Apache Maka handle large file reads?

The Read tool supports pagination through offset and limit parameters, allowing agents to read files incrementally rather than loading entire contents into context. For binary files, Read automatically returns image snapshots instead of attempting text decoding.

Can I disable specific built-in tools in Apache Maka?

The core built-in tool set is fixed at runtime compilation, but apply_patch is already conditionally excluded when the executor lacks applyPatch support. For custom deployments, you would modify buildBuiltinTools() in builtin-tools.ts to filter the returned MakaTool[] array before runtime injection.

What security boundaries apply to Bash commands?

All Bash execution respects the active sandbox boundary configured for the session. The underlying implementation in shell-tools.ts and filesystem-executor.ts enforces these constraints at the OS level, preventing escape from designated working directories and resource limits regardless of command content.

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