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. Pass None to disable sandboxing.

Returns

The file contents as a string.

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

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.

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.

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.

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. You can customize or disable the sandbox per call.

sandbox_example.py
1from opentine.tools.fs import read, write
2
3# Default: sandboxed to cwd — paths cannot escape the working directory
4content = read("data/input.csv")              # OK: resolves within cwd
5# content = read("../../etc/passwd")          # Blocked: resolves outside cwd
6
7# Custom sandbox: restrict to a specific directory
8content = read("input.csv", sandbox="/tmp/workspace")
9
10# No sandbox: allow any absolute path (use with caution)
11content = read("/var/log/app.log", sandbox=None)

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