Tutorial: your first launch of Sidekicks

 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
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95

# Tutorial: your first launch of Sidekicks

By the end of this tutorial, you will have written a configuration with one agent, opened Sidekicks with it, started Alice from the interface, read its log, and watched Sidekicks catch a mistake in the file and recover when you fix it.

## Prerequisites

- The development tools of [How to develop the application](../how-to/develop-the-application.md), and `make install` done once.
- `mm` on your `PATH` and llmman running, with Alice's model pulled (see the [first ACP exchange](first-acp-exchange.md) tutorial).
- A terminal at the root of the repository.

## Step 1 — Write a configuration

Type:

```bash
cat > /tmp/sidekicks-tutorial.yaml <<EOF
version: 1
agents:
  - name: alice
    title: Alice (assistant)
    icon: "👩"
    command: $PWD/scripts/agents.sh
    args: [run, alice]
    workspace: $PWD/agents/alice
channels:
  - name: general
    agents: [alice]
EOF
```

We now have a configuration with one agent, Alice, started through the project's script.

## Step 2 — Open Sidekicks with it

Type:

```bash
SIDEKICKS_CONFIG=/tmp/sidekicks-tutorial.yaml make dev
```

After a minute the first time, the Sidekicks window opens. You should see, on the left, **CHANNELS** with `# general`, and **AGENTS** with `👩 Alice (assistant)` and the word "stopped" under it. At the bottom, the status bar says "0 active agents".

## Step 3 — Start Alice

Move the pointer over Alice: a ▶ button appears on the right. Click it.

You should see Alice's dot turn orange ("starting…") then green ("ready"), and the status bar say "1 active agent".

## Step 4 — Read Alice's log

Click **Log** in the status bar. A panel opens at the bottom with Alice's lines, starting with:

```text
mm v1.0.3 | config: …/agents/alice/agent.yaml | provider: llmman | …
[acp] initialize: client "sidekicks" protocolVersion=1 …
```

This is what Alice writes for whoever looks after it; Sidekicks keeps it for you.

## Step 5 — Make a mistake on purpose

Click **Settings** in the status bar. It says "✓ Valid configuration". Now, in a second terminal, break the file:

```bash
sed -i.bak 's/    command:/    comand:/' /tmp/sidekicks-tutorial.yaml
```

Within a second, a red banner appears in the centre, and **Settings** shows:

```text
line 3 — agents[0]: the key "command" is missing
line 6 — agents[0].comand: unknown key "comand"; did you mean "command"?
```

Alice is still listed: Sidekicks keeps the last valid configuration.

## Step 6 — Fix it

```bash
mv /tmp/sidekicks-tutorial.yaml.bak /tmp/sidekicks-tutorial.yaml
```

The banner disappears and Settings shows "✓ Valid configuration" again — no restart needed.

## Step 7 — Stop

Hover Alice and click ■: the dot turns grey. Close the window: had Alice still been running, Sidekicks would have stopped the agent and freed its model.

## What now?

You have run Sidekicks, driven an agent's life and seen how the configuration is checked. To go further:

- All the keys of the file → [Reference: the configuration file](../reference/configuration.md)
- What each state means → [Reference: agents, channels and events](../reference/agents-and-events.md)
- Why agents start and stop this way → [Memory and local models](../explanation/memory-and-local-models.md)