# Files, attachments and edits

> Give Code the right files and images, use line-specific mentions, review edits, and understand the boundary between workspace access and attachments.

Source: https://kaitoi.io/docs/cli/files-and-edits/
Section: Kaitoi CLI / Working with Kaitoi Code
Written for: Anyone asking Code to inspect or change local files.
Prerequisites: Kaitoi CLI installed; A workspace you are ready to trust
Last reviewed: 2026-10-24

---

Start with the folder Code should work in, then provide the smallest useful
context. This guide covers CLI **0.9.0**. A path in your prompt is not an
instruction to upload your whole computer.

## Set the workspace

In your terminal, start Code with an explicit directory:

```bash
kaitoi code --workspace /path/to/project
```

Read the workspace trust prompt. Trust enables the local file tools and project
instructions for that folder. Inside Code, `/workspace` shows the folder;
`/workspace /path/to/project` changes it and applies the new folder's trust and
extension settings. `/status` helps confirm what is active.

Agent file tools enforce workspace boundaries, protected paths, and file policy.
Trust does not mean every file is readable, every operation is approved, or
all context stays on this machine. Allowed content can be sent to your selected
[model server](/docs/cli/models/).

## Mention a file, folder, or line range

In a trusted workspace, type a mention in your message:

```text
Explain @src/banner.ts:12-18 before proposing a change.
Compare @src/components with @"design notes.md".
```

| Mention               | Context supplied                                            |
| --------------------- | ----------------------------------------------------------- |
| `@path`               | A bounded read of the file, or a folder listing.            |
| `@path:12`            | A read starting at line 12, normally up to 200 lines.       |
| `@path:12-40`         | The requested line range, subject to normal read limits.    |
| `@"path with spaces"` | A quoted path; an optional line range can follow the quote. |

The host reads recognized mentions before the model's first step, using the
normal file-read policy and redaction. An image mention becomes an attachment.
An email address is not a mention, and a nonexistent or out-of-workspace path
is not silently imported. Without workspace trust, mentions are sent as plain
text. Read attachment notices: at most ten mentions are attached per message,
and image attachments share a four-image limit.


In the example workspace, src/banner.ts contains a title and subtitle near
lines 12–18. The prompt asks about @src/banner.ts:12-18. A recognized mention
adds a bounded read of that range before the model responds. It is context for
the request, not approval to edit the file. The source snippet is illustrative.

The complete illustrated range declares title, subtitle, place, starting time, entry price and action, then exports those values. The context attachment contains that same literal selected range; the later editing boundary remains separate.

*Figure: A line-range mention connects a precise source excerpt to the prompt.*

## Attach an image deliberately

You can mention a supported image in the workspace, use `/image` inside Code,
or attach an image at launch:

```bash
kaitoi code --image "design reference.png" "Describe the spacing in this layout"
```

For the interactive command, use `/image path.png` with optional instructions,
or `/image` for the clipboard flow. Use the startup `--image` form for paths
containing spaces. Explicit image attachments can come from outside the
workspace; they are supplied by you, separately from agent file access. Image
size/type limits and the selected model's vision support still apply.

## Ask for an edit you can review

Describe the behavior to change, the files or area in scope, and what must stay
unchanged. In Build mode, inspect the proposed diff or file operation and its
permission choice. Approval to edit is distinct from permission to run commands,
delete or move files, transfer files, or publish work.

Some edits may already be covered by a session grant or edit auto-approval.
Use `/permissions` to inspect grants; do not infer that an action bypassed
policy just because it did not ask again. After the change, review the actual
files and run checks appropriate to the task. A written file is not evidence
that the behavior works. If an edit is refused because the file changed since
it was read or while approval was pending, reread the file and review a fresh
proposal instead of forcing an overwrite.

## Move files between Code and Kaitoi

Ask Code to upload a specific workspace file when a graph needs it as an input.
The upload returns a Kaitoi file ID. To bring a generated result back, ask Code
to download that file ID into the workspace and report its saved path. Local
Runtime outputs are local paths, not hosted Kaitoi file IDs. The current Code
host does not wire the downloader required by `local.save_runtime_file`; use
the reported Runtime paths or Runtime's output-directory option to retain them.
These transfers have their own permission rules. A successful remote run does
not establish that the file was downloaded or saved successfully.

For recovery, use [checkpoints and rewind](/docs/cli/checkpoints/), and read the
reported restore result. They supplement version control; they do not reverse
every command, external side effect, or file change.