File System Tools

The opentine.tools.fs module provides four functions for file system access: reading, writing, editing, and listing. All operations are sandboxed to the current working directory by default.

read

Read the contents of a file. Paths are resolved relative to the sandbox directory (defaults to the current working directory).

read_example.py
1from opentine.tools.fs import read
2
3# Read a file's contents — sandboxed to cwd by default
4content = read("src/main.py")
5print(content)

Parameters

  • path (str) — Path to the file to read.
  • sandbox (str | None, default: cwd) — Directory to sandbox file access to. None uses the current working directory; it does not disable root checks.
  • policy (FilesystemPolicy | None, default None) — Explicit read roots, write roots, symlink behavior, and file-size cap.

Returns

The file contents as a string.

read_sandbox.py
from opentine.core import FilesystemPolicy
from opentine.tools.fs import read

# Read from a specific sandbox directory.
content = read("config.yaml", sandbox="/opt/project")

# Or pass an explicit policy with one or more allowed roots.
policy = FilesystemPolicy(roots=("/opt/project", "/opt/shared"))
content = read("/opt/shared/config.yaml", policy=policy)

write

Write content to a file. Parent directories are created automatically if they don't exist.

write_example.py
1from opentine.tools.fs import write
2
3# Write content to a file — creates parent directories automatically
4result = write("output/report.md", "# Research Report\n\nFindings...")
5print(result)  # Confirmation message

Parameters

  • path (str) — Path to the file to write.
  • content (str) — The content to write to the file.
  • sandbox (str | None, default: cwd) — Directory to sandbox file access to.
  • policy (FilesystemPolicy | None, default None) — Explicit write policy. Writes require the destination to resolve underwrite_roots.

Returns

A confirmation string indicating the file was written successfully.

edit

Replace the first occurrence of a string in a file. This is a targeted find-and-replace — useful for making precise changes without rewriting the entire file.

edit_example.py
1from opentine.tools.fs import edit
2
3# Replace the first occurrence of old text with new text
4result = edit(
5    "src/config.py",
6    old='DEBUG = True',
7    new='DEBUG = False',
8)
9print(result)  # Confirmation message

Parameters

  • path (str) — Path to the file to edit.
  • old (str) — The text to find (first occurrence only).
  • new (str) — The replacement text.
  • sandbox (str | None, default: cwd) — Directory to sandbox file access to.
  • policy (FilesystemPolicy | None, default None) — Explicit write policy. Edits require the file to resolve underwrite_roots.

Returns

A confirmation string indicating the edit was applied.

ls

List the contents of a directory. Each entry is prefixed with d for directories or f for files.

ls_example.py
1from opentine.tools.fs import ls
2
3# List the current directory
4listing = ls()
5print(listing)
6# d src
7# d tests
8# f README.md
9# f pyproject.toml
10
11# List a subdirectory
12listing = ls("src/tools")
13print(listing)
14# f __init__.py
15# f web.py
16# f fs.py
17# f shell.py
18# f python.py

Parameters

  • path (str, default ".") — Path to the directory to list.
  • sandbox (str | None, default: cwd) — Directory to sandbox file access to.
  • policy (FilesystemPolicy | None, default None) — Explicit read policy.

Returns

A string with one entry per line, each prefixed with d or f .

Sandboxing

By default, all file system operations are sandboxed to the current working directory. This prevents agents from reading or writing files outside the project. To widen access, pass a specific sandbox root or an explicit FilesystemPolicy.

sandbox_example.py
1from opentine.tools.fs import read, write
2from opentine.core import FilesystemPolicy
3
4# Default: sandboxed to cwd — paths cannot escape the working directory
5content = read("data/input.csv")              # OK: resolves within cwd
6# content = read("../../etc/passwd")          # Blocked: resolves outside cwd
7
8# Custom sandbox: restrict to a specific directory
9content = read("input.csv", sandbox="/tmp/workspace")
10
11# Explicit policy: allow reads from /var/log and writes only under /tmp/workspace
12policy = FilesystemPolicy(
13    roots=("/var/log", "/tmp/workspace"),
14    write_roots=("/tmp/workspace",),
15)
16content = read("/var/log/app.log", policy=policy)
17write("report.txt", "ok", policy=policy)

Using with an Agent

Pass any combination of file system tools to your agent. A coding agent typically needs all four.

coding_agent.py
1from opentine import Agent
2from opentine.models.openai import OpenAI
3from opentine.tools.fs import read, write, edit, ls
4
5agent = Agent(
6    model=OpenAI("gpt-4o"),
7    tools=[read, write, edit, ls],
8    system="You are a coding assistant. Read files, make edits, and write new files as needed.",
9)
10
11run = agent.run_sync("Refactor the database module to use connection pooling")

Next Steps