How to Use the Read and Write Tools in Apache Maka: A Complete Guide to Safe File Operations

The Read and Write tools in Apache Maka are sandboxed filesystem utilities defined in packages/runtime/src/builtin-tools.ts that validate inputs with Zod schemas and delegate all I/O to a permission-bound executor running in an isolated worker process.

Apache Maka provides built-in file manipulation tools that let language models safely interact with the filesystem. This guide explains how to use the Read and Write tools programmatically from your JavaScript/TypeScript code or through the command line interface, with technical details drawn directly from the apache/maka source.

How Apache Maka Builds the Read and Write Tools

When a session starts, Maka's runtime assembles its built-in tool set through buildBuiltinTools() in [packages/runtime/src/builtin-tools.ts](https://github.com/apache/maka/blob/main/packages/runtime/src/builtin-tools.ts#L94-L103). This factory function creates an array of MakaTool objects, each containing:

• name — the tool identifier ("Read" or "Write")
• activityKind — classification for telemetry and UI
• inputSchema — Zod schema for runtime validation
• impl — the async function that executes the operation

Both tools share a sandboxed filesystem executor initialized at lines 95-100. This executor enforces session-specific permission profiles and runs file operations in a dedicated worker process, isolating I/O from the model's execution context.

Using the Read Tool in Maka

The Read tool retrieves file contents with support for pagination and runtime resource references.

Read Tool Schema and Validation

The input schema (lines 24-58) accepts two mutually exclusive shapes:

Variant	Fields	Use Case
Path-based	path (string), offset? (number), limit? (number)	Read local files with optional line range
Ref-based	ref (string)	Access runtime resources or attachments

Zod validation ensures only one variant is provided. The readDescription constant (lines 55-57) defines the tool's documentation for model consumption.

Read Tool Implementation Logic

The implementation (lines 61-108) branches based on input type:

1. ref present — routes to classifyRuntimeResourceRef() (lines 147-166) which distinguishes normal paths from maka:runtime references and unsupported refs. Runtime resources or attachments are read through the appropriate handler (lines 61-80).

2. Path-based — validates the path isn't a reserved "runtime" ref, then delegates to createBoundaryFilesystemExecutor (lines 82-98).

The executor returns either:

• Plain text: { content: string }
• Image snapshot: { snapshot: Reference } (lines 99-108)

Errors are normalized through internalFilesystemReadFailure() (lines 40-58) for consistent model-friendly reporting.

Read Tool Code Example: Programmatic Usage

import { buildBuiltinTools } from '@maka/runtime';
import { createLocalWorkspaceExecutor } from '@maka/runtime';

const tools = buildBuiltinTools({ executor: createLocalWorkspaceExecutor() });
const readTool = tools.find(t => t.name === 'Read')!;

// Read first 20 lines of README.md
const result = await readTool.impl({
  path: 'README.md',
  offset: 0,
  limit: 20,
}, {
  cwd: process.cwd(),
  sessionId: 'demo-session',
  turnId: 'turn-1',
  abortSignal: new AbortController().signal,
});

console.log(result.content);

Read Tool CLI Usage

maka run "Read" '{"path":"apps/desktop/README.md","offset":0,"limit":5}'

Using the Write Tool in Maka

The Write tool creates or overwrites files with automatic diff reporting.

Write Tool Schema

The schema (lines 26-30) is straightforward:

{
  path: z.string(),
  content: z.string()
}

Write Tool Implementation

The implementation (lines 31-44) forwards a write operation to the sandboxed executor:

• If the executor returns a diff → reports { kind: 'file_diff', ... }
• Otherwise → reports { kind: 'file_write', path, size }

Failures are wrapped by internalFilesystemWriteFailure() (lines 50-57) with structured error information for model retry logic.

Write Tool Code Example: Programmatic Usage

const writeTool = tools.find(t => t.name === 'Write')!;

await writeTool.impl({
  path: 'tmp/example.txt',
  content: 'Hello, Maka!'
}, {
  cwd: process.cwd(),
  sessionId: 'demo-session',
  turnId: 'turn-2',
  abortSignal: new AbortController().signal,
});

Write Tool CLI Usage

maka run "Write" '{"path":"tmp/example.txt","content":"Hello, Maka!"}'

Read and Write Tool Security Architecture

Both tools rely on [packages/runtime/src/filesystem-executor.ts](https://github.com/apache/maka/blob/main/packages/runtime/src/filesystem-executor.ts), which implements createBoundaryFilesystemExecutor. This component:

• Validates all paths against the session's permission profile
• Runs file operations in a dedicated worker process
• Prevents path traversal and unauthorized access
• Returns structured results through fileWriteToolResultToModelOutput in [packages/runtime/src/file-tool-model-output.ts](https://github.com/apache/maka/blob/main/packages/runtime/src/file-tool-model-output.ts)

The classifyRuntimeResourceRef() helper (lines 147-166) provides defense-in-depth by explicitly categorizing reference types before any I/O occurs.

Common Error Handling in Maka File Tools

Error Function	Location	Trigger Condition
internalFilesystemReadFailure()	builtin-tools.ts:40-58	Sandbox worker read error, invalid ref
internalFilesystemWriteFailure()	builtin-tools.ts:50-57	Sandbox worker write error, permission denied
Zod validation errors	Built into schema	Missing required fields, type mismatches

All errors include machine-parseable codes that the language model can use for automatic retry or user notification.

Summary

• buildBuiltinTools() creates Read and Write tool instances with Zod-validated schemas and sandboxed implementations
• Read tool supports both file paths (with offset/limit) and runtime resource references via ref
• Write tool creates files and reports either file_write or file_diff results depending on executor output
• Both tools delegate to createBoundaryFilesystemExecutor for permission-enforced, worker-isolated I/O
• Error handling produces structured, model-friendly outputs through dedicated failure functions
• Access the CLI with maka run "<ToolName>" '<JSON-input>' for quick testing

Frequently Asked Questions

What permissions does the Maka Read tool require?

The Read tool inherits permissions from the session's permission profile passed to createBoundaryFilesystemExecutor. The executor validates every path against this profile before any filesystem access occurs. If the path falls outside allowed directories, internalFilesystemReadFailure() returns a permission error without attempting I/O.

Can the Maka Write tool modify binary files?

The Write tool schema accepts content as a string, so it is designed for text file creation and modification. Binary data handling would require encoding (e.g., base64) outside the tool or using a different runtime utility. The tool's file_diff response format in [file-tool-model-output.ts](https://github.com/apache/maka/blob/main/packages/runtime/src/file-tool-model-output.ts) is optimized for textual diffs.

How do I test Read and Write tool behavior in Apache Maka?

The Maka repository includes comprehensive test suites: [runtime-event-read-model.test.ts](https://github.com/apache/maka/blob/main/packages/runtime/src/__tests__/runtime-event-read-model.test.ts) validates Read tool behavior and error paths, while [builtin-tools.test.ts](https://github.com/apache/maka/blob/main/packages/runtime/src/__tests__/builtin-tools.test.ts) covers Write tool operations. These tests mock the filesystem executor to verify schema validation, error handling, and result formatting without actual disk I/O.

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