Reference: commands

 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
96

# Reference: commands

## `sidekicks`

```text
sidekicks [--config <file>]
```

| Option / variable | Effect |
| --- | --- |
| `--config <file>` | Configuration file to use. Takes precedence over everything else. |
| `SIDEKICKS_CONFIG` | Configuration file when `--config` is not given. |
| (none) | `<user config dir>/sidekicks/config.yaml`, created with comments when missing. |

The order is detailed in the [configuration reference](configuration.md#location).

## `make` targets

| Target | Effect |
| --- | --- |
| `help` | Lists the targets. |
| `install` | `pnpm install` in `frontend/` (macOS and Linux native binaries). |
| `bindings` | Regenerates `frontend/bindings` from the Go services and events (`wails3 generate bindings -clean=true -ts -i`). |
| `frontend` | `install`, then builds `frontend/dist`. |
| `dev` | `wails3 dev`: the application with hot reload. |
| `build` | `wails3 build`: `bin/sidekicks`. |
| `package` | `wails3 package`: on macOS `bin/sidekicks.app`. |
| `package-linux` | `scripts/package.sh linux`: `.deb`, `.rpm`, `.AppImage` and `.tar.gz` for the machine's architecture, into `dist/`. Needs `file` (AppImage) and `rpm`. |
| `package-windows` | `scripts/package.sh windows`: NSIS installer and `.zip` for Windows amd64, cross-built, into `dist/`. Needs `makensis` and `zip`. |
| `release-build` | `scripts/build-release.sh`: on the Mac, every release package into `dist/` and `SHA256SUMS`. |
| `release-tag` | `scripts/tag-release.sh`: tags `v<version>` on `main` and pushes it. |
| `package-macos` | `scripts/package.sh macos`: universal `.dmg` and `.zip` (arm64 + amd64, signed ad hoc), into `dist/`. macOS only. |
| `install-test-config` | `scripts/install-test-config.sh`: writes `examples/test-agents.yaml` at the default configuration location with absolute paths to the repository: each agent is `mm -acp -config agent.yaml` started in its folder, with `afterStop: [<repo>/scripts/agents.sh, unload, <agent>]` to unload its model when it stops, `mm` written with its absolute path (`MM_BIN`, or the one in `PATH`), and the current `PATH` in each agent's `env`; an existing file is kept as `config.yaml.<date>.bak`. |
| `check` | `lint` then `test`. |
| `test` | `test-go`, `test-frontend`, `test-scripts`. |
| `test-go` | `go test ./...` (builds `frontend/dist` first if missing). |
| `test-frontend` | `vitest run` in `frontend/`. |
| `test-scripts` | `scripts/agents_test.sh`, `scripts/check-license-headers_test.sh`, `scripts/package_test.sh` and `scripts/tag-release_test.sh`. |
| `test-real` | `go test -tags realagents -count=1 ./...` — needs `mm` and llmman. |
| `lint` | `lint-go`, `lint-frontend`, `lint-headers`. |
| `lint-go` | golangci-lint v2.14.0 (`tools/go.mod`), configuration `.golangci.yml`. |
| `lint-frontend` | `svelte-check`. |
| `lint-headers` | `scripts/check-license-headers.sh`. |
| `bindings-check` | `bindings`, then fails if `frontend/bindings` differs from the committed version. |

## `scripts/check-license-headers.sh`

```text
scripts/check-license-headers.sh [repository root]
```

Lists the source files (`.go .ts .js .svelte .css .html .sh .py .yml .yaml`, `Makefile`) known to git whose first three lines do not contain `Sidekicks Source-Available License`, and exits 1 if there is one. Not checked: `frontend/bindings`, Wails' `build/` and `Taskfile.yml`, `*.d.ts`, `pnpm-lock.yaml`, `vite.config.ts`, `svelte.config.js`, `agents/`, `*/testdata/*`, `git.sh`, `new.*.sh`, `tag-step.sh`, `.claude/`, `.tickets/`.

## `scripts/package.sh`

```text
scripts/package.sh linux | windows | macos
scripts/package.sh names <system> <arch>
scripts/package.sh version
```

| Command | Effect |
| --- | --- |
| `linux`, `windows`, `macos` | Builds the packages of that system into `dist/` (see the `package-*` targets), then lists `dist/`. |
| `names <system> <arch>` | Prints the file names a build produces, one per line; builds nothing. |
| `version` | Prints `info.version` of `build/config.yml`. |

| System | Files (`<v>` = version) |
| --- | --- |
| `linux` | `sidekicks_<v>_linux_<arch>.deb`, `.rpm`, `.tar.gz`, `Sidekicks-<v>-<x86_64\|aarch64>.AppImage` |
| `windows` | `Sidekicks-<v>-windows-amd64-installer.exe`, `sidekicks_<v>_windows_amd64.zip` |
| `macos` | `Sidekicks-<v>-macos-universal.dmg`, `Sidekicks-<v>-macos-universal.zip` |

## `scripts/build-release.sh`

```text
[LINUX_ARCHES="amd64 arm64"] [SKIP="macos windows linux"] scripts/build-release.sh
```

Empties `dist/`, then builds: macOS with `scripts/package.sh macos` (macOS only), Windows with `scripts/package.sh windows` (needs `makensis`), Linux with `scripts/package.sh linux` in a container per architecture of `LINUX_ARCHES` (default `amd64`), built from `scripts/linux-packages.Dockerfile` (`ubuntu:26.04`, Go of `go.mod`, pnpm of `frontend/package.json`, Wails CLI) with the repository mounted at `/src` and the Go module cache in the volume `sidekicks-gomod-<arch>`. Finally writes `dist/SHA256SUMS`. `SKIP` leaves the systems it names out. Fails when `makensis` is missing or Docker is not running, naming the system to skip.

## `scripts/tag-release.sh`

```text
scripts/tag-release.sh [--remote <name>] [--no-push]
```

Creates the annotated tag `v<version>` (`info.version` of `build/config.yml`, message `Sidekicks <version>`) and pushes it to `--remote` (default `origin`). Refuses when tracked files have changes, when the current branch is not `main`, when `main` differs from `<remote>/main` after a fetch, or when the tag exists locally. Warns, without refusing, when `dist/` misses a package of the version or `SHA256SUMS`. `--no-push` tags locally only.

## CI

`.github/workflows/ci.yml`, on every push and merge request, in an `ubuntu:26.04` container (GTK ≥ 4.10): installs git, a C compiler, the GTK 4 / WebKitGTK 6 build packages, Node and npm from apt, Go from go.dev (version of `go.mod`), pnpm (version of `frontend/package.json`) and the Wails CLI, then runs `make bindings-check` and `make check`.

## Release workflow

`.github/workflows/release.yml`, on the push of a tag `v*`, with `permissions: contents: write`: fails when the tag is not `v` + `info.version` of `build/config.yml`, then creates the release `<tag>` named `Sidekicks <tag>` (`softprops/action-gh-release@v2`, through Rickub's GitHub-compatible API behind `GITHUB_API_URL`), with notes giving the commit, the install guides and the table of the files to expect (from `scripts/package.sh names`). It attaches no file: the packages are attached by hand.