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).

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.

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


# 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).

## 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.

## 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)