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

> Explore Apache Maka's 12 built-in tools like Bash, Grep, and WebSearch. Execute commands directly in the runtime without external dependencies. Master Maka's powerful utilities.

- Repository: [The Apache Software Foundation/maka](https://github.com/apache/maka)
- Tags: how-to-guide
- Published: 2026-08-31

---

**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`](https://github.com/apache/maka/blob/main/packages/runtime/src/builtin-tools.ts) (line 628) |
| **Read** | Retrieves file contents as a string | [`packages/runtime/src/builtin-tools.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/builtin-tools.ts) (line 354) |
| **Write** | Creates or overwrites files with string or binary data | [`packages/runtime/src/builtin-tools.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/builtin-tools.ts) (line 421) |
| **Edit** | Applies diff-style modifications to files (git-apply equivalent) | [`packages/runtime/src/builtin-tools.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/builtin-tools.ts) (line 445) |
| **FormatJson** | Pretty-prints or manipulates JSON data in-place | [`packages/runtime/src/builtin-tools.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/builtin-tools.ts) (line 489) |
| **Glob** | Expands glob patterns into matching file path lists | [`packages/runtime/src/builtin-tools.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/builtin-tools.ts) (line 532) |
| **Grep** | Searches file contents or stdin with regular expressions | [`packages/runtime/src/builtin-tools.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/builtin-tools.ts) (line 565) |
| **ApplyPatch** | Applies unified diff patches to files | [`packages/runtime/src/builtin-tools.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/builtin-tools.ts) (line 329) |
| **StopBackgroundTask** | Terminates tasks started by the runtime | [`packages/runtime/src/builtin-tools.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/builtin-tools.ts) (line 51) |
| **WriteStdin** | Sends input to running PTY Bash processes | [`packages/runtime/src/builtin-tools.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/builtin-tools.ts) (line 52) |
| **WebSearch** | Queries configured search providers (Google, etc.) | [`packages/runtime/src/web-search-tool.ts`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/packages/runtime/src/builtin-tools.ts) at line 354, the tool definition specifies a single required parameter: `path`.

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

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

```typescript
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`](https://github.com/apache/maka/blob/main/packages/runtime/src/shell-tools.ts) for command execution. It supports both managed mode (capture output) and PTY mode (interactive terminals).

```typescript
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

```typescript
// 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.

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

```typescript
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`](https://github.com/apache/maka/blob/main/packages/runtime/src/web-search-tool.ts), this tool queries external search APIs. The tool name is exported as `WEB_SEARCH_TOOL_NAME`.

```typescript
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`](https://github.com/apache/maka/blob/main/packages/runtime/src/web-fetch-tool.ts) retrieves raw URL contents. The tool name is exported as `WEB_FETCH_TOOL_NAME`.

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

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

```typescript
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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/builtin-tools.ts) | Read, Write, Edit, FormatJson, Glob, Grep, ApplyPatch, Bash registration |
| [`shell-tools.ts`](https://github.com/apache/maka/blob/main/shell-tools.ts) | Bash execution, StopBackgroundTask, WriteStdin |
| [`web-search-tool.ts`](https://github.com/apache/maka/blob/main/web-search-tool.ts) | WebSearch |
| [`web-fetch-tool.ts`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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.