The spaces command: set up, update and remove Little Spaces

spaces is the Little Spaces client: one file that the Agents page prompt downloads to ~/.local/share/little-spaces/, beside its installer. The hooks run it, and so do the report commands each session is given. This page lists the commands you might run yourself, and what each does.

Running it

The client isn’t installed as a global command. Run any command through its installer, which finds a suitable Node.js (or the private copy setup installed) and runs the client with it:

sh ~/.local/share/little-spaces/install.sh whoami

This page writes spaces <command> for short. If your computer has Node.js 22.12 or later, node ~/.local/share/little-spaces/spaces.mjs <command> works too. You rarely need to type a command: the prompt runs setup, and each session is given its exact report and answer commands.

Set up and maintain

Command	What it does
`spaces setup [--name "Hooks on laptop"] [--only ID,ID] [--dry-run] [--verbose]`	Signs in if needed and installs the hooks for the apps on this computer. It connects the session it runs in when it can tell which session that is; otherwise it says what to do next. The approval page says what it installs. A stored sign-in installs only the apps its approval named; any other app needs a new approval naming every app. `--only` names apps by ID, such as `claude,codex`. `--dry-run` changes nothing and says what it would do.
`spaces update`	Replaces the client and its installer with the current ones once their checksums pass, then reinstalls the hooks already installed, with a newly pinned Node.js if the hooks use the private copy. It doesn’t sign in again, and never adds an app.
`spaces uninstall [--app ID] [--logout] [--dry-run]`	Removes what the installer wrote, for every app or the ones named, and nothing else. Backups are listed, never copied back. It keeps the sign-in unless you add `--logout`.
`spaces connect --help`	Prints a guide for an agent that setup doesn’t connect, so it can connect itself. It changes nothing.

Nothing updates by itself in the background. Pasting the Agents page prompt again downloads the current client and runs setup. It reuses the stored sign-in, but connecting an app the sign-in wasn’t approved for needs a new approval. spaces update only updates the apps already connected.

Command	What it does
`spaces login [--name "Hooks on laptop"]`	Signs in for hooks, reports and answers, with read and report permission, never work. It prints a link and an eight-letter code to approve.
`spaces whoami`	Shows the server, the agent identity, its workspace and permissions, which credential is in use, and any signals waiting to be sent. It never prints a token.
`spaces logout`	Revokes the sign-in and deletes it from this computer.
`spaces refresh [--force]`	Renews the sign-in now. It also renews by itself.

The sign-in is stored in ~/.config/little-spaces/credentials.json, readable only by you. Signing in again from the same computer lets you approve it as the same agent.

Reports and answers

Sessions run these with the exact command they were given. You can run them too.

Command	What it does
`spaces report '<JSON>'`	Sends a report. See report fields.
`spaces report -`	The same, reading the JSON from standard input, so no shell quoting is needed.
`spaces answers [--run RUN_ID]`	Lists your answers to the agent’s asks, oldest first, as JSON.
`spaces answers --ack EVENT_ID …`	Acknowledges answers to asks without a key, so they stop being returned.
`spaces answers --ack-key EVENT_ID KEY`	Acknowledges the answer to an ask with a key. It may repeat.
`spaces answers --all`	Lists acknowledged answers too, newest first.
`spaces answers --wait SECONDS`	Waits, up to 3,600 seconds, until an answer not yet acknowledged arrives, then prints it. It exits with code 2 if none came in time. It never acknowledges by itself.
`spaces activity '<JSON>'`	Reads a project’s recent activity and workstreams. Needs read permission.
`spaces ask '<JSON>'`	Asks a question about a project’s recent activity. Needs read permission.
`spaces flush`	Sends reports and signals that are waiting in the local outbox.

spaces report saves each report on your computer before sending it. If sending fails, run spaces flush instead of sending it again.

Sessions without hooks

Command	What it does
`spaces session start --app ID`	Tells a session its run and how to report. Apps without hooks, such as Zed and Windsurf Cascade, are told by their instructions to run it when each session starts. `ID` is an agent’s ID, such as `zed`, or `custom:NAME` for an agent setup doesn’t connect.
`spaces session end --run RUN_ID`	Ends that run.

The spaces hook … commands are what the installed hooks run. You don’t run them yourself.

Files on your computer

Path	What it holds
`~/.local/share/little-spaces/`	The client, its installer, their checksums, and the private Node.js copy if setup installed one.
`~/.config/little-spaces/credentials.json`	The sign-in. Readable only by you.
`~/.local/state/little-spaces/`	The outbox of reports and signals not yet sent, and a record of what the installer wrote.

Get started

How it works

Connecting agents

Reference

The spaces command: set up, update and remove Little Spaces

Running it

Set up and maintain

Reports and answers

Sessions without hooks

Files on your computer

​Running it

​Set up and maintain

​Sign-in

​Reports and answers

​Sessions without hooks

​Files on your computer

Running it

Set up and maintain

Sign-in

Reports and answers

Sessions without hooks

Files on your computer