How to work with an agent's files and terminal

This guide shows how to look at what an agent produced, change its instructions, delete a file, and run commands in its folder. It assumes Sidekicks runs with a configuration that has agents.

Open an agent's workspace

In the Agents panel, hover the agent and click 📂.
The centre shows the agent: its state, where it runs (local · /path or container name · /path), the channels it belongs to, and the tabs Files, Terminal, Log.
💬 Conversation goes back to the direct conversation; clicking a channel leaves the workspace too.

Read and change a file

In Files, click a folder to open it, a file to read it. Dot files (.git, .mm…) and node_modules are hidden: tick Show hidden files to see them.
Edit the text. ● modified appears; Save (or ⌘S) writes the file, Revert brings back what is on disk.
If the agent changes the file while you edit it, a banner says so: Take their version reloads it (your changes are lost), Keep mine saves yours over it.

The tree and the open file follow the agent's changes by themselves: a file it creates appears within a second (two in a container).

Preview a document or an image

Markdown (.md), AsciiDoc (.adoc, .asciidoc, .asc) and HTML (.html, .htm) files open on their Preview; Edit shows the text, Preview comes back to the rendering of what is in the editor. Images (.png, .jpg, .gif, .webp, .svg…) only have a preview: click the image for its actual size, again to fit it.

Images and links relative to the document are looked for in the agent's folder: a link to another file opens it here, a link to a site opens the browser.
An HTML page is shown in a frame that runs no script and reaches nothing: its images and style sheets of the folder are put inside it, its links do nothing.
The preview follows the agent's changes, like the editor.

Create or delete a file

Create: select a folder (or a file in it), click + New file, type a name, Enter. The file opens, empty.
Delete: hover the entry and click 🗑 (or Delete under the editor), then confirm. On this computer the file goes to the trash — restore it from the Finder if needed. In a container the deletion is final, and the confirmation says so.

Protect files

Some files must not be changed or deleted by mistake. Without writing anything, the agent's instructions (AGENTS.md), its skills (skills/ and all it holds), its configuration file (after --config or serve acp in its args) and, for an agent in a container or a sandbox, the files it is built from (compose.yaml, Dockerfile, sbxenv.yaml named by its runtime.lifecycle) are protected. To protect others, list them under the agent in Settings:

  - name: milo
    protect: [notes/plan.md, "prompts/**"]

A protected file shows 🔒 instead of 🗑 and opens read only; a folder holding one cannot be deleted. Only the configuration lifts a protection (the ones always applied cannot be lifted): the interface never does. The agent, the terminal and the Finder can still change these files.

Run commands in the agent's folder

Click Terminal: a shell opens in the agent's folder — yours on this computer, bash or sh inside a container. Full-screen programs (vim, htop) work and follow the size of the panel. The shell keeps running while you look at Files; leaving the agent's view ends it, with everything it started. When the shell ends (exit), Open a new shell starts another one.

Read the agent's log

Log shows the last lines the agent wrote on its standard error — what explains an error without opening a terminal.

Variants

Agent in a container: see How to run an agent in a Docker container.
Agent in an sbx sandbox: see How to run an agent in an sbx sandbox; each file action takes a second or two.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59


# How to work with an agent's files and terminal

This guide shows how to look at what an agent produced, change its instructions, delete a file, and run commands in its folder. It assumes Sidekicks runs with a configuration that has agents.

## Open an agent's workspace

1. In the **Agents** panel, hover the agent and click **📂**.
2. The centre shows the agent: its state, where it runs (`local · /path` or `container name · /path`), the channels it belongs to, and the tabs **Files**, **Terminal**, **Log**.
3. **💬 Conversation** goes back to the direct conversation; clicking a channel leaves the workspace too.

## Read and change a file

1. In **Files**, click a folder to open it, a file to read it. Dot files (`.git`, `.mm`…) and `node_modules` are hidden: tick **Show hidden files** to see them.
2. Edit the text. **● modified** appears; **Save** (or ⌘S) writes the file, **Revert** brings back what is on disk.
3. If the agent changes the file while you edit it, a banner says so: **Take their version** reloads it (your changes are lost), **Keep mine** saves yours over it.

The tree and the open file follow the agent's changes by themselves: a file it creates appears within a second (two in a container).

## Preview a document or an image

Markdown (`.md`), AsciiDoc (`.adoc`, `.asciidoc`, `.asc`) and HTML (`.html`, `.htm`) files open on their **Preview**; **Edit** shows the text, **Preview** comes back to the rendering of what is in the editor. Images (`.png`, `.jpg`, `.gif`, `.webp`, `.svg`…) only have a preview: click the image for its actual size, again to fit it.

- Images and links relative to the document are looked for in the agent's folder: a link to another file opens it here, a link to a site opens the browser.
- An HTML page is shown in a frame that runs no script and reaches nothing: its images and style sheets of the folder are put inside it, its links do nothing.
- The preview follows the agent's changes, like the editor.

## Create or delete a file

- **Create**: select a folder (or a file in it), click **+ New file**, type a name, Enter. The file opens, empty.
- **Delete**: hover the entry and click **🗑** (or **Delete** under the editor), then confirm. On this computer the file goes to the trash — restore it from the Finder if needed. In a container the deletion is final, and the confirmation says so.

## Protect files

Some files must not be changed or deleted by mistake. Without writing anything, the agent's instructions (`AGENTS.md`), its skills (`skills/` and all it holds), its configuration file (after `--config` or `serve acp` in its `args`) and, for an agent in a container or a sandbox, the files it is built from (`compose.yaml`, `Dockerfile`, `sbxenv.yaml` named by its `runtime.lifecycle`) are protected. To protect others, list them under the agent in **Settings**:

```yaml
  - name: milo
    protect: [notes/plan.md, "prompts/**"]
```

A protected file shows 🔒 instead of 🗑 and opens read only; a folder holding one cannot be deleted. Only the configuration lifts a protection (the ones always applied cannot be lifted): the interface never does. The agent, the terminal and the Finder can still change these files.

## Run commands in the agent's folder

Click **Terminal**: a shell opens in the agent's folder — yours on this computer, bash or sh inside a container. Full-screen programs (`vim`, `htop`) work and follow the size of the panel. The shell keeps running while you look at **Files**; leaving the agent's view ends it, with everything it started. When the shell ends (`exit`), **Open a new shell** starts another one.

## Read the agent's log

**Log** shows the last lines the agent wrote on its standard error — what explains an error without opening a terminal.

## Variants

- **Agent in a container**: see [How to run an agent in a Docker container](run-an-agent-in-docker.md).
- **Agent in an `sbx` sandbox**: see [How to run an agent in an sbx sandbox](run-an-agent-in-a-sandbox.md); each file action takes a second or two.

## See also

- [Workspaces and terminals — explanation](../explanation/workspaces-and-terminals.md)
- [Reference: workspaces](../reference/agents-and-events.md#workspaces-milestone-m4)