Reference: scripts/agents.sh

Starts the mm test agents of agents/ with a limit on simultaneous agents, and unloads their models from llmman. Tested by scripts/agents_test.sh.

Commands

Command	Arguments	Effect	Output
`run`	`<agent> [mm args…]`	Takes a slot, runs `mm -acp -config <agents>/<agent>/agent.yaml [mm args…]` from the agent's folder with stdio passed through, then frees the slot and unloads the model.	the agent's ACP stdout; `unloaded: <model>` or `not loaded: <model>` on stderr at exit
`ps`	—	Lists the running agents and the models loaded in llmman.	`agents running (limit N):`, one line per agent (`name (pid P) — model`), `models loaded:`, one line per model
`unload`	`<agent>` or `--all`	Unloads the agent's model, or every loaded model, only if `/api/ps` lists it.	`unloaded: <model>` or `not loaded: <model>` per model
`model`	`<agent>`	Prints the top-level `model:` of the agent's `agent.yaml`.	the model name
`list`	—	Lists the folders of `agents/` that contain an `agent.yaml`.	one name per line

Environment variables

Variable	Default	Effect
`MM_BIN`	`mm` (from `PATH`)	The mm binary.
`LLMMAN_URL`	first of `http://127.0.0.1:17434`, `http://host.docker.internal:17434` that answers `/api/ps`	llmman base URL.
`SIDEKICKS_AGENTS_DIR`	`<repo>/agents`	Folder of the agents.
`SIDEKICKS_RUN_DIR`	`<repo>/.run/agents`	Folder of the slot files (ignored by git).
`SIDEKICKS_MAX_AGENTS`	`2`	Simultaneous agents allowed.
`SIDEKICKS_NO_UNLOAD`	unset	`1` keeps the model loaded when `run` ends.

Slots

A slot is a file <run dir>/<agent>.<pid> holding the agent's model name; <pid> is the agents.sh run process.
A slot whose process no longer exists is deleted the next time slots are counted.
Slot changes happen under a lock directory <run dir>/.lock (5 s timeout).
When run ends, the model is not unloaded if another running slot uses the same model (Bob and Riker share one).

Unloading

unload and the end of run send POST /api/generate with {"model": "<model>", "keep_alive": 0}, only when GET /api/ps lists the model, so that a model is never loaded just to be unloaded.

Exit status and errors

Message on stderr	Status	Cause
`agents.sh: unknown agent 'x' (no …/agent.yaml)`	1	No such agent folder.
`agents.sh: N agent(s) already running, the limit is M:`	1	All slots taken (`run`).
`agents.sh: mm not found (install it or set MM_BIN)`	1	`run` without an mm binary.
`agents.sh: llmman does not answer on … (set LLMMAN_URL)`	1	`ps` or `unload` without llmman. At the end of `run` the message is printed but the status stays mm's.
`agents.sh: could not lock …`	1	Lock held for more than 5 s.
`agents.sh: unknown command 'x'`	1	—

run otherwise exits with mm's status.

 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


# Reference: scripts/agents.sh

Starts the mm test agents of `agents/` with a limit on simultaneous agents, and unloads their models from llmman. Tested by `scripts/agents_test.sh`.

## Commands

| Command | Arguments | Effect | Output |
| --- | --- | --- | --- |
| `run` | `<agent> [mm args…]` | Takes a slot, runs `mm -acp -config <agents>/<agent>/agent.yaml [mm args…]` from the agent's folder with stdio passed through, then frees the slot and unloads the model. | the agent's ACP stdout; `unloaded: <model>` or `not loaded: <model>` on stderr at exit |
| `ps` | — | Lists the running agents and the models loaded in llmman. | `agents running (limit N):`, one line per agent (`name (pid P) — model`), `models loaded:`, one line per model |
| `unload` | `<agent>` or `--all` | Unloads the agent's model, or every loaded model, only if `/api/ps` lists it. | `unloaded: <model>` or `not loaded: <model>` per model |
| `model` | `<agent>` | Prints the top-level `model:` of the agent's `agent.yaml`. | the model name |
| `list` | — | Lists the folders of `agents/` that contain an `agent.yaml`. | one name per line |

## Environment variables

| Variable | Default | Effect |
| --- | --- | --- |
| `MM_BIN` | `mm` (from `PATH`) | The mm binary. |
| `LLMMAN_URL` | first of `http://127.0.0.1:17434`, `http://host.docker.internal:17434` that answers `/api/ps` | llmman base URL. |
| `SIDEKICKS_AGENTS_DIR` | `<repo>/agents` | Folder of the agents. |
| `SIDEKICKS_RUN_DIR` | `<repo>/.run/agents` | Folder of the slot files (ignored by git). |
| `SIDEKICKS_MAX_AGENTS` | `2` | Simultaneous agents allowed. |
| `SIDEKICKS_NO_UNLOAD` | unset | `1` keeps the model loaded when `run` ends. |

## Slots

- A slot is a file `<run dir>/<agent>.<pid>` holding the agent's model name; `<pid>` is the `agents.sh run` process.
- A slot whose process no longer exists is deleted the next time slots are counted.
- Slot changes happen under a lock directory `<run dir>/.lock` (5 s timeout).
- When `run` ends, the model is not unloaded if another running slot uses the same model (Bob and Riker share one).

## Unloading

`unload` and the end of `run` send `POST /api/generate` with `{"model": "<model>", "keep_alive": 0}`, only when `GET /api/ps` lists the model, so that a model is never loaded just to be unloaded.

## Exit status and errors

| Message on stderr | Status | Cause |
| --- | --- | --- |
| `agents.sh: unknown agent 'x' (no …/agent.yaml)` | 1 | No such agent folder. |
| `agents.sh: N agent(s) already running, the limit is M:` | 1 | All slots taken (`run`). |
| `agents.sh: mm not found (install it or set MM_BIN)` | 1 | `run` without an mm binary. |
| `agents.sh: llmman does not answer on … (set LLMMAN_URL)` | 1 | `ps` or `unload` without llmman. At the end of `run` the message is printed but the status stays mm's. |
| `agents.sh: could not lock …` | 1 | Lock held for more than 5 s. |
| `agents.sh: unknown command 'x'` | 1 | — |

`run` otherwise exits with mm's status.