How to develop the application

 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

# How to develop the application

This guide shows how to set up a machine, run Sidekicks with hot reload and build it. It assumes you know Go and a terminal.

## Install the tools

| Tool | Version | macOS | Linux (Debian/Ubuntu) |
| --- | --- | --- | --- |
| Go | ≥ 1.26 | `brew install go` | distribution package or go.dev |
| Node | ≥ 20 | `brew install node` | distribution package |
| pnpm | 12.11.2 | `npm install -g pnpm@12.11.2` | same |
| Wails CLI | v3.0.0 | `go install github.com/wailsapp/wails/v3/cmd/wails3@v3.0.0` | same |
| Native toolkit | — | `xcode-select --install` | `sudo apt-get install pkg-config libgtk-4-dev libwebkitgtk-6.0-dev` |

Then check with `wails3 doctor`.

## Install the dependencies and run

```bash
make install
SIDEKICKS_CONFIG="$PWD/examples/test-agents.yaml" make dev
```

`make dev` opens the window and reloads the interface when a Svelte file changes, and rebuilds the Go side when a Go file changes. Without `SIDEKICKS_CONFIG`, Sidekicks uses (and creates) the configuration at its default location.

## Build

```bash
make build      # bin/sidekicks
make package    # macOS: bin/sidekicks.app, signed ad hoc
```

## When you change…

- **a Go service or an event payload** (`internal/app`, `internal/events`, `main.go`): run `make bindings` and commit `frontend/bindings` — the CI fails when they are stale.
- **the configuration format**: update `schema/config.schema.json`, `internal/config`, the testdata and the [configuration reference](../reference/configuration.md).
- **a package or its imports**: update `docs/diagrams/packages.drawio` (its generator is described in the [architecture explanation](../explanation/architecture.md)).
- **any source file you create**: start it with the licence header (`make lint-headers` checks it).

## Variants

- **The repository is shared between macOS and a Linux machine or sandbox**: nothing special to do — `frontend/pnpm-workspace.yaml` makes pnpm install the native binaries of both systems in the same `node_modules`. With npm instead of pnpm, each system would break the other.
- **Use the test agents without `SIDEKICKS_CONFIG`** (including the packaged `.app`): `make install-test-config` writes them at the default location, with absolute paths and the environment an application opened from the Finder lacks.
- **Run without hot reload**: `make frontend && go build -o bin/sidekicks . && bin/sidekicks --config examples/test-agents.yaml`.

## See also

- [How to run the tests](run-the-tests.md) · [Reference: commands](../reference/commands.md)
- Why this stack: [The interface stack](../explanation/ui-stack.md)