Apache Maka Built-In Tools: Complete List and Usage Guide

Apache Maka provides 12 core built-in tools including Bash, Read, Write, Edit, Glob, Grep, ApplyPatch, WebSearch, and WebFetch that execute directly in the runtime without external dependencies.

The Maka framework ships with a comprehensive set of built-in tools exposed through the MakaTool interface. These tools form the foundation of agent capabilities, enabling file operations, shell execution, web interactions, and data manipulation. All tools are registered through buildBuiltinTools() in the runtime package and are instantly available to any Maka session.

Complete List of Maka Built-In Tools

The following table enumerates every built-in tool defined in the Apache Maka source code:

Tool Name	Purpose	Source Location
Bash	Executes shell commands with managed or PTY output streaming	packages/runtime/src/builtin-tools.ts (line 628)
Read	Retrieves file contents as a string	packages/runtime/src/builtin-tools.ts (line 354)
Write	Creates or overwrites files with string or binary data	packages/runtime/src/builtin-tools.ts (line 421)
Edit	Applies diff-style modifications to files (git-apply equivalent)	packages/runtime/src/builtin-tools.ts (line 445)
FormatJson	Pretty-prints or manipulates JSON data in-place	packages/runtime/src/builtin-tools.ts (line 489)
Glob	Expands glob patterns into matching file path lists	packages/runtime/src/builtin-tools.ts (line 532)
Grep	Searches file contents or stdin with regular expressions	packages/runtime/src/builtin-tools.ts (line 565)
ApplyPatch	Applies unified diff patches to files	packages/runtime/src/builtin-tools.ts (line 329)
StopBackgroundTask	Terminates tasks started by the runtime	packages/runtime/src/builtin-tools.ts (line 51)
WriteStdin	Sends input to running PTY Bash processes	packages/runtime/src/builtin-tools.ts (line 52)
WebSearch	Queries configured search providers (Google, etc.)	packages/runtime/src/web-search-tool.ts (line 45)
WebFetch	Performs HTTP GET requests and returns response bodies	packages/runtime/src/web-fetch-tool.ts (line 46)

Core File Operations

Read Tool

The Read tool provides synchronous file access for agents. In packages/runtime/src/builtin-tools.ts at line 354, the tool definition specifies a single required parameter: path.

import { invokeBuiltinTool } from '@maka/runtime';

const { content } = await invokeBuiltinTool('Read', {
  path: '/project/src/config.ts'
});

console.log('File contents:', content);

Write Tool

The Write tool at line 421 handles both text and binary output. It overwrites existing files or creates new ones atomically.

await invokeBuiltinTool('Write', {
  path: '/tmp/output.json',
  content: JSON.stringify({ status: 'complete' }, null, 2)
});

Edit Tool

The Edit tool (line 445) applies structured diffs similar to git apply. This enables precise, line-targeted modifications without full file rewrites.

await invokeBuiltinTool('Edit', {
  path: '/project/src/main.ts',
  oldString: 'const DEBUG = false;',
  newString: 'const DEBUG = true;'
});

Shell Execution Tools

Bash Tool

The Bash tool at line 628 delegates to packages/runtime/src/shell-tools.ts for command execution. It supports both managed mode (capture output) and PTY mode (interactive terminals).

const result = await invokeBuiltinTool('Bash', {
  command: 'find . -name "*.ts" -not -path "*/node_modules/*"',
  description: 'Find all TypeScript files'
});

console.log('Files found:', result.stdout.split('\n'));

Process Control Tools

Two specialized tools manage long-running processes:

• StopBackgroundTask (line 51): Sends termination signals to background jobs
• WriteStdin (line 52): Injects input into active PTY sessions

// Start a long-running server
const serverTask = await invokeBuiltinTool('Bash', {
  command: 'npm run dev',
  background: true
});

// Later: send input or terminate
await invokeBuiltinTool('WriteStdin', {
  taskId: serverTask.id,
  input: 'rs\n'  // Restart signal
});

await invokeBuiltinTool('StopBackgroundTask', {
  taskId: serverTask.id
});

Search and Pattern Matching

Grep Tool

The Grep tool at line 565 implements regex-based content search across files or streams.

const matches = await invokeBuiltinTool('Grep', {
  pattern: 'TODO|FIXME',
  path: '/project/src',
  recursive: true
});

matches.results.forEach(m => {
  console.log(`${m.file}:${m.line}: ${m.text}`);
});

Glob Tool

The Glob tool at line 532 expands patterns using standard glob syntax.

const testFiles = await invokeBuiltinTool('Glob', {
  pattern: '**/*.test.{ts,tsx}',
  cwd: '/project'
});

Web Integration Tools

WebSearch Tool

Defined in packages/runtime/src/web-search-tool.ts, this tool queries external search APIs. The tool name is exported as WEB_SEARCH_TOOL_NAME.

const search = await invokeBuiltinTool('WebSearch', {
  query: 'Apache Maka GitHub repository',
  topK: 10
});

console.log('Top result:', search.results[0].url);

WebFetch Tool

The WebFetch tool in packages/runtime/src/web-fetch-tool.ts retrieves raw URL contents. The tool name is exported as WEB_FETCH_TOOL_NAME.

const page = await invokeBuiltinTool('WebFetch', {
  url: 'https://raw.githubusercontent.com/apache/maka/main/README.md'
});

console.log('README length:', page.content.length);

Data Processing Tools

FormatJson Tool

The FormatJson tool at line 489 handles JSON pretty-printing and structural operations.

const formatted = await invokeBuiltinTool('FormatJson', {
  path: '/data/compressed.json',
  indent: 2,
  sortKeys: true
});

ApplyPatch Tool

The ApplyPatch tool at line 329 applies unified diff format patches directly to files.

const patch = `--- a/config.json
+++ b/config.json
@@ -1,3 +1,4 @@
 {
+  "featureFlag": true,
   "version": "1.0.0"
 }
`;

await invokeBuiltinTool('apply_patch', {
  path: '/etc/application/config.json',
  patch: patch
});

Architecture and Registration

All built-in tools are instantiated through buildBuiltinTools() in packages/runtime/src/builtin-tools.ts. This function returns an array of MakaTool objects that the engine registers automatically.

The MakaTool interface requires:

• name: Unique identifier string
• description: Human-readable purpose
• parameters: Zod schema for validation
• invoke: Async execution function

Tool implementations are split across modules for maintainability:

Module	Tools Implemented
builtin-tools.ts	Read, Write, Edit, FormatJson, Glob, Grep, ApplyPatch, Bash registration
shell-tools.ts	Bash execution, StopBackgroundTask, WriteStdin
web-search-tool.ts	WebSearch
web-fetch-tool.ts	WebFetch

Summary

• Apache Maka provides 12 built-in tools covering filesystem, shell, search, web, and data operations
• All tools implement the MakaTool interface and register through buildBuiltinTools() in packages/runtime/src/builtin-tools.ts
• File operations (Read, Write, Edit, ApplyPatch) enable complete code manipulation without external dependencies
• Shell tools (Bash, StopBackgroundTask, WriteStdin) support both simple commands and interactive PTY sessions
• Web tools (WebSearch, WebFetch) require external API configuration but expose unified interfaces
• Pattern tools (Glob, Grep) provide fast repository traversal and content search

Frequently Asked Questions

How do I invoke a built-in tool from a custom skill?

Use the invokeBuiltinTool() utility imported from @maka/runtime. Pass the tool name as first argument and parameters object as second. The function returns a Promise resolving to the tool's output structure.

Are built-in tools available in all Maka deployments?

Yes. Built-in tools ship with the runtime package and require no external services except WebSearch and WebFetch, which need configured API keys for search providers or HTTP endpoints.

What's the difference between Edit and ApplyPatch tools?

Edit performs targeted string replacements with oldString/newString parameters—ideal for small changes. ApplyPatch accepts full unified diff format (the patch parameter) for complex multi-file modifications, matching git apply behavior.

Can I extend Maka with custom tools beyond the built-in set?

Yes. Implement the MakaTool interface and register via the engine's tool registry. Custom tools coexist with built-ins and follow identical invocation patterns.

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