What Features Do Maka's Tools Offer: A Complete Guide to Apache Maka's Built-in Tool Suite

Apache Maka ships with a comprehensive, extensible toolset that enables LLM agents to interact with the host environment through filesystem operations, shell execution, web search, desktop automation, and multi-agent orchestration, all governed by strict permission profiles and sandbox boundaries.

Apache Maka is an open-source framework designed for safe, auditable LLM agent execution. The core builtin-tools are defined in packages/runtime/src/builtin-tools.ts, where each tool conforms to a strict JSON schema validated by zod and is wrapped by ToolRuntime to ensure every invocation is recorded and permission-checked.

File System Operations

Maka provides robust file manipulation capabilities that respect workspace boundaries and permission profiles.

Reading and Writing Files

The Read tool loads text or supported images from the workspace, optionally resolving runtime-resource references. According to the source in builtin-tools.ts (lines 99-101), it handles path normalization and permission checks before returning content.

The Write tool provides atomic file writing with optional snapshotting. As implemented in packages/runtime/src/file-tool-model-output.ts via fileWriteToolResultToModelOutput, it supports both text and binary content with append semantics.

Searching and Listing

For code navigation, Grep leverages ripgrep with a generous wall-clock timeout defined by GREP_TIMEOUT_MS = 120000 (120 seconds) in builtin-tools.ts (lines 92-96). The Glob tool lists files matching patterns within the workspace boundary, enabling efficient file discovery without traversing restricted paths.

Precise File Editing

The Edit tool applies JSON-patch-style modifications to existing files. This tool can be conditionally disabled via the includeEdit configuration flag (lines 78-80 of builtin-tools.ts), allowing administrators to restrict in-place modifications while preserving read access.

Shell Execution and Web Intelligence

Beyond static files, Maka enables dynamic environmental interaction through shell and network tools.

Sandboxed Bash Commands

The Bash tool executes arbitrary shell commands through buildManagedBashTool (lines 50-55 of builtin-tools.ts). Each command runs within the current turn's shell plan and respects the workspace's PermissionProfile. When sandbox boundaries are active, the SandboxManager validates execution contexts and translates paths via normalizeSandboxBoundaryPath.

Web Search Capabilities

Maka offers dual web search implementations. The provider-agnostic WebSearch tool in packages/runtime/src/web-search-tool.ts supports multiple backends including Tavily, OpenAI, and Anthropic APIs. For lightweight deployments, packages/runtime/src/native-web-search-tool.ts provides a built-in search implementation. Both return structured results that respect the context budget pruning limits.

Desktop and Multi-Agent Automation

For complex workflows, Maka includes tools that operate beyond the command line.

Computer-Use for UI Automation

The Computer-Use tool (packages/runtime/src/computer-use-tools.ts) enables real desktop UI interaction, allowing agents to click, type, scroll, and read window states on the host machine. Every action carries strict provenance tracking to maintain audit trails for security-sensitive automation tasks.

Agent Swarm Management

For distributed multi-agent setups, the Agent-Swarm Status tool (packages/runtime/src/agent-swarm-status-tool.ts) queries the health and activity of sub-agents, reporting metrics like active agent counts and task distribution across the swarm.

Task Orchestration and State Management

Maka supports complex multi-turn workflows through high-level planning tools.

Plans and Goals

The Plan and Goal tools, defined in packages/runtime/src/plan-tools.ts and packages/runtime/src/goal-tools.ts, allow models to generate, store, and retrieve structured objectives across conversation turns. These tools maintain state persistence for long-running tasks that span multiple agent invocations.

Scheduled Background Tasks

The Scheduled-Task subsystem (packages/runtime/src/scheduled-task-tools.ts) creates, lists, and cancels background jobs that persist across turns, enabling asynchronous operations like periodic health checks or delayed file processing.

Runtime Safety and Audit Features

Every tool invocation in Maka is governed by a unified safety layer.

Permission and Sandbox Enforcement

Tools respect the workspace's PermissionProfile compiled by @maka/core/permission-profile-compiler. The Sandbox-Boundary tool (packages/runtime/src/sandbox-boundary-tool.ts) defines execution boundaries for tools requiring stricter isolation, such as those running under linux-sandbox.

Durable Tracing and Result Management

Every call generates a ToolResult event stored via packages/runtime/src/tool-output.ts, capturing arguments, outputs, and deterministic toolUseId references. To prevent context window overflow, packages/runtime/src/active-tool-result-prune.ts automatically prunes stale or oversized payloads when they exceed the default token threshold of 2,048 tokens.

Archive Access

For large binary outputs, the ArchiveRead tool (packages/runtime/src/tool-result-archive.ts) allows models to reference tool-result artifacts without pulling full payloads into the model turn, optimizing memory usage during complex workflows.

Extending the Tool Catalog

Maka's tool system is designed for extensibility. Developers can register new capabilities by exporting a MakaTool object and registering it via buildBuiltinTools(). The framework automatically derives the tool catalog through packages/runtime/src/tool-catalog-derive.ts, ensuring new tools inherit the same schema validation, permission checking, and audit logging as built-in primitives.

Code Examples: Invoking Maka Tools

The following JSON payloads demonstrate how models invoke common tools. Each conforms to the schemas generated by the runtime.

Reading a file:

{
  "type": "tool_call",
  "tool_name": "Read",
  "args": {
    "path": "docs/README.md"
  }
}

Writing with atomic semantics:

{
  "type": "tool_call",
  "tool_name": "Write",
  "args": {
    "path": "output/result.txt",
    "content": "Hello from Maka!",
    "append": false
  }
}

Executing sandboxed Bash:

{
  "type": "tool_call",
  "tool_name": "Bash",
  "args": {
    "command": "ls -lR .",
    "timeout_ms": 60000
  }
}

Performing web search:

{
  "type": "tool_call",
  "tool_name": "WebSearch",
  "args": {
    "query": "latest Apache Maka release notes",
    "num_results": 3
  }
}

Automating desktop UI:

{
  "type": "tool_call",
  "tool_name": "ComputerUse",
  "args": {
    "action": "click",
    "selector": "button.submit",
    "wait_for": "#status"
  }
}

Each invocation returns a tool_result message containing structured ToolResultContent and a unique toolUseId for deterministic reference in subsequent turns.

Summary

• Comprehensive Coverage: Maka's built-in tools span filesystem operations (Read, Write, Edit, Glob, Grep), shell execution (Bash), web intelligence (WebSearch), and desktop automation (Computer-Use).
• Safety First: Every tool respects workspace PermissionProfile boundaries and supports sandboxed execution through SandboxManager and SandboxBoundary definitions.
• Auditability: Complete tracing via ToolResult events ensures every tool call, argument, and output is durably recorded with unique toolUseId identifiers.
• Context Management: Automatic pruning in active-tool-result-prune.ts keeps model contexts under token budgets (default 2,048 tokens) while ArchiveRead handles large binary artifacts.
• Extensibility: New tools integrate seamlessly by implementing the MakaTool interface and registering through buildBuiltinTools(), with automatic catalog derivation.

Frequently Asked Questions

How does Maka ensure shell commands don't escape the workspace?

The Bash tool is constructed via buildManagedBashTool in packages/runtime/src/builtin-tools.ts and executes within a managed shell plan that respects the compiled PermissionProfile. When sandbox boundaries are defined through packages/runtime/src/sandbox-boundary-tool.ts, the SandboxManager validates all paths using normalizeSandboxBoundaryPath before execution, preventing directory traversal outside the workspace.

Can I disable specific tools like Edit for read-only environments?

Yes. The Edit tool can be explicitly disabled via the includeEdit configuration flag (lines 78-80 of packages/runtime/src/builtin-tools.ts). Administrators can configure the tool catalog at initialization time through buildBuiltinTools() to exclude file-modifying tools while retaining read-only operations like Read and Grep.

What happens when a tool returns too much data for the context window?

Maka implements automatic Tool-Result Pruning via packages/runtime/src/active-tool-result-prune.ts. When a tool result exceeds the configurable token threshold (defaulting to 2,048 tokens), the runtime truncates or omits the payload to maintain context budget constraints. For large binary artifacts, the ArchiveRead tool allows models to reference stored results without loading full content into the conversation turn.

How do I add a custom tool to Maka's runtime?

Custom tools are added by exporting a MakaTool object with a zod-validated JSON schema and registering it through buildBuiltinTools() in packages/runtime/src/builtin-tools.ts. The framework automatically discovers and catalogs new tools through packages/runtime/src/tool-catalog-derive.ts, ensuring they inherit the same permission enforcement, sandbox awareness, and durable tracing as native tools.

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