Files, attachments and edits.

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:

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.

#Mention a file, folder, or line range

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

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.

#Attach an image deliberately

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

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, and read the reported restore result. They supplement version control; they do not reverse every command, external side effect, or file change.