Built-in tools

The read, write, edit, and bash tools the agent uses to work in your project.

Tools are the actions the agent can take in your working directory. The model decides when to call them; Tau executes them and streams the results back. Tau ships four built-in coding tools: read, write, edit, and bash.

All paths are resolved against the session’s working directory (--cwd, or the directory you launched Tau from).

read

Reads a file from disk.

{ "path": "README.md", "offset": 1, "limit": 40 }

For text files, read returns UTF-8 content, applies offset/limit, and truncates to at most 2,000 lines or 50 KB (whichever comes first), appending a hint like [42 more lines in file. Use offset=101 to continue.]. Supported images (JPEG, static PNG, GIF, WebP, and BMP) are detected from their file content and sent to vision-capable models as image attachments. BMP files are converted to PNG. Tau validates images and, when necessary, resizes them without upscaling or changing their aspect ratio. The processed attachment is limited to 2,000 pixels on either side and 5 MB. Processing also rejects source files above 50 MB or 40 million pixels. Animated PNG and JPEG XL inputs receive explicit unsupported-format notices. If decoding, conversion, or resizing cannot produce a safe attachment, Tau returns a clear omission notice.

When the active model does not accept images, read returns an explicit text-only notice that says the image contents are unavailable and recommends switching to a vision-capable model. It does not attach or process the image. Provider serialization applies the same defensive downgrade to image blocks from older sessions or other tools. This avoids invalid requests and reduces pressure on text-only models to invent a visual description.

The Textual TUI shows this notice, but does not render images inline; native terminal-image rendering remains outside the read tool’s provider-neutral contract.

Fails when path is missing/invalid, the file doesn’t exist, the path is a directory, offset is past the end, or the file is neither UTF-8 text nor a supported image.

write

Creates or overwrites a complete UTF-8 text file.

{ "path": "src/example.py", "content": "print('hello')\n" }

Creates missing parent directories and overwrites any existing file. Writes to the same path are serialized within a process, so concurrent write/edit calls on one file don’t interleave.

edit

Applies exact text replacements to one file.

{
  "path": "src/example.py",
  "edits": [
    { "oldText": "print('hello')", "newText": "print('hello, Tau')" }
  ]
}

Each oldText must be non-empty, match exactly (whitespace included), appear exactly once, and not overlap another edit. All edits validate before anything is written — if any fails, the file is left unchanged. Line endings are normalized for matching and the original dominant ending is restored. Successful results include a diff, a unified patch, and the first changed line number.

bash

Runs a shell command in the working directory.

{ "command": "pytest -q", "timeout": 30 }

Combines stdout and stderr, succeeds on exit code 0, and returns the tail of large output (truncated to 2,000 lines / 50 KB; the full output is written to a temp .log file whose path is included in the result). On POSIX, a timeout kills the whole process group.

Choosing the right tool

• read — inspect files (instead of cat/sed).
• write — new files or complete rewrites.
• edit — precise changes to an existing file.
• bash — tests, linters, searches, project inspection.