pi-spaces 0.0.0-stage → 0.16.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,3 +1,628 @@
1
- # Temporary Holding Version
1
+ # 🪐 pi-spaces
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ ![pi-spaces: several Pi agent homes side by side](assets/preview.png)
4
+
5
+ Named spaces for [Pi](https://pi.dev): keep several agent homes side by side and switch between them from inside Pi.
6
+
7
+ A space is a complete Pi agent home: its own sign-ins, packages, settings, skills and sessions. Use one per client, per experiment, or to try a package without touching your everyday setup. A space is a root folder with its agent home, `agent`, inside it, like Pi's own `~/.pi/agent`, so a program that keeps more per space has room for it next to `agent/`.
8
+
9
+ ```text
10
+ /space new work Created space "work" at ~/.pi/spaces/work (its agent home is ~/.pi/spaces/work/agent).
11
+ /space Switch to space
12
+ → base
13
+ work
14
+ Pi restarts in "work"; the status line shows space: work
15
+ ```
16
+
17
+ It relies only on Pi's own `PI_CODING_AGENT_DIR` variable, so it works with plain Pi and with any program that runs Pi (a launcher such as gentle-shell).
18
+
19
+ > **Moved:** these packages were `@jals1212/pi-spaces` and `@jals1212/pi-spaces-cli` up to 0.15. Replace `npm:@jals1212/pi-spaces` with `npm:pi-spaces` in your `settings.json` files (keep only one), and reinstall the command as `pi-spaces-cli`.
20
+
21
+ ## Two packages: use either one, or both
22
+
23
+ pi-spaces ships as two independent npm packages. They read the same spaces and the same [config file](#profiles), but neither requires the other: install the one that fits how you start Pi, or both.
24
+
25
+ | | The Pi extension | The `pi-space` shell command |
26
+ | --- | --- | --- |
27
+ | Package | `pi-spaces` | `pi-spaces-cli` |
28
+ | Install | `pi install npm:pi-spaces` | `npm install -g pi-spaces-cli` |
29
+ | Where you use it | Inside Pi | In your shell, before Pi starts |
30
+ | What it gives you | `/space` (list, create, switch, rename, remove), `pi --space <name>`, the `🪐` status line, the [`<pi_space>` prompt section](#what-the-model-is-told), the [Herdr sidebar](#commands-in-pi) and the [`pi-spaces` skill](#the-pi-spaces-skill) | A picker of the spaces of every profile, `new`, `setup`, `rename`, `remove`, `migrate`, package commands across spaces (`update --every`), shell completion |
31
+ | Works on its own | Always | With a profile whose `commands.space` has `{home}` (see below) |
32
+
33
+ ### Which one do I need?
34
+
35
+ - **You start plain `pi` and want to switch from inside it**: the extension alone.
36
+ - **You start Pi through a launcher that takes its home as an option** (`gentle-shell --home <dir>`, `my-launcher --home <dir>`): the command alone is enough. Give the launcher a [profile](#profiles) whose `commands.space` has `{home}`; `pi-space` then starts the launcher directly in the space's home and sets the space's variables itself, so Pi needs nothing installed. See [Example: gentle-shell](#example-gentle-shell).
37
+ - **You want both**: pick a space from the shell, switch from inside Pi, and see the space in the status line. Install both; they share everything.
38
+
39
+ ### What each one cannot do alone
40
+
41
+ **The command without the extension:**
42
+
43
+ - With the built-in `pi` profile (or any `commands.space` without `{home}`), starting a space runs `pi --space <name>`, and the package commands run `pi --space <name> update`. Only the extension understands `--space`, so these need it in the base home. Commands that only touch folders (`new`, `setup`, `rename`, `remove`, `migrate`, `list` without a space, `init`) never need it.
44
+ - Inside Pi there is no `/space`, no status line, and the model gets no `<pi_space>` section. The variables `PI_SPACE` and `PI_SPACE_HOME` are still set for Pi's tools.
45
+ - `pi-space new` asks whether the new space's `agent/settings.json` declares the extension (Enter is yes), and Pi installs what that file declares the first time it runs there. Answer no, or pass `--no-extension`, to keep the space without it; `--extension` declares it without asking, and without a terminal it is declared. `/space new` always declares it, since it runs inside the extension.
46
+
47
+ **The extension without the command:**
48
+
49
+ - No picker or completion from the shell; use `pi --space <name>` and `/space` instead.
50
+ - No `setup`, `migrate` or `--every` across spaces and profiles; `/space new` names the `pi-space setup` call to run, and `pi --space <name> update` updates one space at a time.
51
+
52
+ ## Requirements
53
+
54
+ - Pi 1.4 or later (the extension).
55
+ - Node 20 or later (the command).
56
+
57
+ ## Install
58
+
59
+ The extension, into the Pi home you start (a launcher with its own home installs it through its own install command):
60
+
61
+ ```sh
62
+ pi install npm:pi-spaces
63
+ ```
64
+
65
+ The command, globally from npm (`pi install` does not put commands on your `PATH`):
66
+
67
+ ```sh
68
+ npm install -g pi-spaces-cli
69
+ ```
70
+
71
+ Each package is installed and updated on its own.
72
+
73
+ ## Quick start
74
+
75
+ With the extension, inside Pi:
76
+
77
+ ```text
78
+ /space new work create a space
79
+ /space pick a space; Pi restarts in it
80
+ /space switch base back to the home Pi started with
81
+ ```
82
+
83
+ With the extension, from your shell:
84
+
85
+ ```sh
86
+ pi --space work # start Pi in "work"
87
+ pi --space work "review this branch" # with a prompt
88
+ pi --space work update # update the packages of "work"
89
+ ```
90
+
91
+ With the command, from your shell:
92
+
93
+ ```sh
94
+ pi-space # pick a space of any profile: arrows, Enter, type to filter
95
+ pi-space new pi/work # create a space of the profile "pi"
96
+ pi-space pi/work # start Pi in it
97
+ pi-space remove pi/work # delete it, after asking; keeps a backup unless told not to
98
+ pi-space update --every # update the packages of base and of every space of every profile
99
+ ```
100
+
101
+ A new space is a folder with an `agent/` folder inside it, empty except for `agent/settings.json`, which declares this package so `/space` works inside it. Sign in and install packages there as you would in a fresh Pi. Spaces made by an older version have no `agent/` folder and keep working as they are; see [Moving an old space](#moving-an-old-space).
102
+
103
+ ## Commands in Pi
104
+
105
+ | Command | What it does |
106
+ | --- | --- |
107
+ | `/space` | Opens a list of the other spaces and restarts Pi in the one you pick. Without the interactive terminal it lists them instead. |
108
+ | `/space list` | Lists `base` and every space, with `*` on the active one. |
109
+ | `/space new <name>` | Creates an empty space (its folder, with `agent/` inside). When a setup command is set (the profile's `commands.setup`, or `PI_SPACES_SETUP`), it names `pi-space setup <profile>/<name>` to run from a shell, with this Pi's profile (`pi` when none matches). |
110
+ | `/space switch <name>` | Restarts Pi in that space. `base` is the home Pi started with. |
111
+ | `/space switch` | Same as `/space`. |
112
+ | `/space rename <old> <new>` | Renames a space. The active space cannot be renamed. |
113
+ | `/space remove <name> [--yes] [--no-backup]` | Deletes a space after asking, then asks whether to keep a backup in `<spaces folder>/.backups` (keeping one is first in the list; dismissing the question keeps the space). `--yes` skips the questions and keeps a backup; it is required without a dialog (print and JSON modes). `--no-backup` deletes without one. |
114
+ | `pi --space <name>` | Starts Pi directly in a space, keeping the prompt and every other option. |
115
+ | `pi --space <name> <command> [args...]` | Runs one of Pi's package commands (`install`, `remove`, `uninstall`, `update`, `list`) in a space, or in the base home with `base`: `pi --space work update --extensions`, `pi --space work install npm:<package>`. |
116
+
117
+ The status line shows `🪐 <profile>/<name>` while a space is active: the name `pi-space` takes, with the [profile](#profiles) of the running Pi (`pi` when no profile matches its base home), so `🪐 launcher/work` and `🪐 pi/work` are told apart. `/space` cannot change the profile: a switch starts the same program again. In the base home it shows `🪐 <profile>/base` when pi-spaces opened it (`pi --space base`, `pi-space pi/base`, or `/space switch base`), and nothing when Pi was started plainly. 🪐 is pi-spaces' own emoji.
118
+
119
+ **Herdr sidebar**: the same text also shows in [Herdr](https://herdr.dev)'s Agents sidebar, next to the agent. Display only: the agent's state in Herdr does not change.
120
+
121
+ - In a Herdr pane (`HERDR_ENV=1`, `HERDR_PANE_ID`, `HERDR_SOCKET_PATH`) it is the pane's `space` metadata token, reported again every 10 seconds with a 30-second TTL, so it goes away when Pi does, and cleared when the session ends. To show it, add `$space` to a row of the Agents sidebar in Herdr's `config.toml`, then run `herdr server reload-config`:
122
+
123
+ ```toml
124
+ [ui.sidebar.agents]
125
+ rows = [
126
+ ["state_icon", "machine", "workspace", "tab"],
127
+ ["agent", "$space"],
128
+ ]
129
+ ```
130
+
131
+ - In a terminal of the Herdr app (herdr-core sets `HC_TERMINAL_ID`) it is the terminal's `space` label, set with `hc label <terminal> space=<text>`. While the session lasts it follows `hc events --terminal <terminal>` and sets the label again when it goes missing or changes: a set that failed while herdr-core was starting, or a core restarted when the Herdr app closed and opened. When that stream ends it follows it again (after 1, 2, 5, 10, then every 30 seconds), and its first snapshot restores the label. A label has no TTL: the session removes it when it ends, and a session that starts in another terminal first removes it from the one it leaves, so a Pi killed without ending can leave the label until the next session replaces it. Both sidebars are served when both environments are present. The Herdr app's shipped Agents panel does not show labels, so showing it takes a copy of that panel (mods and layouts shipped with Herdr are read-only; a clone is yours):
132
+
133
+ 1. Clone the layout you use and the `agents` mod:
134
+
135
+ ```sh
136
+ herdr-app do layout.clone '{"name":"main","as":"my-layout"}'
137
+ herdr-app do mod.clone '{"name":"agents","as":"my-agents"}'
138
+ ```
139
+
140
+ 2. In `~/.config/herdr-app/layouts/my-layout.json`, point the Agents block to the clone: `"content": { "mod": "my-agents" }`.
141
+ 3. In `~/.config/herdr-app/mods/my-agents/main.js`, import `terminals` from `"herdr"`, read each terminal's labels by address, and add the space to the agent's row when it has a `space` label:
142
+
143
+ ```js
144
+ // where the rows are built: the labels of every terminal, by address
145
+ const labelsOf = new Map(terminals().map((x) => [x.address, x.labels ?? {}]))
146
+
147
+ // in the row of agent `a` (`t` is the mod's theme())
148
+ const space = labelsOf.get(a.address)?.space ?? ''
149
+ // ...the row...
150
+ .when(Boolean(space), (el) => el.child(div().flex_none().text_size(12).text_color(t.dim).child(space)))
151
+ ```
152
+
153
+ 4. Check the mod, which the app reloads on save: `herdr-app check ~/.config/herdr-app/mods/my-agents`.
154
+
155
+ To try the mod without Pi, set a label by hand in a Herdr app terminal with `hc label "$HC_TERMINAL_ID" space="🪐 pi/test"`, and remove it with `hc label "$HC_TERMINAL_ID" space=`.
156
+
157
+ Choosing an argument such as `switch` from the `/space ` suggestions only fills the line; press Enter again to run it. `/space` and Enter opens the picker in one step.
158
+
159
+ **Names**: lowercase letters, digits, `-` and `_`, starting with a letter or digit, at most 64 characters. `base` is reserved, and so are the command words `list`, `new`, `remove`, `rename`, `switch`, `update`, `install`, `uninstall`, `setup` and `completion`.
160
+
161
+ ## The `pi-space` command
162
+
163
+ The `pi-spaces-cli` package adds a `pi-space` command to your shell; it works with or without the extension (see [Two packages](#two-packages-use-either-one-or-both)). It names every space as `<profile>/<name>` (`pi/work`, `my/base`): the profile is an entry of the [config file](#profiles), and `pi` (plain Pi) is always there.
164
+
165
+ | Command | What it does |
166
+ | --- | --- |
167
+ | `pi-space` | Opens a picker of the spaces of every profile and starts Pi in the one you choose. |
168
+ | `pi-space <profile>/<name> [pi args...]` | Starts Pi in a named space; `<profile>/base` runs the profile's `commands.base` as it is. |
169
+ | `pi-space new <profile>/<name> [--extension\|--no-extension]` | Creates a space, asking whether it declares the extension, then runs the profile's setup command. |
170
+ | `pi-space setup <profile>/<name\|--every>` | Runs the setup command again. |
171
+ | `pi-space rename <profile>/<old> <new>` | Renames a space. |
172
+ | `pi-space remove <profile>/<name>` | Deletes a space, after asking. |
173
+ | `pi-space migrate <profile>/<name\|--every>` | Gives an old space the [`agent/` layout](#moving-an-old-space). |
174
+ | `pi-space list` | Lists the spaces of every profile. |
175
+ | `pi-space list\|update\|install\|uninstall <profile>/<name\|--every> ...` | Runs Pi's package commands in a space, in a profile's spaces, or (`--every` alone) in every profile's. |
176
+ | `pi-space init` | Writes a starter config file. |
177
+
178
+ How it starts Pi depends on the profile's `commands.space`:
179
+
180
+ - **With `{home}`** (`my-launcher --home {home}`): it runs that command directly in the space's home and sets the space's variables itself, so the extension is not needed. `pi-space launcher/work --version` runs `my-launcher --home <that home> --version`.
181
+ - **Without `{home}`**, and for the built-in `pi` profile: it runs `pi --space <name> [command]` (or the filled-in command), and the extension in the base home does the switch.
182
+
183
+ The profile says which program to run, where its spaces live and how to prepare a new space; `--command`, `--dir` and `--setup` override those for one call, for one named profile. The command does not read `PI_SPACES_COMMAND`, `PI_SPACES_DIR` or `PI_SPACES_SETUP` as settings: they are what it hands to the Pi it starts. See [`cli/README.md`](cli/README.md) for every option, completion and the exit status.
184
+
185
+ ## Profiles
186
+
187
+ A **profile** describes one program that runs Pi (plain Pi is one too): where its agent home is, the commands that start it, where its spaces live, how to prepare a new space, and the variables it needs per space. Profiles live in an optional file, in TOML or JSON, so you do not need shell variables or functions to tell pi-spaces about a program. Without the file, nothing changes: this is exactly how pi-spaces behaves without any configuration.
188
+
189
+ The extension uses the profile whose `home` is the base home Pi started with (the one `base` goes back to); inside a space that is the home the space came from. The optional `pi-space` command ([`cli/README.md`](cli/README.md)) reads the same file, and the profile is the first word of every space it takes: `pi-space ml/work`. It does not use `default`: the profile is always named.
190
+
191
+ ### The file
192
+
193
+ | | |
194
+ | --- | --- |
195
+ | Location | The first that exists of `$XDG_CONFIG_HOME/pi-spaces/config.toml`, `$XDG_CONFIG_HOME/pi-spaces/config.json`, `~/.pi-spaces/config.toml` and `~/.pi-spaces/config.json` (`XDG_CONFIG_HOME` unset, blank or relative means `~/.config`, so `~/.config/pi-spaces/config.toml`: easy to keep in your dotfiles); with none, `~/.pi-spaces/config.toml`, where `pi-space init` writes. On Windows `~` is `%USERPROFILE%` (`C:\Users\<you>\.config\pi-spaces\config.toml`). The first file found wins. When `config.toml` and `config.json` are in the same folder, `config.toml` is read and a warning names the `config.json` that is ignored (remove one of them). Nothing moves or creates any file. |
196
+ | Format | TOML when the file name ends in `.toml`, else JSON (with comments). Both have the same keys and the same checks; a JSON object is a TOML table. |
197
+ | Change it | `PI_SPACES_CONFIG=<path>` (a leading `~` is your home folder; a relative path is taken from it). The `pi-space` command also takes `--config <path>` (see [`cli/README.md`](cli/README.md)). |
198
+ | Missing | No profiles: Pi, spaces and `pi-space` behave as without this feature. |
199
+ | Invalid | See [When the file is wrong](#when-the-file-is-wrong). |
200
+
201
+ A complete example for a program called `my-launcher`, which keeps its own configuration outside its agent home:
202
+
203
+ ```toml
204
+ schema = "pi-spaces.config/v2"
205
+
206
+ [profiles.ml]
207
+ home = "~/.my-launcher/agent"
208
+ spaceEnv = { MY_LAUNCHER_CONFIG_HOME = "{home}/config" }
209
+
210
+ [profiles.ml.commands]
211
+ base = "my-launcher --"
212
+ setup = "my-launcher --home {home} setup"
213
+ ```
214
+
215
+ <details><summary>The same in JSON</summary>
216
+
217
+ ```json
218
+ {
219
+ "schema": "pi-spaces.config/v2",
220
+ "profiles": {
221
+ "ml": {
222
+ "home": "~/.my-launcher/agent",
223
+ "commands": {
224
+ "base": "my-launcher --",
225
+ "setup": "my-launcher --home {home} setup"
226
+ },
227
+ "spaceEnv": { "MY_LAUNCHER_CONFIG_HOME": "{home}/config" }
228
+ }
229
+ }
230
+ }
231
+ ```
232
+
233
+ </details>
234
+
235
+ With that file, a space of `my-launcher` lives in `~/.my-launcher/spaces/<name>` (its agent home is `<name>/agent`), `/space new <name>` points you at `pi-space setup ml/<name>`, and entering the space `work` starts Pi with `MY_LAUNCHER_CONFIG_HOME=~/.my-launcher/spaces/work/agent/config`, while the base home gets no such variable from pi-spaces. From a shell, `pi-space ml/work` runs `my-launcher -- --space work`, and an alias such as `alias mlw='pi-space ml/work'` is optional sugar on top.
236
+
237
+ Some programs behave differently when they are given their home explicitly (an option such as `--home`), even when it is their own default home. So `commands.base` runs the program exactly as you would run it yourself, and `commands.space` puts it in the space's home. A program that takes its home with an option gets a `space` command with `{home}` in it: `pi-space` runs it in the space's home with no `--space`, with the words after the space after the command, and its `base` is the program as it is, so its own commands work in base. For `my-launcher`:
238
+
239
+ ```toml
240
+ schema = "pi-spaces.config/v2"
241
+
242
+ [profiles.launcher]
243
+ home = "~/.my-launcher/agent"
244
+ spaceEnv = { MY_LAUNCHER_CONFIG_HOME = "{home}/config" }
245
+
246
+ [profiles.launcher.commands]
247
+ base = "my-launcher"
248
+ space = "my-launcher --home {home}"
249
+ setup = "my-launcher --home {home} setup"
250
+ ```
251
+
252
+ <details><summary>The same in JSON</summary>
253
+
254
+ ```json
255
+ {
256
+ "schema": "pi-spaces.config/v2",
257
+ "profiles": {
258
+ "launcher": {
259
+ "home": "~/.my-launcher/agent",
260
+ "commands": {
261
+ "base": "my-launcher",
262
+ "space": "my-launcher --home {home}",
263
+ "setup": "my-launcher --home {home} setup"
264
+ },
265
+ "spaceEnv": { "MY_LAUNCHER_CONFIG_HOME": "{home}/config" }
266
+ }
267
+ }
268
+ }
269
+ ```
270
+
271
+ </details>
272
+
273
+ With it, `pi-space launcher/base` runs `my-launcher`, `pi-space launcher/base upgrade` runs `my-launcher upgrade`, and `pi-space launcher/work` runs `my-launcher --home ~/.my-launcher/spaces/work/agent`.
274
+
275
+ Keep the `spaceEnv` of the program's own config home: without it, a space's `--home` would leave the program's configuration shared with the base home. The details are in [`cli/README.md`](cli/README.md#a-command-with-home).
276
+
277
+ `pi-space init` writes a starter file (see [Writing the file](#writing-the-file)). A file in the older format keeps working: see [Moving from v1 to v2](#moving-from-v1-to-v2).
278
+
279
+ ### Example: gentle-shell
280
+
281
+ For whoever uses gentle-shell, this is a profile for it. The base runs `gentle-shell` as it is, and each space gets its own config folder, `gentle-ai`, next to its `agent/` folder through `spaceEnv`:
282
+
283
+ ```toml
284
+ schema = "pi-spaces.config/v2"
285
+
286
+ [profiles.gentle]
287
+ home = "~/.gentle-shell/agent"
288
+ spaceEnv = { GENTLE_PI_CONFIG_HOME = "{space}/gentle-ai" }
289
+
290
+ [profiles.gentle.commands]
291
+ base = "gentle-shell"
292
+ space = "gentle-shell --home {home}"
293
+ setup = "gentle-shell --home {home} setup"
294
+ ```
295
+
296
+ <details><summary>The same in JSON</summary>
297
+
298
+ ```json
299
+ {
300
+ "schema": "pi-spaces.config/v2",
301
+ "profiles": {
302
+ "gentle": {
303
+ "home": "~/.gentle-shell/agent",
304
+ "commands": {
305
+ "base": "gentle-shell",
306
+ "space": "gentle-shell --home {home}",
307
+ "setup": "gentle-shell --home {home} setup"
308
+ },
309
+ "spaceEnv": { "GENTLE_PI_CONFIG_HOME": "{space}/gentle-ai" }
310
+ }
311
+ }
312
+ }
313
+ ```
314
+
315
+ </details>
316
+
317
+ ### Writing the file
318
+
319
+ `pi-space init` writes the config file for you, in the location above (or in `--config <path>`), and refuses a file that already exists. It has no profiles of its own: the built-in `pi` is always there. The file starts with comments that show how `pi` is set up and a profile for another program, then an empty v2 config:
320
+
321
+ ```toml
322
+ # pi-spaces config: https://github.com/jals1212/pi-spaces#profiles
323
+ #
324
+ # The built-in profile "pi" is always there, set up like this; add a
325
+ # [profiles.pi] table to change it:
326
+ #
327
+ # [profiles.pi]
328
+ # home = "~/.pi/agent"
329
+ # dir = "~/.pi/spaces"
330
+ # commands = { base = "pi", space = "pi --space {name}" }
331
+ # ...
332
+
333
+ schema = "pi-spaces.config/v2"
334
+ ```
335
+
336
+ (The paths are written absolute, for your machine; the header goes on with the profile for another program.) The file is TOML, unless `--config` names a path that does not end in `.toml`: that one gets the same header and an empty config in JSON:
337
+
338
+ ```text
339
+ // pi-spaces config: https://github.com/jals1212/pi-spaces#profiles
340
+ // ...
341
+ {
342
+ "schema": "pi-spaces.config/v2",
343
+ "profiles": {}
344
+ }
345
+ ```
346
+
347
+ Both formats take comments, in both schemas: `#` in TOML; `//` to the end of the line and `/* ... */` in JSON. A comment inside a string is part of the string. An unclosed `/*` makes a JSON file invalid.
348
+
349
+ ### Schema `pi-spaces.config/v2`
350
+
351
+ Top level (every other key is refused):
352
+
353
+ | Key | Type | Required | Meaning |
354
+ | --- | --- | --- | --- |
355
+ | `schema` | string | yes | `"pi-spaces.config/v2"`, or `"pi-spaces.config/v1"` (see [Schema versions](#schema-versions)). |
356
+ | `default` | string | no | Accepted and validated (it must name a profile of the file, or `pi`), but not used: neither the extension nor `pi-space` falls back to it. `pi-space` warns when it reads a file that has it; remove the key. |
357
+ | `profiles` | object | no | Profiles by name. Names: lowercase letters, digits, `-` and `_`, starting with a letter or digit, at most 64 characters. |
358
+
359
+ A profile (every other key is refused; every key is optional):
360
+
361
+ | Key | Type | Default | Meaning |
362
+ | --- | --- | --- | --- |
363
+ | `home` | string, not empty | `PI_CODING_AGENT_DIR`, else `~/.pi/agent` | The base agent home of the program: the home it starts Pi with, which `base` goes back to. `~` is your home folder; a relative path is taken from it. |
364
+ | `commands` | object | none (the profile starts `pi`) | The command of each action, below. `base` is required when `commands` is there; any other key is refused. |
365
+ | `dir` | string, not empty | `spaces` next to `home` (`~/.my-launcher/agent` gives `~/.my-launcher/spaces`) | The folder that holds the profile's spaces. `~` and relative paths as in `home`. |
366
+ | `spaceEnv` | object of strings | none | Variables that exist only in spaces; see below. Names: letters, digits and `_`, not starting with a digit; not `PI_CODING_AGENT_DIR`, `PI_SPACE`, `PI_SPACE_HOME` or any `PI_SPACES_*`, which pi-spaces sets itself. |
367
+
368
+ `commands` (each a string, not empty):
369
+
370
+ | Key | Required | Meaning |
371
+ | --- | --- | --- |
372
+ | `base` | yes | Starts the base home: `pi-space <profile>/base` runs it as it is, with the words after `base` after it, and no `--space`. `{home}`, `{space}` and `{name}` in it become the profile's `home`, the folder above it and `base`. `pi-space launcher/base upgrade` with `"base": "my-launcher"` runs `my-launcher upgrade`. |
373
+ | `space` | no | The template that starts a space; `{home}` becomes the space's agent home, `{space}` its root folder and `{name}` its name, and the words after the space go after it. **With `{home}`** (`my-launcher --home {home}`): run in the space's home, with the environment of the space (its `spaceEnv` and the variables of the home). **Without `{home}`** (`pi --space {name}`): filled in and run with the plain environment, because the program switches itself. **Missing**: `<base> --space <name>`. |
374
+ | `setup` | no | Prepares a new space; `{home}` becomes the space's agent home, `{space}` its root folder and `{name}` its name. With it, `/space new` names `pi-space setup <profile>/<name>`. |
375
+
376
+ `PI_SPACES_COMMAND`, the program told to the model and exported, is `commands.space` when it is there, else `commands.base`; `PI_SPACES_SETUP` is `commands.setup`. The package commands (`update`, `install`, `uninstall`, `list`) go through the same commands: `pi-space update launcher/base` runs `my-launcher update`, and `pi-space update launcher/work` runs `my-launcher --home ~/.my-launcher/spaces/work/agent update`.
377
+
378
+ All strings are trimmed. `{home}`, `{space}` and `{name}` are replaced everywhere they appear in a `spaceEnv` value and in the commands (in base, `{space}` is the folder that holds the profile's `home`), and `$` in a value stays literal. The profile has no `command`, `setup` or `homeless` in v2: they are `commands`, and `pi-space <profile>/base upgrade` already runs `<base> upgrade`.
379
+
380
+ ### `spaceEnv`: what is separate and what is shared
381
+
382
+ Pi keeps everything in its agent home, so a space separates it completely with no configuration. A program that runs Pi may also keep something **outside** that home (a configuration folder, say) and hand its location to Pi in an environment variable. When you switch, pi-spaces moves only the variables that point inside the old home (see [How switching works](#how-switching-works)); a variable that points elsewhere is not recognised as part of the home and stays as it was. So without `spaceEnv`, whatever the program keeps outside the agent home is **shared** between the base home and every space. That is the default on purpose: nothing is separated that you did not ask to separate.
383
+
384
+ To separate it, name the variable in `spaceEnv`, with a value built from the space:
385
+
386
+ - Entering a space sets the variable, from the template, with `{home}` the space's agent home (`<space>/agent`), `{space}` the space's root folder and `{name}` its name. Use `{space}` for what the program keeps beside `agent/`, so it stays out of Pi's own home.
387
+ - Going back to `base` puts back the value the base home had when you left it, or removes the variable when it had none, so the base home runs exactly as it was started. The base's values travel in `PI_SPACES_BASE_ENV` while you are in spaces.
388
+ - Going from one space to another sets it again for the target; a value that pointed into the old space is replaced, not moved.
389
+ - `pi --space <name>` does the same at startup.
390
+
391
+ pi-spaces does not create what a variable points to; `setup` (or the program itself) does.
392
+
393
+ ### The built-in `pi` profile
394
+
395
+ Plain Pi is always a profile named `pi`: base `pi`, spaces `pi --space {name}`, no setup, no `spaceEnv`. Its home is `PI_SPACES_BASE_HOME` (set inside a space), else `PI_CODING_AGENT_DIR`, else `~/.pi/agent`. It needs no file; `pi-space init` only shows it in comments.
396
+
397
+ Inside another program's Pi those variables hold that program's home. When a profile of the file names that folder as its `home`, `pi` does not take it and uses `~/.pi/agent`, so `pi/<name>` is still plain Pi there.
398
+
399
+ Naming `pi` in `profiles` replaces it as a whole; what that entry leaves out still takes the defaults above for `home` and the command, never anything from the old built-in's other fields.
400
+
401
+ ### Schema versions
402
+
403
+ The file says which format it uses in `schema`, so the format can grow without breaking files. This pi-spaces reads `pi-spaces.config/v2` (the format above) and `pi-spaces.config/v1` (see [the v1 format](#the-v1-format)); a v1 file works exactly as before. A file with a newer `pi-spaces.config/vN` is refused with a message that it needs a newer pi-spaces (update the package), for example `"schema" is "pi-spaces.config/v3", which needs a newer pi-spaces; this one reads "pi-spaces.config/v1" and "pi-spaces.config/v2".`; anything else in `schema`, or no `schema`, is refused as invalid. A newer format is never half-read. A pi-spaces older than the one that added v2 refuses a v2 file the same way ("needs a newer pi-spaces").
404
+
405
+ ### The v1 format
406
+
407
+ The first format, `"schema": "pi-spaces.config/v1"`, is still read. Its profile has `home`, `dir` and `spaceEnv` as above, and these keys instead of `commands`:
408
+
409
+ | Key | Type | Default | Meaning |
410
+ | --- | --- | --- | --- |
411
+ | `command` | string, not empty | `pi` for the profile `pi`; none for the others | The command that starts the program (`my-launcher --`), in front of `--space <name>`. With `{home}` and `{name}` in it (`my-launcher --home {home}`), `pi-space` runs it directly in the space's home, without `--space`, filling them in with the space's agent home and name, and `{space}` with its root folder (in `base`, the profile's `home`, the folder above it and `base`), and the words after the space go after it. See [A command with `{home}`](cli/README.md#a-command-with-home). |
412
+ | `setup` | string, not empty | none | The command that prepares a new space; `{home}` becomes the space's agent home, `{space}` its root folder and `{name}` its name. |
413
+ | `homeless` | list of words, not empty | none | First words that run `command` without its home: `"homeless": ["upgrade"]` with `my-launcher --home {home}` makes `pi-space launcher/base upgrade` run `my-launcher upgrade`, with no `--space` and the plain environment of the profile. Only the first word counts; each word has no spaces. |
414
+
415
+ A v1 profile with `commands` is refused, and so is a v2 profile with `command`, `setup` or `homeless`.
416
+
417
+ ### Moving from v1 to v2
418
+
419
+ There is no command for it: edit the file once.
420
+
421
+ 1. Change `schema` to `"pi-spaces.config/v2"` (the steps are the same in TOML and JSON).
422
+ 2. `command` with `{home}` becomes `commands.space`, and `commands.base` is that command without the `{home}` words (`--home {home}` removed).
423
+ 3. `command` without `{home}` becomes `commands.base`, with no `space`.
424
+ 4. `setup` becomes `commands.setup`.
425
+ 5. Drop `homeless`: in v2 `pi-space <profile>/base upgrade` already runs `<base> upgrade`.
426
+
427
+ Before (v1):
428
+
429
+ ```toml
430
+ schema = "pi-spaces.config/v1"
431
+
432
+ [profiles.launcher]
433
+ home = "~/.my-launcher/agent"
434
+ command = "my-launcher --home {home}"
435
+ setup = "my-launcher --home {home} setup"
436
+ spaceEnv = { MY_LAUNCHER_CONFIG_HOME = "{home}/config" }
437
+ homeless = ["upgrade", "self-uninstall", "memory"]
438
+ ```
439
+
440
+ <details><summary>The same in JSON</summary>
441
+
442
+ ```json
443
+ {
444
+ "schema": "pi-spaces.config/v1",
445
+ "profiles": {
446
+ "launcher": {
447
+ "home": "~/.my-launcher/agent",
448
+ "command": "my-launcher --home {home}",
449
+ "setup": "my-launcher --home {home} setup",
450
+ "spaceEnv": { "MY_LAUNCHER_CONFIG_HOME": "{home}/config" },
451
+ "homeless": ["upgrade", "self-uninstall", "memory"]
452
+ }
453
+ }
454
+ }
455
+ ```
456
+
457
+ </details>
458
+
459
+ After (v2):
460
+
461
+ ```toml
462
+ schema = "pi-spaces.config/v2"
463
+
464
+ [profiles.launcher]
465
+ home = "~/.my-launcher/agent"
466
+ spaceEnv = { MY_LAUNCHER_CONFIG_HOME = "{home}/config" }
467
+
468
+ [profiles.launcher.commands]
469
+ base = "my-launcher"
470
+ space = "my-launcher --home {home}"
471
+ setup = "my-launcher --home {home} setup"
472
+ ```
473
+
474
+ <details><summary>The same in JSON</summary>
475
+
476
+ ```json
477
+ {
478
+ "schema": "pi-spaces.config/v2",
479
+ "profiles": {
480
+ "launcher": {
481
+ "home": "~/.my-launcher/agent",
482
+ "commands": {
483
+ "base": "my-launcher",
484
+ "space": "my-launcher --home {home}",
485
+ "setup": "my-launcher --home {home} setup"
486
+ },
487
+ "spaceEnv": { "MY_LAUNCHER_CONFIG_HOME": "{home}/config" }
488
+ }
489
+ }
490
+ }
491
+ ```
492
+
493
+ </details>
494
+
495
+ A v1 file keeps working unchanged, so move when you want to. Update pi-spaces first, though: the extension in every home and the `pi-space` command. An older pi-spaces refuses a v2 file with "needs a newer pi-spaces", and then behaves as if there were no file.
496
+
497
+ ### When the file is wrong
498
+
499
+ Unknown keys, wrong types, bad names, a `default` that names no profile, an unreadable file and invalid TOML or JSON are all refused with a message that names the file and the problem, for example `~/.pi-spaces/config.toml: unknown key "hmoe" in profile "ml"; allowed keys are "home", "commands", "dir" and "spaceEnv".` (in a v1 file the keys are `"home", "command", "dir", "setup", "spaceEnv" and "homeless"`). Pi never stops for it: the extension shows the message once as a warning when the session starts (on stderr without a terminal UI) and then behaves as if there were no file. A missing file is not an error.
500
+
501
+ ## Moving an old space
502
+
503
+ Spaces made before this layout have no `agent/` folder: their folder is the agent home. They keep working as they are, with every command, and `{space}` is then the same folder as `{home}`. To give one the new layout, run, from a shell (it needs the optional [`pi-space` command](cli/README.md)):
504
+
505
+ ```sh
506
+ pi-space migrate pi/work # one space
507
+ pi-space migrate pi/--every # every space of a profile
508
+ pi-space migrate --every # every space of every profile
509
+ ```
510
+
511
+ It copies the whole space to `<spaces folder>/.backups/<name>-<UTC time>` first, then moves its content into `<space>/agent/`; the space keeps its name. It never touches `base`, the space you are in (run it from another space or a plain shell), or a space that already has `agent/`. If a step fails, the move is undone and the backup stays. A path written inside a space's files that points into the old folder (a local package, a `spaceEnv` value kept in a script) does not change: update it by hand.
512
+
513
+ ## Configuration reference
514
+
515
+ ### Where spaces live
516
+
517
+ In a `spaces` folder next to the home Pi starts with: `~/.pi/agent` keeps its spaces in `~/.pi/spaces/<name>/`, and each space keeps its agent home in `~/.pi/spaces/<name>/agent/`, as `~/.pi` keeps Pi's own in `agent/`. A program that runs Pi with its own home gets its own folder too, for example `~/.tool/agent` → `~/.tool/spaces`. The folder stays the same while you switch between spaces. A [profile](#profiles)'s `dir` replaces it for that profile's home, and `PI_SPACES_DIR` replaces both. The `pi-space` command does not read `PI_SPACES_DIR` (or `PI_SPACES_COMMAND` and `PI_SPACES_SETUP`) as a setting: it takes the folder from the profile or `--dir`, and sets the variable for the Pi it starts.
518
+
519
+ ### Environment variables
520
+
521
+ Read:
522
+
523
+ | Variable | Meaning |
524
+ | --- | --- |
525
+ | `PI_SPACES_DIR` | The spaces folder. A relative value is taken from your home folder. Default: the matching profile's `dir`, else `spaces` next to the base home. |
526
+ | `PI_SPACES_CONFIG` | The [config file](#profiles) with the profiles. A leading `~` is your home folder and a relative value is taken from it. Default: the first that exists of `config.toml` and `config.json` in `~/.config/pi-spaces` (or `$XDG_CONFIG_HOME/pi-spaces`), then in `~/.pi-spaces`; else `~/.pi-spaces/config.toml`. A path ending in `.toml` is read as TOML, any other as JSON. |
527
+ | `PI_SPACES_COMMAND` | The program that starts Pi (default `pi`; for a v2 profile its `commands.space`, else `commands.base`): told to the model and exported (see below). A switch starts Pi again with the command line it already has, so this is information, not a setting. |
528
+ | `PI_SPACES_SETUP` | The command that prepares a new space (a v2 profile's `commands.setup`). `/space new` names `pi-space setup <profile>/<name>` when it is set. The `pi-space` command sets it for the Pi it starts, from the profile or `--setup`; it does not read it from your shell. |
529
+ | `PI_CODING_AGENT_DIR` | Pi's agent home; its parent holds the default spaces folder. Default: `~/.pi/agent`. |
530
+
531
+ Set for the Pi a switch starts:
532
+
533
+ | Variable | Meaning |
534
+ | --- | --- |
535
+ | `PI_CODING_AGENT_DIR` | The space's agent home (`<space>/agent`; the space's folder itself for an [old space](#moving-an-old-space)), or the base home for `base`. |
536
+ | `PI_SPACE` | The space's name. Unset in the base home. |
537
+ | `PI_SPACES_BASE_HOME` | The home Pi started with, so `base` and the spaces folder survive switches. |
538
+ | `PI_SPACES_BASE_ENV` | Only with a profile's `spaceEnv`, and only in a space: the base home's own values of those variables (JSON), put back when you return to `base`. |
539
+
540
+ Set in every Pi this extension runs in, even one started without a switch, for its tools and the programs they start:
541
+
542
+ | Variable | Meaning |
543
+ | --- | --- |
544
+ | `PI_SPACE` | The active space's name, unset in the base home: the same variable a switch sets. |
545
+ | `PI_SPACE_HOME` | The agent home this Pi runs with: the space's `agent` folder (its folder, for an old space), or the base home. |
546
+ | `PI_SPACES_COMMAND` | Kept when it has a value; set to `pi` when it is unset or blank. The `pi-space` command sets it for the Pi it starts (the profile's command, or `--command`), and the extension reads it to tell the model and the tools how Pi was started (see below); `pi-space` itself does not read it from your shell. |
547
+
548
+ ### What the model is told
549
+
550
+ Before each run the system prompt gets a `<pi_space>` section with the same three facts: the space (or the base home), the agent home, and the command, with `<command> --space <name>` and `/space` as the ways to change space (when the command has `{home}` or `{name}`, `pi-space <profile>/<name>` instead of `<command> --space <name>`). The model knows where it runs without reading the environment. A Pi without structured prompt sections gets no section; the variables are still set.
551
+
552
+ ### The `pi-spaces` skill
553
+
554
+ The package also ships a `pi-spaces` skill (`skills/pi-spaces/SKILL.md`). It tells agents what a space is, how to read the current space, home and command, and which `/space` or `pi-space` action to use or propose for listing, creating, switching and removing spaces. Pi loads it when a task is about spaces; `/skill:pi-spaces` loads it by hand.
555
+
556
+ ### Exit status
557
+
558
+ | Status | `pi --space` |
559
+ | --- | --- |
560
+ | 0 … | Pi's own exit status. |
561
+ | 1 | An unknown or invalid space, or no name after `--space`. |
562
+
563
+ The `pi-space` command has its own: see [`cli/README.md`](cli/README.md#exit-status).
564
+
565
+ ## How switching works
566
+
567
+ Pi reads its agent home once, when it starts, so a running session cannot move to another home. `/space switch` closes Pi and starts the same command again with the space's agent home (`<space>/agent`):
568
+
569
+ - `PI_CODING_AGENT_DIR`, `PI_SPACE` and `PI_SPACES_BASE_HOME` are set as in [Environment variables](#environment-variables).
570
+ - Any other variable whose value is the old home, or a path inside it, moves to the same path in the new home; in a list such as `PATH`, each entry moves on its own. This keeps variables that a launcher derived from the home consistent. `PWD` and `OLDPWD` are left alone.
571
+ - With a [profile](#profiles) that has `spaceEnv`, those variables are then set, with `{home}` (the space's agent home), `{space}` (its root folder) and `{name}` filled in, when the target is a space; when it is `base`, they get back the values the base home had (`PI_SPACES_BASE_ENV`).
572
+ - The same options are kept, such as `--model`, `-e`, `--tools` and other extensions' options. The initial prompt, `@file` arguments, everything after `--`, and the session options (`-c`, `-r`, `--session`, `--session-id`, `--fork`, `--session-dir`, `--no-session`, `-n`) are dropped, because they belong to the home being left.
573
+ - A `--space <name>` option is dropped too, so a Pi that was started with it does not return to that space.
574
+ - Switching works only in the interactive terminal.
575
+
576
+ **A profile with `commands`** does not start the running Pi again: `/space switch base` runs its `commands.base`, and `/space switch <name>` runs its `commands.space` with `{home}`, `{space}` and `{name}` filled in (or `<commands.base> --space <name>` when it has no `commands.space`), so the program's own setup for the base home is kept. The environment is the one above; the options of the running Pi are not added. A command with an unclosed quote is reported and nothing restarts. Any other profile (a v1 file, or no profile) starts the running Pi again as described above.
577
+
578
+ `pi --space <name>` acts before Pi opens its interface or runs anything, so it keeps the prompt and the session options too, in every mode.
579
+
580
+ `pi --space <name> <command> ...`, where `<command>` is one of Pi's package commands right after the name, runs Pi again in that home with only `<command> ...`: Pi runs a package command only as its first argument. Options before `--space`, such as a launcher's own `-e`, are left out. The same Pi runs it, so a launcher's own Pi manages the space's packages; `base` and the current home work too.
581
+
582
+ ## What it leaves on your machine
583
+
584
+ Only the spaces you create, each a folder in the spaces folder with its `agent/` folder inside, and `agent/settings.json`. Pi fills a space as it would any home. Removing a space moves its folder to `.backups/<name>-<UTC time>` in the spaces folder, or deletes it with `--no-backup` or when you choose so; nothing else is written outside it. A backup is a whole space (its root folder, with `agent/` in it when it has one): move it back to restore it (`mv ~/.pi/spaces/.backups/work-2026-10-28T14-30-05Z ~/.pi/spaces/work`), or delete it when you no longer need it. Backups are never removed for you, and `.backups` is never listed as a space.
585
+
586
+ ## Safety
587
+
588
+ `/space remove`, `/space rename`, `pi-space remove`, `pi-space rename` and `pi-space migrate` refuse, before they ask:
589
+
590
+ - `base` and the active space;
591
+ - symlinks, and anything that is not a real folder directly inside the spaces folder;
592
+ - a space that holds the current or base home;
593
+ - a spaces folder that is the filesystem root, your home folder, or the agent home (or inside it).
594
+
595
+ A backup also needs `.backups` to be a real folder, not a symlink or a file.
596
+
597
+ ## Development
598
+
599
+ Two packages live in this repository: the Pi extension and its shared core at the root (`pi-spaces`), and the `pi-space` command in `cli/` (`pi-spaces-cli`).
600
+
601
+ ```sh
602
+ npm test # links cli/ to this checkout, builds both, runs both test suites (Node 22.18 or later)
603
+ pi -e ./extensions/spaces.ts # try the extension without installing it
604
+ ```
605
+
606
+ `src/` is TypeScript. Pi loads the extension's TypeScript itself. The command in `cli/` imports the core as `pi-spaces/spaces` (and the profiles code as `pi-spaces/config`): the plain JavaScript in `dist/` that `npm run build` makes (Node does not strip types from files under `node_modules`). `npm pack` and `npm publish` build it first. `scripts/link-self.mjs` makes `cli/node_modules/pi-spaces` a link to this checkout, so the command's tests use the core from the working tree instead of from npm.
607
+
608
+ Branches: work goes to `develop` through pull requests; `main` receives `develop` when a release closes.
609
+
610
+ ## Releasing
611
+
612
+ Each package has its own version, its own `CHANGELOG.md` and its own tag prefix:
613
+
614
+ | Package | Directory | Tag | Version and notes |
615
+ | --- | --- | --- | --- |
616
+ | `pi-spaces` (the extension) | `.` | `vX.Y.Z` | `package.json`, `CHANGELOG.md` |
617
+ | `pi-spaces-cli` (`pi-space`) | `cli/` | `cli-vX.Y.Z` | `cli/package.json`, `cli/CHANGELOG.md` |
618
+
619
+ 1. On a `release/X.Y.Z` branch from `develop`: set `version` in the package's `package.json`, rename `## Unreleased` in its `CHANGELOG.md` to `## X.Y.Z`, and commit `release X.Y.Z: <summary>`. Merge it into `develop`, then `develop` into `main`.
620
+ 2. Tag `main` and push the tag: `vX.Y.Z` for the extension, `cli-vX.Y.Z` for the command.
621
+ 3. The [release workflow](.github/workflows/release.yml) checks the tag against that package's `package.json` and `CHANGELOG.md`, runs the tests of both packages, and stages the version on npm through trusted publishing, with provenance. Approve it with 2FA: `npm stage list`, then `npm stage approve <id>`, or on npmjs.com.
622
+ 4. The workflow then creates the GitHub release, with the version's section of that package's `CHANGELOG.md` as notes.
623
+
624
+ The command takes its core from the extension package (the `pi-spaces` range in `cli/package.json`). A CLI release needs a version in that range already on npm, so release the extension first and approve it; the workflow refuses a `cli-v*` tag otherwise. When the command needs a newer core, raise the range in `cli/package.json` in the same release.
625
+
626
+ ## License
627
+
628
+ MIT