> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bor-os.io/llms.txt
> Use this file to discover all available pages before exploring further.

# File editing

# File Editing

BOR reads, writes, and surgically patches files like a coding agent. This is what powers "build a real project", "fix the bug in my repo", and "write a script that…". File tools live in `server/protocol/handlers/file.js`.

## Reading

| Tool                         | Purpose                                                                                                                                                      |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `read_file`                  | Read a file. Relative paths resolve against the project root; absolute paths are allowed. `device:/` maps to your home folder, `bor:/` to BOR-created files. |
| `read_file_in_chunks`        | Read a large file by chunk.                                                                                                                                  |
| `read_batch`                 | Read several files at once.                                                                                                                                  |
| `list_files`                 | List a directory.                                                                                                                                            |
| `search_files`               | Search file contents (regex).                                                                                                                                |
| `list_code_definition_names` | List top-level code definitions in a file/folder.                                                                                                            |

Reads are unrestricted — BOR can read any path the Node process can read.

## Writing

| Tool                           | Purpose                                             |
| ------------------------------ | --------------------------------------------------- |
| `write_file` / `write_to_file` | Create or fully replace a file.                     |
| `replace_in_file`              | Surgically patch a file with SEARCH/REPLACE blocks. |
| `delete_file`                  | Remove a file.                                      |

### `write_file`

The file content rides in the tag body (CDATA-safe). BOR streams it into a live **editor card** in the bubble — one card per file. For a multi-file project, you watch each file fill in and finalize separately.

### `replace_in_file` (surgical edits)

For targeted changes, BOR reads the file, then patches it with a diff of SEARCH/REPLACE blocks:

```
------- SEARCH
const a = 1;
=======
const a = 2;
+++++++ REPLACE
```

The applier matches the SEARCH text exactly (with a line-trimmed fallback) and swaps in the REPLACE text. If the SEARCH text isn't found, BOR is told to re-read the latest file and make the search match exactly — it won't blindly overwrite.

## Where files go

The default destination follows the **`.bor` artifact policy** (see [Storage](../concepts/storage-and-data.md)):

* New projects → `.bor/workspaces/<slug>/`
* Individual scripts → `.bor/files/<slug>.<ext>`
* Images / downloads / reports / exports / scratch → the matching `.bor/` subfolder

…unless you name a path or reference an existing project at a path BOR already knows. BOR always announces where it wrote.

## Write protection

`server/protocol/paths.js` refuses writes to the OS source tree (`server/`, `shell/`, `node_modules/`, `.git/`, lockfiles) and to absolute paths outside `$HOME` (except `/tmp`, `/var/folders`). Narrow carve-outs let the AI write a theme's `user-extras.css` and theme assets. This keeps BOR from damaging its own source while leaving you free.

## Robust parsing

File content can contain anything — `<`, `>`, even `]]>` or stray markup from a confused model. BOR's parser is hardened so this never corrupts a write:

* It anchors on the tool's own close tag, not on the (fragile) CDATA delimiter — so a malformed CDATA close can't make one file swallow the next.
* It accepts content with embedded `]]>` or no CDATA at all.
* It strips BOR's internal turn-structure tags (`<tool_results>` etc.) if a weak model hallucinates them into file content — they never land on disk.

This is why "build me a 6-file app" reliably writes six correct, separate files even on smaller models. See [The protocol](../concepts/the-protocol.md#robustness).

## Use cases

* *"Write a Python script that renames my photos by date."* → one file in `.bor/files/`, run it.
* *"Fix the off-by-one in `/Users/me/app/src/list.ts`."* → `read_file`, then `replace_in_file` in place.
* *"Scaffold a Next.js dashboard."* → a real project in `.bor/workspaces/`, then [run it](running-commands.md) and [preview it](the-browser.md).
* *"Refactor this module."* → read, surgically patch, re-read to verify.