docs: reference/cli.md — one catalogue for every subcommand - #1007
Merged
Conversation
Ends the CLI scatter the docs audit flagged (commands documented across installation, operations, public-api, README, and UPGRADING, with the seven headless commands only in an installation.md code block and missing from README's CLI list): - docs/reference/cli.md: summary table + per-command sections. Full home for the commands that had only scattered blocks (config reconcile, keepers, deps, the headless read/write commands, usage, the hash-* helpers, reap-environments — now with its real --archive/--force-delete flags); concise entry + canonical link for commands with a task home (doctor, backup/restore, api-token, install-service, mcp). - operations.md: the config-reconcile/keepers/deps sections move out of 'Backup, restore, and corruption recovery' (the audit's 'four CLI references that aren't about backup'); intro points at the catalogue. - installation.md: the subcommand catalogue collapses to a pointer. - The moved deps text gains 'deps install claustrum' (it predated #984 and named only shawl). - README's CLI list gains deps + the seven headless commands and links the page; nav + llms.txt updated; inbound anchors repointed (moved sections keep their old anchor ids via explicit {#id} attrs, which also satisfies markdownlint MD051 for the in-page table links). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Contributor
|
| Filename | Overview |
|---|---|
| docs/reference/cli.md | Adds the consolidated CLI catalogue with stable IDs for moved sections. |
| docs/operations.md | Replaces moved command sections with legacy fragment targets and a link to the new catalogue. |
| docs/installation.md | Replaces the scattered command list with a link to the CLI reference. |
| mkdocs.yml | Adds the CLI catalogue to the Reference navigation. |
Reviews (2): Last reviewed commit: "docs: legacy anchor stubs for the moved ..." | Re-trigger Greptile
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
schubydoo
pushed a commit
that referenced
this pull request
Jul 28, 2026
Merging this PR tags and publishes **v1.0.0**.
Generated by knope from the `.changeset/` fragments — don't edit it by
hand; add or amend a changeset on the source PR instead.
---
## Breaking Changes
- The Docker image now uses an Alpine (musl) base with explicitly
pinned, Renovate-tracked apk packages instead of Debian slim with an
unpinned `apt upgrade`; it is smaller and drops the Go-based `gosu` (now
`su-exec`). Derived images must use `apk` rather than `apt`.
([#944](https://github.com/schubydoo/clauster/pull/944))
- The `clauster mcp` write tools (`spawn_session` / `stop_session` /
`resume_session`) are now gated behind a new `mcp.allow_writes` config
key that defaults **off**, so the local-privileged, unauthenticated
stdio MCP surface is read-only by default and its `--help`/banner no
longer understate its capability (#1010); set `mcp.allow_writes: true`
to restore the #950 write tools.
([#1066](https://github.com/schubydoo/clauster/pull/1066))
- The cross-site `Origin` allowlist is now enforced even when
`auth.enabled` is false (the shipped default), closing a CSRF /
WebSocket-hijack hole: previously the HTTP `guard` middleware returned
before the Origin check and all four WebSocket routes short-circuited
theirs, so a page the operator merely visited could drive unsafe
requests against the loopback dashboard (trust a directory, resume a
bridge, clone a repo, restart) and read-stream live session output. With
auth off the gate rejects only a *present*, non-allowlisted `Origin` —
an absent one (a CLI/script client, never a browser) still passes. A
loopback bind auto-allows `127.0.0.1`/`localhost`/`[::1]` **at its
configured port**, so the default deployment needs no change; an
auth-off deployment the browser reaches at any other address — a
non-loopback bind, a tunnel or reverse proxy, or an SSH port-forward
onto a different local port — must now list that origin in
`auth.allowed_origins`, the same setting an authenticated deployment in
those positions already needs. It fails closed and visibly, never
silently (see UPGRADING.md).
([#1070](https://github.com/schubydoo/clauster/pull/1070))
- Live sessions are now attributed to the bridge that actually owns
them, so a Server Mode bridge no longer lists a project's independent
Interactive Sessions as its own; the MCP `list_sessions` tool no longer
repeats a session once per bridge, and a bridge's `id` is now its unique
instance id (**breaking**: it was the project name — see UPGRADING.md).
([#1082](https://github.com/schubydoo/clauster/pull/1082))
- Commit to SQLite for storage and remove the unsupported `database_url`
(Postgres) config key; a leftover `database_url` in your config is now
ignored rather than rejected.
([#801](https://github.com/schubydoo/clauster/pull/801))
## Features
- The **Advanced** config panel now edits list and map fields too
(#978): `clone.allowed_schemes` and `clone.allowed_private_cidrs` get a
rows editor (add/remove entries), and `webhooks.events` gets a checkbox
per known lifecycle event (each shown at its correct default, saving
only the events you change). These join the existing Advanced scalars
behind the same `config_write` capability + step-up re-auth. Secret URL
lists (`webhooks.urls`, `notifications.urls`) and auth trust lists stay
file/CLI-only — their masked values can't round-trip a browser edit
safely — and every write is still fail-closed, re-validated (bad CIDR /
unknown event rejected), and audited by key-name only.
([#982](https://github.com/schubydoo/clauster/pull/982))
- New **Advanced** config surface (#978): the operational-but-sensitive
`clone.*` and `webhooks.*` scalars are now editable in-app behind the
`config_write` capability **and** a step-up re-auth — `POST /api/reauth`
re-proves the operator password for a short unlock window, and
`GET`/`PUT /api/config/advanced` gate on that fresh proof.
Lockout/exposure/RCE keys (bind, auth switches, `ui.enabled`, TLS,
binaries, `config_write.*`, `login_shepherd.*`) stay file/CLI-only, and
every Advanced write is fail-closed (backup + atomic replace) and
audited by key-name only.
([#979](https://github.com/schubydoo/clauster/pull/979))
- The config editor now has an **Advanced settings** panel (#978): when
config-write is enabled, the `clone.*` and `webhooks.*` scalars are
editable from the dashboard behind a step-up re-auth — re-enter your
password to unlock a short window, edit, and save through the same
"restart to apply" flow. A wrong password shows an inline error and
keeps the panel locked; the unlock window expiring mid-edit re-prompts
rather than silently failing. Network bind, authentication, and TLS stay
file/CLI-managed.
([#980](https://github.com/schubydoo/clauster/pull/980))
- Launching a bridge over the API now reports whether it was newly
created or an existing one was reused, and each project's metrics add up
across all of its bridges.
([#797](https://github.com/schubydoo/clauster/pull/797))
- Add two optional per-launch controls for standard (server-mode)
bridges: a custom session name shown in claude.ai/code in place of the
project name, and a sandbox toggle (OS-level filesystem/network
isolation). Both default to no change and persist across resume.
([#811](https://github.com/schubydoo/clauster/pull/811))
- New headless read commands — `clauster projects`, `status`,
`sessions`, `logs`, and `open` — drive clauster from the terminal with
no server running (add `--json` for scriptable output), sharing one
engine with the web UI.
([#927](https://github.com/schubydoo/clauster/pull/927))
- New headless write commands — `clauster start <project>` and `clauster
stop <instance>` — spawn and stop bridges from the terminal with no
server running, sharing the web UI's engine, mode policy, and validation
(`--mode`, `--trust`, `--json`).
([#928](https://github.com/schubydoo/clauster/pull/928))
- Completes the config-change audit trail's subprocess-visibility slice
(#958 Part 6): MCP **and plugin** writes now record the redacted `claude
mcp`/`claude plugin` **argv** the CLI actually ran, and the before/after
**file fingerprints** (path + SHA-256 + size, never contents) now cover
the reset-project-choices, approvals, plugin, and marketplace handlers
too — not just MCP-server writes. So `config_audit.log` answers both
"where did this change land?" and "what ran?" for every CLI-driven
config mutation.
([#977](https://github.com/schubydoo/clauster/pull/977))
- The config-change audit trail now records, for each MCP-server write,
**which config files the change actually touched** — by path, SHA-256,
and byte size (never the file contents). Because `claude mcp` does
Claude Code's own bookkeeping across several files, this makes the
subprocess's side effects visible in `config_audit.log` and answers
"where did this change land?" without exposing any secret values.
([#976](https://github.com/schubydoo/clauster/pull/976))
- Every config-write is now recorded to a single `config_audit.log`
audit trail — one JSON line per change across every surface (CLAUDE.md,
settings, permissions, hooks, MCP, approvals, subagents, skills,
plugins, marketplaces), capturing the surface, scope, target file,
action, actor, and the top-level key names touched (never the values).
Generalises the previous CLAUDE.md-only edit audit so a config change
can be traced to where it landed.
([#969](https://github.com/schubydoo/clauster/pull/969))
- Add a Config management panel to the dashboard (when config-write is
enabled) for editing your project's CLAUDE.md and settings.json across
User/Project/Local scopes, with a type-the-name confirm and secret
masking. ([#828](https://github.com/schubydoo/clauster/pull/828))
- Add an MCP tab to the Config management panel to add, edit, and remove
MCP servers at project, local, or user scope, and to approve or reject
each committed project server.
([#831](https://github.com/schubydoo/clauster/pull/831))
- Add Permissions and Hooks tabs to the Config management panel for
editing a scope's tool-permission rules and lifecycle hooks, behind the
same type-the-name confirm.
([#829](https://github.com/schubydoo/clauster/pull/829))
- Add a Plugins tab to the Config management panel to enable, disable,
install, uninstall, and update plugins, and to add, remove, and update
marketplaces — each gated by the type-the-name confirm, with an extra
retype-the-id confirm on install.
([#833](https://github.com/schubydoo/clauster/pull/833))
- Add a Skills tab to the Config management panel to list, create, edit,
and delete your project or user skills (their SKILL.md), behind the same
type-the-name confirm.
([#832](https://github.com/schubydoo/clauster/pull/832))
- Add a Subagents tab to the Config management panel to list, create,
edit, and delete your project or user subagents (built-in and plugin
agents are shown read-only).
([#830](https://github.com/schubydoo/clauster/pull/830))
- Add a CLAUDE.md config-write surface (user/project/local scope,
edit/blank, gitignore-on-create for the local file) — content is never
redacted, unlike other config-write surfaces, since it's prose, not
secrets. ([#818](https://github.com/schubydoo/clauster/pull/818))
- Add a `local` scope to the config-write API (MCP servers, permission
rules, hooks) for project-only settings, gitignoring any newly created
local config file automatically.
([#813](https://github.com/schubydoo/clauster/pull/813))
- MCP servers can now be added/removed/edited through Claude Code's own
`claude mcp` CLI (secrets travel via env, never the command line), plus
project approval enable/disable and a reset-approvals action — all
behind the existing config-write gate.
([#822](https://github.com/schubydoo/clauster/pull/822))
- Add a plugins + marketplaces config-write API
(enable/disable/install/uninstall/update, marketplace
add/remove/list/update) driven through `claude plugin`, gated behind the
existing off-by-default capability plus a strong per-plugin confirm on
install. ([#827](https://github.com/schubydoo/clauster/pull/827))
- Add a config-write API for `env`/`model`/misc `settings.json` keys at
user/project/local scope, plus a scope-merge provenance view showing
each key's effective value and source layer.
([#823](https://github.com/schubydoo/clauster/pull/823))
- Add a skills config-write surface (user/project scope;
list/view/add/delete + `skillOverrides` enable/disable at all three
scopes) — plugin skills stay read-only, uploaded scripts need an extra
confirm and are never executed, and skill content is redacted on read.
([#825](https://github.com/schubydoo/clauster/pull/825))
- Add a subagents config-write surface (list/view/add/edit/delete at
user/project scope) — Claude Code's own built-in and plugin-provided
agents are shown but refused as read-only.
([#824](https://github.com/schubydoo/clauster/pull/824))
- Harden the dashboard's Content-Security-Policy by removing
`unsafe-eval` from script-src.
([#788](https://github.com/schubydoo/clauster/pull/788))
- Run several interactive sessions per project from the dashboard, each
with its own controls and isolated git worktree, plus a warning when two
would share the same working copy.
([#800](https://github.com/schubydoo/clauster/pull/800))
- `clauster deps install claustrum` now side-installs the **Direct
Session daemon** — the standalone `claustrum` binary the hosted
live-view channel needs. It downloads the pinned, SHA-256-verified
release for your OS/arch (Linux/macOS/Windows × x86_64/arm64) from
`schubydoo/claustrum` into `<state_dir>/deps/bin`, and Clauster's daemon
launcher uses it automatically (an explicit `claustrum.binary` or a
`claustrum` on `PATH` still wins). Fail-closed like the other managed
binaries — a checksum mismatch refuses — and surfaced in `clauster deps
list` / `doctor` (the doctor line only appears when
`claustrum.enabled`). The pin auto-bumps via Renovate.
([#984](https://github.com/schubydoo/clauster/pull/984))
- New `clauster deps list/install/uninstall <extra>` side-installs the
optional `pty`/`notify` extras into `<state_dir>/deps` for the
standalone binary (which adds that directory to its import path at
startup), behind an explicit unsigned-wheel confirmation.
([#933](https://github.com/schubydoo/clauster/pull/933))
- First-run setup wizard (#978): running `clauster` with no
`clauster.yml` now serves a small, loopback-only setup page instead of
exiting with an error. Enter your projects folder, bind address, and a
dashboard password, and it writes a config with authentication enabled,
then restarts onto it. The wizard binds `127.0.0.1:7621` by default
(override with `CLAUSTER_SETUP_PORT`) and gates the submit to a loopback
origin, so only a local operator can complete setup.
([#981](https://github.com/schubydoo/clauster/pull/981))
- The standalone binary now bundles `pip`, so `clauster deps install
<extra>` runs on it directly (no separate Python needed); `clauster deps
install shawl` provides the pinned, checksum-verified
[Shawl](https://github.com/mtkennerly/shawl) service wrapper that
`install-service windows` now uses instead of nssm; and the uninstaller
enumerates the side-installed extras/Shawl and can preserve them with
`--keep-deps`. ([#936](https://github.com/schubydoo/clauster/pull/936))
- The config panel's Hooks surface gains a friendly rows editor —
add/remove one command hook per row (event, matcher, command, timeout)
instead of hand-editing the nested JSON; rows sharing an event + matcher
are saved as one group, and raw JSON stays as the escape hatch for
shapes the rows can't show. Commands are stored verbatim and never run
by Clauster. ([#973](https://github.com/schubydoo/clauster/pull/973))
- `clauster stop/logs/open`, the MCP tools and the API now accept a
unique instance-id prefix, refusing an ambiguous one instead of
guessing. ([#1113](https://github.com/schubydoo/clauster/pull/1113))
- Add an opt-in, auth-gated dashboard panel that drives a `claude auth
login` / `claude setup-token` flow so an operator can re-authenticate
the runtime `claude` account from the browser instead of SSHing in.
([#846](https://github.com/schubydoo/clauster/pull/846))
- The dashboard login panel now points operators at the non-interactive
runtime-account auth options (`ANTHROPIC_API_KEY`,
`CLAUDE_CODE_OAUTH_TOKEN`, `apiKeyHelper`) so they can be set from the
config editor without SSH, with docs on which to use when.
([#925](https://github.com/schubydoo/clauster/pull/925))
- The `clauster mcp` server gains write tools — an MCP client can now
spawn, stop, and resume bridge sessions (not just observe them). Trust
is never auto-granted: `spawn_session` requires an explicit `trust:
true` for an untrusted directory.
([#950](https://github.com/schubydoo/clauster/pull/950))
- The `claude.node_from_nvm` setting now defaults to **on**: bridges
resolve nvm's `default` node and put its `node`/`npx`/`npm` plus
nvm-global CLIs (e.g. `agent-browser`) on the bridge `PATH` in every
spawn context (not just `bash -c`). `clauster doctor` warns when an nvm
toolchain won't reach spawned bridges; set the option false to opt out.
([#859](https://github.com/schubydoo/clauster/pull/859))
- Add an opt-in `claude.node_from_nvm` setting that puts your
nvm-managed Node on the bridge's PATH, fixing npx/node MCP servers that
failed to start under systemd.
([#803](https://github.com/schubydoo/clauster/pull/803))
- The config panel's Permissions surface gains a friendly rows editor —
add/remove `allow`, `deny`, and `ask` rules and pick a default mode from
a list, instead of hand-editing raw JSON (raw stays as the escape hatch
for shapes the rows can't show). `ask` rules are now accepted by the
permissions write surface.
([#972](https://github.com/schubydoo/clauster/pull/972))
- Automatically back up `clauster.db` before running a database
migration, keeping the last 5 snapshots under `state_dir/backups/`.
([#804](https://github.com/schubydoo/clauster/pull/804))
- Interactive Session launches gain a Conversation picker (More
options): fork any of the project's past conversations into the new
session — the original stays untouched.
([#948](https://github.com/schubydoo/clauster/pull/948))
- Add a versioned `/api/v1` public API with named, revocable bearer
tokens (`clauster api-token issue/list/rotate/revoke`) and an optional
OpenAPI docs page (`api.openapi_enabled`, off by default).
([#805](https://github.com/schubydoo/clauster/pull/805))
- Allow one standard bridge and several interactive sessions to run side
by side within a single project.
([#789](https://github.com/schubydoo/clauster/pull/789))
- The Settings config surface now offers a friendly key/value row editor
for the `env` map (add / edit / remove), with the raw-JSON view kept as
an escape hatch for other keys.
([#879](https://github.com/schubydoo/clauster/pull/879))
- The config panel's subagent editor now treats the **Name** box as the
single source of the agent's name — it's written into the frontmatter
`name:` automatically on save (the backend requires the two to match),
so you no longer type it twice. New agents start from a small
frontmatter template that omits `name:`.
([#974](https://github.com/schubydoo/clauster/pull/974))
- Add `tls.provision = self-signed` to auto-generate and renew a
self-signed HTTPS certificate at startup, stored under `state_dir/tls/`.
([#790](https://github.com/schubydoo/clauster/pull/790))
- Add `ui.enabled` (default `true`) to optionally run Clauster as a
JSON-API-only deployment with no browser dashboard.
([#810](https://github.com/schubydoo/clauster/pull/810))
- Add an `uninstall.sh` / `uninstall.ps1` counterpart to the install
scripts: it auto-detects the install method (standalone binary or
uv/pipx/pip/scoop), removes the binary/package, the service unit, and
the state directory + config, with `--dry-run`,
`--keep-config`/`--keep-data`, a confirmation prompt, and fail-closed
path safety. ([#881](https://github.com/schubydoo/clauster/pull/881))
## Fixes
- The dashboard now wraps its content in a single `<main>` landmark and
carries a page `<h1>`, so assistive tech can navigate its regions and
every content node sits inside a landmark (resolves the dashboard's
remaining moderate axe landmark/heading findings).
([#963](https://github.com/schubydoo/clauster/pull/963))
- The config editor's section jump-nav now includes an Advanced chip
whenever the password-gated Advanced panel is available, so the panel is
discoverable without scrolling to the bottom.
([#1052](https://github.com/schubydoo/clauster/pull/1052))
- The frozen binary now completes its first-run database migration under
a non-UTF-8 locale (#1015): `alembic.ini` was ASCII-cleaned so
`configparser` no longer crashes on an em-dash when the binary starts
with no `LANG`/`LC_ALL` against a fresh database.
([#1055](https://github.com/schubydoo/clauster/pull/1055))
- `clauster api-token issue`/`rotate`/`revoke` now accept the token
label either as a positional argument or with `--label` — previously the
three verbs disagreed (`issue` required `--label` while
`rotate`/`revoke` took a positional), so `api-token revoke --label X`
errored. ([#962](https://github.com/schubydoo/clauster/pull/962))
- `config_audit.log` is now **size-rotated** (#1011): at ~5 MB the
current file becomes `config_audit.log.1`, older files shift up, and
anything past 5 rotated files is dropped — so the config-write audit
trail is bounded at ~30 MB instead of growing unbounded on a long-lived
instance. Rotation is best-effort (a rotation error is logged and never
blocks the already-best-effort audit append), so a committed config
write is never held up by it.
([#1062](https://github.com/schubydoo/clauster/pull/1062))
- Docs: co-locate auth safety caveats with the options they qualify —
proxy identity is admission not access control (networking + security),
`auth.enabled`/`allow_unauthenticated_network` reference rows now carry
their fail-closed context, and the public-API unauthenticated note
states its loopback-only premise.
([#992](https://github.com/schubydoo/clauster/pull/992))
- A Background session that is not registered on claude.ai now requires
a first prompt — launched blank it would idle at "send a prompt to
start" forever with no way to receive one; the launch popover marks the
field required and the dispatch API rejects it with a 422.
([#1053](https://github.com/schubydoo/clauster/pull/1053))
- The claustrum preflight (`doctor`, the session-start panel, and `deps
list`) now resolves the binary the same way the daemon spawns it
(#1013): a configured `claustrum.binary` — the documented workaround for
systemd's minimal PATH — counts as present instead of a permanent false
"unavailable" warning, and `deps list` agrees with `doctor` instead of
reporting the same binary two different ways.
([#1057](https://github.com/schubydoo/clauster/pull/1057))
- `clauster doctor` now reports the detected claustrum daemon version
and warns — advisorily, never as a failure — when it can't be confirmed
at or above the release clauster pins (#1013): an unstamped/dev build or
an older release is surfaced rather than silently assumed compatible,
and a managed `deps/bin` install shadowed by a different
`PATH`/configured binary now raises a `binary:claustrum:shadow` warning
so you know which copy actually runs. Completes the claustrum-preflight
follow-up (Bug 3–5).
([#1060](https://github.com/schubydoo/clauster/pull/1060))
- On Windows the claustrum daemon is now launched with `-listen-pipe`,
so it opens the named-pipe listener the Windows client dials (via the
`rpc.pipe` file beside the socket); POSIX keeps using the AF_UNIX socket
unchanged. ([#900](https://github.com/schubydoo/clauster/pull/900))
- Teach the claustrum client to reach the daemon over a Windows named
pipe (discovered via the `rpc.pipe` file beside the socket) on Windows,
where asyncio cannot consume the AF_UNIX socket; POSIX keeps using the
AF_UNIX socket unchanged.
([#893](https://github.com/schubydoo/clauster/pull/893))
- On Windows the claustrum daemon is now spawned with `-token-file`
instead of `-token-fd 0` (a numeric fd is not a usable token handle for
the Go daemon there), so clauster can start and drive a hosted-channel
daemon over the named pipe.
([#902](https://github.com/schubydoo/clauster/pull/902))
- The Clone button now stays disabled until you enter a Git URL, so an
empty clone no longer shows a raw error.
([#762](https://github.com/schubydoo/clauster/pull/762))
- A restart no longer hides stopped sessions: every persisted instance
is now rebuilt on its own row, instead of collapsing to one card per
project. ([#1118](https://github.com/schubydoo/clauster/pull/1118))
- The config editor now tells a feature switch what it needs (#1016 Part
2): a switch whose optional dependency is missing — Direct Sessions (the
`claustrum` binary), notifications (`apprise`), the live-terminal view
(`pyte`) — shows a "Requires … — run `clauster deps install …`" note and
can't be turned on, so you learn what a feature needs at the moment
you'd enable it instead of finding it silently dormant. Availability is
resolved exactly the way the runtime resolves it (honoring a configured
`claustrum.binary`), so a dependency that IS present never greys out its
switch. ([#1064](https://github.com/schubydoo/clauster/pull/1064))
- Config-panel feedback now scrolls into view when it appears: arming a
delete focuses its type-to-confirm input, and an Advanced save brings
its success/error banner into the visible scrollport instead of leaving
it hidden above the fold.
([#1050](https://github.com/schubydoo/clauster/pull/1050))
- Fix the config editor's section tabs stretching into full-width bars
when they wrap onto multiple rows.
([#758](https://github.com/schubydoo/clauster/pull/758))
- Fix the config editor's section jumps so the heading you click lands
below the sticky nav instead of hiding under it.
([#759](https://github.com/schubydoo/clauster/pull/759))
- Config panel fixes: clearing a JSON surface
(Settings/Permissions/Hooks) and saving now treats a blank box as the
empty default instead of rejecting it as invalid JSON, the typed scope
confirm-token no longer lingers when you switch surface tabs, and the
last inline `style` attributes were converted to classes so the panel no
longer trips the `style-src` CSP.
([#960](https://github.com/schubydoo/clauster/pull/960))
- The config panel's "Show merged (effective) view" toggle now carries a
disclosure caret and `aria-expanded` — matching the panel's other
expand/collapse toggles — instead of rendering as easy-to-miss plain
text. ([#975](https://github.com/schubydoo/clauster/pull/975))
- Internal: simplify effective-settings scope-merge computation to
remove an unreachable branch (no behavior change).
([#826](https://github.com/schubydoo/clauster/pull/826))
- The config-management MCP, permissions, and hooks surfaces now return
404 (not 422) for an unknown scope while config-write is disabled, so a
disabled surface can't be fingerprinted.
([#835](https://github.com/schubydoo/clauster/pull/835))
- The hooks config-write API now rejects plugin-owned hook commands —
manage those via the plugin, not this surface.
([#817](https://github.com/schubydoo/clauster/pull/817))
- The config panel no longer rejects valid Skills and Subagents that
carry forward-compatible frontmatter keys (e.g. `effort`, `license`,
`metadata`), and no longer masks a benign `author` field as a secret.
([#959](https://github.com/schubydoo/clauster/pull/959))
- Broaden the automated test suite and tighten coverage checks to guard
against regressions.
([#808](https://github.com/schubydoo/clauster/pull/808))
- Cross-OS robustness: reject Windows reserved device names (`CON`,
`NUL`, …) as project names, honestly report a Windows background-agent
stop (a hard kill, not a false clean stop), don't mislabel a transient
clone-finalize failure as "already exists", preflight the AF_UNIX
socket-path length for macOS, and warn when `nssm` is absent for the
Windows service install.
([#917](https://github.com/schubydoo/clauster/pull/917))
- Headless CLI/MCP writers now serialize spawn/stop against the running
server on a per-project cross-process lock, and state saves merge onto
the store's current contents — a bridge can no longer be double-launched
and a forgotten record no longer resurrects (#949).
([#951](https://github.com/schubydoo/clauster/pull/951))
- Config and CLAUDE.md writes now share one cross-process lock held on a
file in the state dir, so the editor and config-write paths mutually
exclude across processes without leaving a `CLAUDE.md.lock` artifact in
project directories.
([#921](https://github.com/schubydoo/clauster/pull/921))
- Fix unreadable text selection in the dark theme: selected text in the
config editors (and elsewhere) now renders as white on a solid
Signal-Blue field (WCAG-AA 5:1) instead of Tabler's near-invisible
default tint. ([#970](https://github.com/schubydoo/clauster/pull/970))
- Fix the dashboard hiding running Server Mode sessions when a project
has more than one bridge.
([#1144](https://github.com/schubydoo/clauster/pull/1144))
- Close short-lived database engines' SQLite connections
deterministically instead of leaving them for the garbage collector,
which emitted spurious `unclosed database` warnings on Python 3.13+.
([#890](https://github.com/schubydoo/clauster/pull/890))
- Internal cleanup: share one SHA-256 hash helper across the config
modules (no behavior change).
([#753](https://github.com/schubydoo/clauster/pull/753))
- The dashboard now shows a header pill when the runtime `claude`
account is logged out, and `/healthz` reports its auth state
(`claude_login_ok` / `claude_login_method`, covering OAuth, API-key, and
helper logins) — so a stale login surfaces before a bridge silently
hangs at "Starting".
([#844](https://github.com/schubydoo/clauster/pull/844))
- Completing the first-run setup wizard on a non-loopback bind now
records the origin you reached it at in `auth.allowed_origins`, so the
login that follows succeeds. The wizard wrote no origins at all, and
`build_allowed_origins` auto-allows loopback only when the bind host is
itself loopback — so on the `0.0.0.0` bind the Docker image forces,
setup completed onto an empty allowlist and the very next request, the
login POST, was refused with `403 origin check failed` with no way back
into the dashboard short of hand-editing the generated `clauster.yml`.
The origin is recorded only for a bind that auto-allows nothing, only
from a submit that already cleared the wizard's own gate (the setup
token, or the loopback Origin check), and only when it parses as an
`http(s)` origin; a loopback install's generated config is unchanged.
The bundled `compose.yaml` and the installation guide now set
`CLAUSTER_AUTH_ALLOWED_ORIGINS` too, which covers the same failure on
the environment-configured path that never runs the wizard.
([#1077](https://github.com/schubydoo/clauster/pull/1077))
- The first-run setup wizard now works in Docker (#1017): it writes
`clauster.yml` to the persistent `/config` volume (`CLAUSTER_CONFIG`)
instead of the container's ephemeral layer, and — with
`CLAUSTER_SETUP_HOST=0.0.0.0` (baked into the image) — binds a reachable
interface gated by a one-time token printed to the container log, so a
published port can complete first-run setup without hand-writing config
or an SSH tunnel.
([#1067](https://github.com/schubydoo/clauster/pull/1067))
- docs: new `reference/cli.md` catalogues every subcommand, ending the
CLI scatter across installation/operations/README
([#1007](https://github.com/schubydoo/clauster/pull/1007))
- Docs: new operator-facing "How it works" page with a runtime-topology
diagram, and a glossary defining the vocabulary (bridge, keeper, Server
Mode / Interactive Session / Direct Session, spawn modes) the docs
previously used before defining.
([#1004](https://github.com/schubydoo/clauster/pull/1004))
- docs: DB-snapshot rollback must delete stale `-wal`/`-shm` sidecars,
not keep them (the snapshot is a self-contained `VACUUM INTO` copy)
([#1009](https://github.com/schubydoo/clauster/pull/1009))
- Docs: the in-app config editor gets its own guide page, the first-run
setup wizard now leads the quickstart config step, and the login
shepherd is discoverable from the docs home and quickstart.
([#1002](https://github.com/schubydoo/clauster/pull/1002))
- docs: installation decision table — pick an install method by
platform/updates instead of reading all ten sections
([#1008](https://github.com/schubydoo/clauster/pull/1008))
- Docs accuracy: warn that the on-disk bridge log is not redacted by
default (SUPPORT + operations), and replace the stale README claim that
`claustrum` is not distributable with the `clauster deps install
claustrum` instruction.
([#990](https://github.com/schubydoo/clauster/pull/990))
- docs: split configuration.md into a how-to guide
(`guides/configuration.md`) and the generated key reference
(`reference/config.md`), with a redirect from the old URL
([#1006](https://github.com/schubydoo/clauster/pull/1006))
- Docs: platform support is now a scannable capability × OS matrix on
its own reference page, and the site ships an `llms.txt` map that states
the bind/auth safety invariant for assistants.
([#1005](https://github.com/schubydoo/clauster/pull/1005))
- Docs site: new symptom-first Troubleshooting page, journey-grouped
navigation (Start here / Concepts / Guides / Reference / Operations /
Project), and the root UPGRADING / CHANGELOG / CONTRIBUTING / SUPPORT /
SECURITY files now appear on the published site.
([#994](https://github.com/schubydoo/clauster/pull/994))
- Update the README and docs feature lists to describe the full
dashboard Claude Code config editor (CLAUDE.md, settings/env,
permissions, hooks, MCP, subagents, skills, plugins) instead of just the
CLAUDE.md editor it started as.
([#883](https://github.com/schubydoo/clauster/pull/883))
- List-valued config keys can now be set from the environment, and
dict-valued keys no longer advertise a variable that crashes startup.
Eight `list[str]` keys — including `auth.allowed_origins`, which an
auth-on deployment behind a proxy, tunnel, or non-loopback bind needs —
were mapped to a `CLAUSTER_*` variable whose raw string was assigned
straight into the field, so setting the documented variable failed
config validation with `Input should be a valid list` and the process
never started; env-only deployments (Docker/Compose in particular) had
no way to set them short of hand-editing `clauster.yml`. Values now
split on commas **or newlines** — the newline form so a `*_FILE` secret
file can be written one entry per line, which previously collapsed into
a single unusable entry — with surrounding whitespace trimmed and blank
entries dropped. Note that an **empty** value now means an empty list
rather than falling through to the YAML value, so
`CLAUSTER_AUTH_ALLOWED_ORIGINS: ""` in a Compose file clears a
configured allowlist (it fails closed, refusing origins rather than
allowing them). An entry containing a literal comma — an Apprise URL in
`notifications.urls` with comma-separated query targets, say — still has
to be set in the YAML file. The three `dict` keys (`projects`,
`claude.env`, `webhooks.events`) genuinely cannot be addressed by one
variable and are now omitted from the env map entirely rather than being
discoverable-but-fatal, matching what the configuration guide already
documented. ([#1075](https://github.com/schubydoo/clauster/pull/1075))
- `clauster.yml.example` again shows the `config_write` and
`login_shepherd` sections (with `allow_user_scope` /
`allow_setup_token`) as commented-out defaults with a one-line
explanation and a pointer to the config reference (#1012). The #983
declutter had dropped them, so a new operator starting from the example
couldn't discover the config-management panel or the login shepherd —
the surfaces the 1.0 test-plan pre-flight tells testers to enable.
([#1061](https://github.com/schubydoo/clauster/pull/1061))
- An external terminal/SSH `claude` session sharing a running bridge's
directory now stays labeled external instead of being folded in as one
of the bridge's managed sessions.
([#874](https://github.com/schubydoo/clauster/pull/874))
- `clauster doctor` now reports each optional extra (`pty`/`notify`) as
OK or WARN with an install hint, and the dashboard's live-terminal
control renders greyed with that hint when the tap is enabled but the
`pyte` extra is missing instead of silently vanishing.
([#919](https://github.com/schubydoo/clauster/pull/919))
- Forgetting a stopped Interactive Session now also clears its saved
pointer, so the next launch registers a fresh session instead of
silently reattaching one that was archived or deleted out from under it
(#671). ([#868](https://github.com/schubydoo/clauster/pull/868))
- Document that in forward-auth (header-only) mode, `trusted_ips` must
list only your proxy's own IP — a broader range lets anyone reachable
there bypass authentication.
([#754](https://github.com/schubydoo/clauster/pull/754))
- Config-editor validation failures now surface a per-field,
plain-language message (e.g. "clone.allowed_private_cidrs: '…' does not
appear to be an IPv4 or IPv6 network") instead of the raw pydantic dump
with internal model names and error URLs.
([#1054](https://github.com/schubydoo/clauster/pull/1054))
- Internal frontend cleanup: dedupe shared helpers, drop dead code, and
add reusable template macros (no behavior change).
([#784](https://github.com/schubydoo/clauster/pull/784))
- `clauster doctor` and the dashboard preflight panel no longer nag
about the optional `apprise` dependency when notifications aren't
actually going to send (#1016): the `extra:apprise` row now appears only
when `notifications.enabled` is set **and** at least one
`notifications.urls` entry is configured — matching when runtime
actually imports apprise. (`pyte`/`pywinpty` stay ungated: pyte also
reassembles the bridge connect-URL and pywinpty is the Windows
Interactive-Session backend, so they matter beyond the opt-in
live-terminal view. Binary deps like claustrum were already gated on
their feature switch.)
([#1063](https://github.com/schubydoo/clauster/pull/1063))
- The per-launch **sandbox toggle is disabled for this release**
(#1037). Evidence from the pre-RC dogfood showed `--sandbox` reached the
remote-control bridge but was never passed to the server-mode session
worker that runs Bash, so the security-labeled control silently did
nothing — a "fail closed visibly" violation. The launch popover no
longer offers it, the `sandbox` API/CLI/MCP parameter is
accepted-but-inert (coerced to `default`), and any persisted `on`/`off`
on a stopped card resumes safely as `default`. It returns behind
dependency preflight + platform gating in #1046.
([#1059](https://github.com/schubydoo/clauster/pull/1059))
- A Direct Session's `instance_id` now persists across a clauster
restart (both the JSON and DB hosted-state backends), so a client-cached
id keeps resolving instead of 404ing against a freshly re-minted one.
([#843](https://github.com/schubydoo/clauster/pull/843))
- The Direct Session (hosted) lifecycle API endpoints — stop, resume,
forget, and message — now accept a session's `instance_id` in addition
to its `claustrum_process_id`, so an API client can address a session by
whichever id it already holds.
([#840](https://github.com/schubydoo/clauster/pull/840))
- Stop hosted sessions from spawning duplicate processes when resumed
twice at once, reject an unknown `permission_mode` with a clear 422, and
finish pending notifications cleanly on shutdown.
([#757](https://github.com/schubydoo/clauster/pull/757))
- Fix the Windows owner-only ACL so a stuck `icacls` no longer fails the
state write — it now logs a warning and proceeds on the inherited
permissions, restoring the best-effort contract.
([#920](https://github.com/schubydoo/clauster/pull/920))
- Fix the CLI and MCP server reporting stale, incomplete bridge state,
and bridges started from the CLI rendering as EXTERNAL/unmanaged in the
dashboard: instance liveness is now persisted and read per instance
rather than resolved per project, so every bridge on a project is
visible to every process and can be stopped by its own id.
([#1109](https://github.com/schubydoo/clauster/pull/1109))
- A long or hostile line in a project's config file can no longer stall
the dashboard's secret-redaction pass.
([#1123](https://github.com/schubydoo/clauster/pull/1123))
- Password managers no longer autofill a saved username into the launch
popover's First prompt and Session name, which could otherwise become a
bridge display name.
([#1122](https://github.com/schubydoo/clauster/pull/1122))
- The launch popover now closes as soon as you hit Trust & start,
instead of lingering through the whole spawn.
([#761](https://github.com/schubydoo/clauster/pull/761))
- Cap the live transcript at the most recent 1000 turns, with a "showing
last N" indicator, so long sessions stay responsive.
([#787](https://github.com/schubydoo/clauster/pull/787))
- An abandoned dashboard sign-in no longer wedges every later attempt:
the login panel rehydrates its in-progress flow after a page reload (so
Cancel is reachable), and a flow left idle for 15 minutes is reclaimed
by the next sign-in.
([#1081](https://github.com/schubydoo/clauster/pull/1081))
- The dashboard's long-lived `setup-token` login now runs on Windows
over a ConPTY (`pip install 'clauster[pty]'`), with the operator-pasted
code redacted from returned output since a ConPTY echoes input back.
([#912](https://github.com/schubydoo/clauster/pull/912))
- The dashboard `claude setup-token` login now waits for the authorize
URL to be stable across two polls before showing it, so a URL caught
mid-render (split across the pty reader's chunks) is never surfaced
truncated. ([#856](https://github.com/schubydoo/clauster/pull/856))
- `clauster logs` now withholds a half-flushed line until it completes,
so redaction can never miss a secret split across two reads.
([#1111](https://github.com/schubydoo/clauster/pull/1111))
- The MCP Server-approvals panel now reflects approvals that live in the
settings files (top-level
`enabledMcpjsonServers`/`disabledMcpjsonServers`, where `claude mcp
add-json --scope local|user` relocates them), so a server approved that
way no longer shows as un-approved. A settings-owned approval is shown
read-only (marked `settings`), since it can only be changed on the
settings surface or via `claude mcp` — the panel no longer offers an
approve/reject/unset that would silently revert on reload.
([#961](https://github.com/schubydoo/clauster/pull/961))
- The unapproved-MCP-server launch preflight now also treats a server
decided (enabled or disabled) in a project's `.claude/settings.json` /
`settings.local.json` or the user `~/.claude/settings.json` as decided —
matching which sources claude actually honors — so it no longer falsely
warns about a server that shows no enable gate.
([#857](https://github.com/schubydoo/clauster/pull/857))
- Launching an Interactive Session in a project with unapproved
committed `.mcp.json` servers now soft-blocks with an error-styled
confirm (it would otherwise hang at claude's MCP approval prompt and
never connect): a "Resolve in Server approvals" button, a "Launch
anyway" override, and block-by-default. Resolving the servers refreshes
the check so the next launch proceeds.
([#858](https://github.com/schubydoo/clauster/pull/858))
- The per-project readiness check now warns when a committed `.mcp.json`
has servers pending approval, since an interactive (pty) launch hangs
invisibly at claude's MCP-approval prompt otherwise — resolve them in
Server approvals first.
([#845](https://github.com/schubydoo/clauster/pull/845))
- The MCP `list_sessions` read tool no longer writes the shared state
store or fires crash webhooks and notifications.
([#1110](https://github.com/schubydoo/clauster/pull/1110))
- Modals no longer close when a text-selection drag that started inside
the dialog releases over the backdrop — only a click that both starts
and ends on the backdrop dismisses (Escape and the close button are
unchanged). ([#1049](https://github.com/schubydoo/clauster/pull/1049))
- Password managers no longer offer to fill non-credential dashboard
fields (#1036). Every non-password `input`/`textarea` — config-editor
rows, launch popovers, the clone URL, the first-run setup wizard — now
carries the per-vendor opt-out attributes (`data-1p-ignore` /
`data-lpignore` / `data-bwignore` / `data-form-type="other"`) alongside
`autocomplete="off"`, which Chromium Autofill and the manager extensions
ignore on its own (crbug 468153). Applied in the templates (a `{{
NO_AUTOFILL }}` global) so Alpine `x-for` row clones and the Alpine-free
setup page inherit it. The login and setup **password** fields
deliberately omit it, so your manager still fills/saves credentials.
([#1065](https://github.com/schubydoo/clauster/pull/1065))
- The launch popover's First prompt and custom session name fields no
longer get autofilled by a password manager — they were the only opt-out
inputs without an explicit `type`, which is enough for a manager to skip
the opt-out entirely.
([#1095](https://github.com/schubydoo/clauster/pull/1095))
- Dismissing the first-run orientation card now collapses it to a light
"No projects yet" hint instead of a near-identical block.
([#802](https://github.com/schubydoo/clauster/pull/802))
- A stopped card that shadows a live unmanaged Server Mode bridge is
pruned again — the check now finds the bridge above a working session,
whose own pid is the SDK worker rather than the bridge.
([#1119](https://github.com/schubydoo/clauster/pull/1119))
- Fix Stopped session cards vanishing when an unrelated `claude`
happened to be running in the same project folder, and stale phantom
cards never being cleaned up while another session on that project was
live: the dashboard's phantom-prune now decides per instance rather than
per project, and only treats an external session as a bridge when its
command line actually is one (including the `--rc` form, which it
previously failed to recognise).
([#1109](https://github.com/schubydoo/clauster/pull/1109))
- An Interactive Session whose preserved session was archived or deleted
while stopped now surfaces as an **error** on restart — instead of a
misleading "running" bridge that sits idle with no session — and its
stale pointer is cleared so the next launch starts fresh (#671). This is
the backstop for when the pre-launch check can't confirm the session
(e.g. credentials unavailable).
([#870](https://github.com/schubydoo/clauster/pull/870))
- Fix the launch popover's consent gates squeezing their explanation
text to about two words per line: Tabler's `.alert` is a flex row, so
the trust, bypass-permissions and MCP-approval gates laid their
explanation and controls out side by side until an explicit `display:
block` restored stacking.
([#1098](https://github.com/schubydoo/clauster/pull/1098))
- Fix the black strips that appeared around the live terminal after
resizing or zooming.
([#791](https://github.com/schubydoo/clauster/pull/791))
- Publish the repo's contributor conventions: `AGENTS.md`
(machine-facing) + `CLAUDE.md` are now committed, and CONTRIBUTING gains
the branching/review workflow (linear history, squash-merge, Greptile
review). ([#991](https://github.com/schubydoo/clauster/pull/991))
- The PyPI page now renders its README links correctly (they were
repo-relative, so every one 404'd there) and the package is classified
`Development Status :: 5 - Production/Stable`.
([#1085](https://github.com/schubydoo/clauster/pull/1085))
- Remove the outdated "v0.3 — multi-user" line from the README; clauster
is single-operator by design.
([#786](https://github.com/schubydoo/clauster/pull/786))
- Stop the environment reaper archiving a live bridge owned by another
clauster instance or OS user: it filtered an account-wide environment
list against an instance-scoped live set, so any bridge outside this
instance's `projects_root` read as a leftover and could be archived
mid-session — such an environment is now unattributable and skipped.
([#1102](https://github.com/schubydoo/clauster/pull/1102))
- The in-app restart (`POST /api/restart`) and the first-run setup
wizard's post-completion restart now work on the frozen binary (#1014):
`_reexec` no longer passes the binary path twice in argv (a PyInstaller
one-file build has `sys.executable == sys.argv[0]`), which previously
aborted with `unrecognized arguments` and left the server dead — masked
only where a service manager restarts on exit.
([#1056](https://github.com/schubydoo/clauster/pull/1056))
- Internal cleanup: dedupe config-write helpers and tighten type
annotations (no behavior change).
([#783](https://github.com/schubydoo/clauster/pull/783))
- Say up front when a stopped Server Mode card can't be resumed because
its project already has a live bridge.
([#1151](https://github.com/schubydoo/clauster/pull/1151))
- Resuming a stopped bridge now revives the same session instead of
creating a duplicate entry.
([#799](https://github.com/schubydoo/clauster/pull/799))
- The auth and web-UI guards now strip the configured `root_path` before
matching routes, so path classification stays correct behind a reverse
proxy that does not strip the mount prefix (defense-in-depth; the
supported prefix-stripping proxy is unaffected).
([#880](https://github.com/schubydoo/clauster/pull/880))
- A blank `auth.password_hash` can no longer be logged in with.
`verify_password` returned success for any *falsy* stored hash, so an
empty-string hash (reachable via `password_hash: ""` or a
present-but-empty `CLAUSTER_AUTH_PASSWORD_HASH`) made the source-visible
dummy password a working credential for both `/login` and the
`/api/reauth` step-up. Success now requires a real configured hash, and
a blank or whitespace-only `password_hash` normalizes to `null` at
config load — mirroring `api_token_hash` — so the value is refused at
both layers. The constant-time dummy verify still runs, so no timing
oracle is opened.
([#1070](https://github.com/schubydoo/clauster/pull/1070))
- An MCP server credential carried in a URL query string (`?api_key=…`),
a URL fragment, or a stdio `args` element is no longer serialized into
`claude mcp add-json`'s argv, where any local user could read it from
`ps` / `/proc/<pid>/cmdline`. The keep-secrets-off-argv guard
(`entry_needs_direct_write`) only recognized `env`/`headers` values and
`scheme://user@host` URLs, which key-name redaction cannot see past; it
now fails closed on a URL with a query, userinfo, or fragment component,
on a non-empty `args` list, and on an unparseable URL, routing those
entries to the direct (non-spawning) writer that produces identical
on-disk state. A credential embedded in the URL *path* remains uncovered
— every hosted-MCP URL has a path, so that needs a field-allowlist
redesign. ([#1070](https://github.com/schubydoo/clauster/pull/1070))
- `clauster restore --config-out` now writes the restored `clauster.yml`
atomically at mode `0600` instead of copying it at a umask-derived
`0644`. The config carries the argon2 `auth.password_hash` (and
`api_token_hash`), so the old behaviour published it to every local user
for offline cracking — and with `--force` it actively relaxed an
existing `0600` file. The write now goes through a `mkstemp` temp
(created owner-only) and an atomic replace, so the hash is never briefly
world-readable, a failed restore leaves no permissive file behind, and a
symlink sitting at `--config-out` is replaced rather than written
through to an unrelated file. The destination's parent directory is
deliberately left alone, since `--config-out` is often a shared
location. ([#1070](https://github.com/schubydoo/clauster/pull/1070))
- The `.bak` sibling that a local-scope settings write leaves beside
`.claude/settings.local.json` is now gitignored too. Only the exact
target path was ignored, so the backup — a plaintext copy of the
*previous* `env` map, this surface's one secret-bearing shape — sat
un-ignored next to it and could be swept into a commit by `git add -A`
and pushed. `ensure_gitignored` gained an opt-in `ignore_backup_sibling`
flag, set by all four writers of that file (settings, hooks, skill
overrides, permissions), and those writers now run it **before** the
write rather than after — so a failure between the two steps can no
longer leave the secret-bearing backup trackable.
([#1070](https://github.com/schubydoo/clauster/pull/1070))
- `claude setup-token`'s authorize URL is now recovered from its OSC 8
hyperlink, so the dashboard login shepherd can read it under a Windows
ConPTY where the terminal emits the URL as a hyperlink rather than plain
text. ([#909](https://github.com/schubydoo/clauster/pull/909))
- Internal cleanup from a slop-cleanup sweep: share the Anthropic HTTPS
transport + client base between the environments and code-sessions
clients, collapse the duplicate `~/.claude.json` atomic-writer onto the
shared core, and tighten a few return/param types. No behavior change.
([#873](https://github.com/schubydoo/clauster/pull/873))
- Launching an Interactive Session now pre-checks the preserved session
and, if it was archived or deleted, clears the stale pointer so the
launch starts fresh instead of reattaching a dead session and coming
back idle (#671). Best-effort — it never blocks a launch, and leaves the
pointer untouched on any uncertainty.
([#869](https://github.com/schubydoo/clauster/pull/869))
- The startup warning for an ignored `database_url` no longer cites an
incorrect version.
([#835](https://github.com/schubydoo/clauster/pull/835))
- On startup, clauster now garbage-collects its own stale bridge
pointers — only those that are both non-live and older than a 14-day
retention window — so long-dead pointers stop accumulating (#671). A
live bridge's pointer, or a recently-stopped session's (still
resumable), is never touched, and any error is logged, never fatal to
startup. ([#871](https://github.com/schubydoo/clauster/pull/871))
- Restore Resume on a stopped Server Mode session after a restart, and
stop a declined resume reporting success.
([#1147](https://github.com/schubydoo/clauster/pull/1147))
- Fix the live transcript on a running session so turns no longer
duplicate or lag, and the oldest/newest sort toggle now applies to the
live feed with a matching label.
([#751](https://github.com/schubydoo/clauster/pull/751))
- Add a read-only Transcript button to the live desktop/bridge session
row (hidden for worktree interactive sessions, whose transcript lives
under a different working directory).
([#918](https://github.com/schubydoo/clauster/pull/918))
- The Transcripts selector (and the resume/fork picker that shares its
endpoint) now opens near-instantly on unchanged transcripts (#1035):
each file's `turn_count` plus the picker's label/timestamp fields are
cached on a `(mtime, size)` stamp instead of re-parsing every `.jsonl`
on every open — which stalled ~20 s on a project with a large
transcript. Any append/change re-derives, so the listing stays correct.
([#1058](https://github.com/schubydoo/clauster/pull/1058))
- Trim `clauster.yml.example` from a dense inline-manual (247 lines,
~71% comments) to a concise quick-start template: one terse hint per
key, verbose prose moved to the docs, all keys and defaults preserved.
([#882](https://github.com/schubydoo/clauster/pull/882))
- Widen the launch popover so the trust-on-start text reads comfortably
instead of wrapping to a word or two per line.
([#760](https://github.com/schubydoo/clauster/pull/760))
- The README's feature catalogue is now a short summary that links to
the docs site rather than restating it, and SUPPORT.md documents the
release cadence (event-driven; security fixes immediate, regressions
within days). ([#1083](https://github.com/schubydoo/clauster/pull/1083))
- The dashboard now offers Interactive Session on Windows when the
ConPTY keeper (the `pty` extra) is installed, instead of always hiding
it — the mode-picker gate was stale after Windows ConPTY support landed.
([#916](https://github.com/schubydoo/clauster/pull/916))
- Harden Windows state/config file writes: a best-effort owner-only ACL
on the state dir, an in-process write lock serializing clauster's own
concurrent writers, a retry over transient file-sharing violations, and
LF (not CRLF) output.
([#915](https://github.com/schubydoo/clauster/pull/915))
- Interactive Session (true-resume PTY) now runs on Windows: the keeper
drives the bridge over a ConPTY pseudo-console via pywinpty (`pip
install 'clauster[pty]'`), falling back to Server Mode when the extra is
absent. ([#903](https://github.com/schubydoo/clauster/pull/903))
- Cancelling or finishing a Windows login no longer stalls for five
seconds and leaks a reader thread when the CLI leaves a child process
behind. ([#1126](https://github.com/schubydoo/clauster/pull/1126))
- On Windows, stopping a poisoned bridge, a timed-out clone, or a stuck
claustrum launcher now kills the whole process tree instead of leaving
its children running.
([#1127](https://github.com/schubydoo/clauster/pull/1127))
- Conversations from sessions spawned in a git worktree now appear in
the pty launch popover's Conversation picker (which branches a new
session off a past conversation, leaving the original untouched),
resolve when selected, and count toward the project's token rollup. A
worktree session runs with the worktree as its cwd, so Claude files its
transcript in a sibling `~/.claude/projects/<sanitized-cwd>/` directory;
every reader keyed on the project root alone, so those conversations
were invisible to the picker (a project whose only main-dir transcript
was live showed just "New conversation") and their tokens were missing
from usage. The project's own directory and its worktree siblings are
now searched together. Because sanitizing a path collapses `/`, `.`, `-`
and `_` all to `-`, a directory name cannot be mapped back to a path
unambiguously — a sibling project named `<project>--claude-worktrees-x`
produces a name carrying this project's worktree prefix — so every
candidate that is a real sibling project's directory is excluded, and an
unreadable projects root skips the worktree scan entirely rather than
admitting an ambiguous one. The session resolver accepts the same
directory set (its per-directory parent-identity check and stem
validation are unchanged, so a crafted session id still cannot escape),
and the liveness join counts worktree sessions too, keeping the listing
and the live set in lockstep — otherwise a running worktree session
would have shown as dormant and been offered in a picker meant for
finished conversations, branching from one still being written.
([#1076](https://github.com/schubydoo/clauster/pull/1076))
Co-authored-by: clauster-ci[bot] <289303168+clauster-ci[bot]@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Next split-epic chunk (REMEDIATION 3.2): the CLI was documented across five pages — a command list + headless blocks in
installation.md, three reference sections insideoperations.md's backup H2 (the audit's "four CLI references that aren't about backup"),api-tokeninpublic-api.md, and a README list missing seven headless commands entirely.docs/reference/cli.md— summary table + per-command sections. It is the full home for commands that only had scattered blocks (config reconcile,keepers,deps, the headless read/write commands,usage, thehash-*helpers,reap-environments— now documenting its real--archive/--force-deleteflags), and a concise entry + canonical link for commands whose depth lives on a task page (doctor,backup/restore,api-token,install-service,mcp).operations.md— theconfig reconcile/keepers/depssections move out; the backup H2 is about backup again; the intro points at the catalogue.installation.md— the subcommand catalogue collapses to a pointer (the pre-first-spawndoctornudge stays).depstext predated feat(deps): clauster deps install claustrum (Direct Session daemon) #984 and named onlyshawl; it now covers both pinned binaries (claustrum+shawl).depsand the seven headless commands (projects/status/sessions/logs/open/start/stop) and links the page. Nav +llms.txtupdated.{#id}heading attrs — inbound links in glossary/troubleshooting/platforms/installation are repointed and the ids also satisfy markdownlint MD051 for the in-page table links (the spaced{ #id }form does not; verified empirically).Verification: every flag/verb/exit-code claim checked against
__main__.py/deps.py/cli_write.py(independently re-verified by the docs-reviewer pass — no findings); full local gate green (4290 tests / 100% cov, lint-docs incl. MD051, strict mkdocs build with zero INFO link notices); all 14 anchors confirmed present in the built page.🤖 Generated with Claude Code