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

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

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, which serves as the single source of truth for tool shapes throughout the codebase. The buildBuiltinTools factory function in 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, producing JSON representations suitable for LLM provider consumption. Additionally, 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:

// 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: Central definition of all local tools and the buildBuiltinTools factory.
• packages/runtime/src/tool-runtime.ts: Exports the MakaTool interface, establishing the contract for tool parameters and results.
• packages/runtime/src/model-protocol.ts: Declares ModelToolDefinition and ModelToolSet for LLM serialization.
• packages/mcp/src/tool-definition.ts: Manages tool fingerprinting for the Maka Control Protocol.
• 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 and implement the MakaTool interface from 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 (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 defines a fixed set of local tools through the buildBuiltinTools factory. While the MakaTool interface in 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.

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

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