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

> Explore Apache Maka's 10 built-in tools for LLM agents. Enhance your agents with file system operations, shell execution, search, and background tasks.

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

---

**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`](https://github.com/apache/maka/blob/main/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.

```json
{
  "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`](https://github.com/apache/maka/blob/main/packages/runtime/src/builtin-tools.ts#L54).

### Write

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

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

```

Source: [`builtin-tools.ts: L21-L25`](https://github.com/apache/maka/blob/main/packages/runtime/src/builtin-tools.ts#L21).

### 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.

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

```

Implementation: [`builtin-tools.ts: L45-L48`](https://github.com/apache/maka/blob/main/packages/runtime/src/builtin-tools.ts#L45).

### FormatJson

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

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

```

Source: [`builtin-tools.ts: L89-L95`](https://github.com/apache/maka/blob/main/packages/runtime/src/builtin-tools.ts#L89).

## 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.

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

```

Implementation: [`builtin-tools.ts: L28-L31`](https://github.com/apache/maka/blob/main/packages/runtime/src/builtin-tools.ts#L28).

## Search Tools

### Glob

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

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

```

Source: [`builtin-tools.ts: L32-L36`](https://github.com/apache/maka/blob/main/packages/runtime/src/builtin-tools.ts#L32).

### Grep

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

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

```

Implementation: [`builtin-tools.ts: L65-L70`](https://github.com/apache/maka/blob/main/packages/runtime/src/builtin-tools.ts#L65).

## 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.

```json
{
  "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`](https://github.com/apache/maka/blob/main/packages/runtime/src/builtin-tools.ts#L28).

## 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`.

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

```

Source: [`builtin-tools.ts: L24-L26`](https://github.com/apache/maka/blob/main/packages/runtime/src/builtin-tools.ts#L24).

### write_stdin

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

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

```

Source: [`builtin-tools.ts: L24-L26`](https://github.com/apache/maka/blob/main/packages/runtime/src/builtin-tools.ts#L24).

## Tool Assembly and Runtime Integration

All built-in tools are assembled by the **`buildBuiltinTools()`** function at the end of [`builtin-tools.ts`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/packages/runtime/src/tool-runtime.ts)** — defines `MakaTool` and `MakaToolContext` types used throughout the runtime
- **[`packages/runtime/src/shell-tools.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/shell-tools.ts)** — helper functions for constructing Bash and background-task utilities
- **[`packages/runtime/src/filesystem-executor.ts`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/shell-tools.ts) and [`filesystem-executor.ts`](https://github.com/apache/maka/blob/main/filesystem-executor.ts) enforces these constraints at the OS level, preventing escape from designated working directories and resource limits regardless of command content.