ccdesk 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+## 0.1.0 (2026-10-11)
+
+### Features
+
+* **scan:** read Claude Code config the way Claude Code loads it ([1410e35](https://github.com/ayagmar/ccdesk/commit/1410e35647bd3ce361e81e8e81dfb4fd2a67245a))
+* **server:** serve the UI locally with safe, reviewable edits ([c2fe6b6](https://github.com/ayagmar/ccdesk/commit/c2fe6b626d2b7ce42c4076a87307b34f0280f123))
+* **shared:** add config types and Claude Code data generated from upstream ([c084af7](https://github.com/ayagmar/ccdesk/commit/c084af74246caf7e2224b7a480453e4baab198a1))
+* **ui:** add the timetable UI for browsing and fixing config ([cb25c0f](https://github.com/ayagmar/ccdesk/commit/cb25c0f9edb081f323ca6aa7fc477a7c0db2de69))
+* **usage:** count tool calls from transcripts and suggest allow rules ([84687e5](https://github.com/ayagmar/ccdesk/commit/84687e5fabeaea62eaf2b405eee7236f4bd289f5))
+
+### Bug Fixes
+
+* **scan:** show git-ignored files as ignored on Windows ([38982e3](https://github.com/ayagmar/ccdesk/commit/38982e3ab6a9d841ef147c270ee285bc526124a5))

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ayagmar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,115 @@
-# Temporary Holding Version
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/ayagmar/ccdesk/master/assets/brand/banner-dark.webp" />
+  <img alt="Murmeli the marmot, ccdesk's station master, waving from a station desk beside a line of five coloured stops" src="https://raw.githubusercontent.com/ayagmar/ccdesk/master/assets/brand/banner-light.webp" />
+</picture>
 
-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.
+# ccdesk
+
+[![npm](https://img.shields.io/npm/v/ccdesk?style=flat-square&color=141414)](https://www.npmjs.com/package/ccdesk)
+[![CI](https://img.shields.io/github/actions/workflow/status/ayagmar/ccdesk/ci.yml?branch=master&style=flat-square&label=ci)](https://github.com/ayagmar/ccdesk/actions/workflows/ci.yml)
+[![node](https://img.shields.io/node/v/ccdesk?style=flat-square&color=141414)](package.json)
+[![license](https://img.shields.io/github/license/ayagmar/ccdesk?style=flat-square&color=141414)](LICENSE)
+
+See and change everything that shapes Claude Code on your machine: instruction files, settings, hooks, MCP servers, subagents, skills, plugins and auto memory.
+
+```sh
+npx ccdesk
+```
+
+ccdesk opens in your browser on the directory you ran it from and answers one question: **what is Claude told here, and where does each piece come from?**
+
+It is not a session viewer or a usage dashboard. It reads your config, shows it in the order Claude Code loads it, and lets you fix it.
+
+## What you see
+
+For any directory Claude Code has been used in:
+
+- **Instructions.** Every `CLAUDE.md`, `CLAUDE.local.md`, `AGENTS.md` and `.claude/rules/*.md` that applies, in load order. Each file shows whether it is loaded, skipped (and why), or loaded only for matching paths. It also lists the `@imports` it pulls in, whether it is tracked in git, untracked, git-ignored or personal, and whether it is a link into `~/.agents` that other coding agents read too.
+- **Settings.** Every key with the value Claude Code ends up using and the file it comes from: managed (including `managed-settings.d/`), user, project or local. Local settings are read from the repository root, as Claude Code does. Values overridden by a higher file are struck through, lists that merge across files are marked as merged, and a key set in a file Claude Code does not read it from is marked ignored.
+- **Permissions.** Every `allow`, `ask` and `deny` rule from every settings file, plus `defaultMode` and extra folders. Claude Code checks deny, then ask, then allow across all files, so an allow rule that the same rule in deny or ask overrides is flagged. Rules that wait for you to trust the folder, or that managed settings switch off, are marked as not in effect. An allow rule that covered no call in those sessions is marked, and calls Claude Code asked you about and you allowed show up as **suggested** allow rules, such as `Bash(pnpm test *)` or `WebFetch(domain:nodejs.org)`, with how many times you allowed them. A rule is not suggested when it would also cover a call you refused, or when your rules already decide those calls. Bash rules are suggested only for read-only commands such as `ls` or `jq`, for subcommands such as `git status` or `gh pr view` whose flags cannot run another command or write a file you did not name, and for script runners such as `pnpm test` or `git commit`, the same rule Claude Code's own prompt offers. A script runner runs your project's scripts or hooks, and npm and pnpm flags such as `--node-options` can make it run other code. A rule for `sed`, `make`, `go test`, `gh repo`, `git stash` or an install could allow far more than you approved.
+- **Built-in tools.** Every tool Claude Code ships with, what it does, and what happens when Claude reaches for it here: removed by a deny rule, asks first, or runs without asking. Rules that cover only some uses, such as `Bash(git push *)` or an `Edit` path, and `PreToolUse` hooks that match the tool are listed with it. Outcomes are as in Manual mode; the header says which mode sessions here start in. **Used** counts how often Claude called each tool in the sessions started here, or anywhere in the repository and its worktrees, since rules at a repository's root apply there too.
+- **Memory.** Auto memory for the directory, with filters by type (user, feedback, project, reference). Checks flag memories missing from `MEMORY.md`, broken `[[links]]`, a `MEMORY.md` too long to load in full, and memories saved in more than one directory. `autoMemoryEnabled`, `autoMemoryDirectory` and `CLAUDE_CODE_DISABLE_AUTO_MEMORY` are taken into account.
+- **Hooks, MCP servers, subagents, skills, commands, output styles and plugins**, each marked with the scope it comes from. Hooks turned off by `disableAllHooks` or `allowManagedHooksOnly`, MCP servers that wait for approval, are turned off, rejected or overridden by a closer definition, and plugins that are off are marked. Project skills come from the start directory and every parent up to the repository root. Subagents, skills and plugins can be filtered by kind.
+- **All settings.** Every key in the settings reference, set or not, grouped by area: what it does, which files Claude Code reads it from, its documented values and default, and the value it has here. Pick one to set it in the file you choose.
+- **Health checks.** Instruction files longer than the 200 lines the docs suggest, paragraphs repeated across files, and imports of files that do not exist.
+
+The header says when you have not yet accepted Claude Code's trust dialog for the folder, which is read from `~/.claude.json`. Settings files and `.mcp.json` files that are not valid JSON are listed at the top.
+
+If the directory is in a git repository, a strip under the line shows which of these files are tracked in git (everyone who clones gets them), not tracked yet, or git-ignored.
+
+**What Claude sees** switches to what your config puts in context when a session starts here, in load order: a custom output style, instruction files and their imports (without frontmatter and HTML comments, which Claude Code strips), the part of `MEMORY.md` that loads, the skill listing and your subagents' descriptions. Each shows its size and an estimated token count. Claude Code's system prompt and the tool names of MCP servers are listed but not counted. ccdesk does not show the text of an import outside the project and your Claude folders, and imports that wait for your approval are not counted.
+
+Below it, **When Claude touches a file** takes a path and lists what joins the session once Claude reads or edits it: path rules, skills with matching `paths`, and the `CLAUDE.md` files of the folders on the way.
+
+The line across the top is the load order: **M**anaged, **U**ser, **P**roject, **L**ocal, **A**uto memory and plugins (**X**). Click a stop to show only that scope.
+
+Every table can be filtered with `/`, narrowed with the chips above it, and sorted by clicking a column. Long tables show 50 rows at a time. Filters and sorting are kept in the URL, so a reload or a shared link opens the same view.
+
+**All directories** lists every directory Claude Code has sessions or memory for, and memories that exist in more than one of them.
+
+## What you can change
+
+- **Settings.** Pick a key from the schema, which comes with autocomplete and descriptions, or open an existing one. Choose which file to write: user, project or local; files Claude Code does not read the key from are not offered. Each value gets the control that fits its type: a checkbox, a choice list, a number field, a text field with the documented values one click away, one entry per line, or JSON. Before anything is written you see the exact diff, and Save writes exactly that diff: if the file changed in the meantime, ccdesk asks you to review again. Values are checked against Claude Code's settings schema, other keys are left as they are, and the old file is backed up first. A file that is a symlink, such as one in a dotfiles repository, is written through and stays a link. Undo is one click.
+- **Permission rules.** Move a rule to another list, remove it, or add a new one to the file you choose, with the same diff review and backup. A suggested rule goes into local settings by default, as Claude Code's "don't ask again" does.
+- **Built-in tools.** Turn a tool off for Claude with a deny rule in the file you choose, and turn it back on by removing the rules that remove it. A rule from managed settings cannot be removed, so the tool stays off.
+- **Memory.** Delete a memory you no longer want. ccdesk also removes its line from `MEMORY.md`, warns you if other memories link to it, keeps a backup, and offers undo. A memory missing from `MEMORY.md` can be added to it, and lines pointing at deleted files can be removed. Each of these shows the exact change to `MEMORY.md` first and is refused if the memory or the index changed after you reviewed it.
+- **Open in your editor.** Every file path has an open button. ccdesk uses `$CCDESK_EDITOR`, then `$VISUAL` or `$EDITOR` when they name a graphical editor, and otherwise your system's default app.
+
+Backups go to `~/.claude/backups/ccdesk/`. **Recent changes** lists every change ccdesk made. Each one can be restored after you review the diff, and the current file is backed up before it is replaced.
+
+ccdesk never deletes sessions and never writes `~/.claude.json`.
+
+## Keyboard
+
+| Key | Action |
+| --- | --- |
+| `j` / `k` | Next / previous row |
+| `1`–`9` | Jump to a section |
+| `/` | Filter rows |
+| `Ctrl K` / `⌘ K` | Jump to any directory, file, setting or rule, or a memory saved for any directory |
+| `Esc` | Close details |
+
+## Options
+
+```
+npx ccdesk [options]
+
+  --port <n>   Port to listen on (default: a free port)
+  --no-open    Print the URL instead of opening a browser
+  -h, --help   Show this help
+```
+
+ccdesk reads `~/.claude`, or `$CLAUDE_CONFIG_DIR` when it is set. It watches the config files for the open directory, so edits made in another editor or by Claude show up within a second. `~/.claude.json` is not watched, because Claude Code rewrites it during every session; changes to it show up when you return to ccdesk's tab. Requires Node.js 22.19 or newer.
+
+## Privacy and safety
+
+- The server listens on `127.0.0.1` only. Every API call needs a token generated for that run, which the browser receives in the URL fragment. Requests from other hosts or origins are refused.
+- Nothing leaves your machine.
+- Values under `env` and `headers` (in settings and MCP servers) are hidden in the UI, including in diffs and in a settings file reached through an import or a link. ccdesk never changes them: an edit that touches them is refused, and so is a restore that would put back older values. The user name, password and query string of a `url` (such as an MCP server's) are hidden too, wherever ccdesk shows it, and errors about a broken JSON file give only the line and column.
+- ccdesk never reads `~/.claude/.credentials.json`, even through a link or an import, and never writes `~/.claude.json`, even through a settings file that links to it. A `MEMORY.md` that links outside its memory folder is left alone.
+- To count tool calls and your answers to permission prompts, ccdesk reads the open directory's transcripts in `~/.claude/projects/`. Only counts and rule patterns (a command's program and subcommand, a fetch's domain) reach the page, never commands, file contents or anything else from a session. Your answers come from a transcript field Claude Code does not document, so older transcripts may not have them.
+- Backups can hold settings with secrets, so their folders and files are readable only by you.
+- Markdown is rendered without raw HTML, so an `AGENTS.md` from a cloned repo cannot run script in the page.
+
+## Settings schema
+
+The settings schema is generated from the `Settings` type in [`@anthropic-ai/claude-agent-sdk`](https://www.npmjs.com/package/@anthropic-ai/claude-agent-sdk), which is published with each Claude Code release. Which files each key is read from comes from the Scope column of the [settings reference](https://code.claude.com/docs/en/settings-reference). The built-in tools come from the [tools reference](https://code.claude.com/docs/en/tools-reference). The settings catalog comes from the same reference. A daily workflow regenerates all of them and opens a pull request when any of them changed. Some of Claude Code's behaviour, such as how rules match commands, is only described in the docs, so ccdesk follows it by hand and cites the docs section in the code; the workflow also fingerprints every cited section and lists the ones that changed in the pull request.
+
+## Development
+
+```sh
+pnpm install
+pnpm dev        # API on 127.0.0.1:4319
+pnpm dev:ui     # UI with hot reload on 127.0.0.1:4320
+pnpm check      # typecheck, lint, format, tests, build
+pnpm schema     # regenerate src/shared/settings.schema.json
+pnpm scopes     # regenerate src/shared/settings-scopes.json from the settings reference
+pnpm tools      # regenerate src/shared/builtin-tools.json from the tools reference
+pnpm docs:fingerprints  # fingerprint the docs sections the code cites; prints the ones that changed
+```
+
+Tests never touch your real `~/.claude`. Each one builds a throwaway home directory.
+
+## License
+
+MIT

package/dist/server/backups.js

@@ -0,0 +1,226 @@
+import { lstat, readdir, readFile, realpath } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
+import {} from "../shared/types.js";
+import { assertMemoryDir, indexPathIn, revisionOfBoth } from "./mutations.js";
+import {} from "./scan/env.js";
+import { isRecord, isWithin, redactSecrets, revisionOf, shownText, shownUrl, } from "./scan/files.js";
+import { backupRoot, MANIFEST, RefusedError, readIfExists, recordChange, removeExactly, SNAPSHOT, serially, writeAtomic, } from "./write.js";
+const KINDS = new Set(["settings", "memory-index", "memory-delete"]);
+function strings(value) {
+    return Array.isArray(value) && value.every((v) => typeof v === "string");
+}
+/** A backup folder's manifest; anything that does not look like one ccdesk wrote is skipped. */
+async function readManifest(env, id) {
+    // ccdesk's ids are letters, digits and dashes, so no id can name a folder outside the root.
+    if (!/^[\w-]+$/.test(id))
+        return null;
+    const text = await readIfExists(env, join(backupRoot(env), id, MANIFEST)).catch(() => null);
+    if (text === null)
+        return null;
+    let data;
+    try {
+        data = JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+    if (!isRecord(data) ||
+        typeof data.kind !== "string" ||
+        !KINDS.has(data.kind) ||
+        typeof data.target !== "string" ||
+        typeof data.createdAt !== "string" ||
+        typeof data.before !== "string" ||
+        typeof data.after !== "string" ||
+        (data.removedIndexLines !== undefined && !strings(data.removedIndexLines)))
+        return null;
+    return data;
+}
+/** The changes ccdesk made, newest first, a page at a time. */
+export async function listBackups(env, { before, limit }) {
+    const ids = (await readdir(backupRoot(env)).catch(() => [])).sort().reverse();
+    const changes = [];
+    for (const id of ids) {
+        if (before !== undefined && id >= before)
+            continue;
+        const manifest = await readManifest(env, id);
+        if (!manifest)
+            continue;
+        if (changes.length === limit)
+            return { changes, more: true };
+        changes.push({
+            id,
+            kind: manifest.kind,
+            target: manifest.target,
+            createdAt: manifest.createdAt,
+            created: manifest.before === revisionOf(null),
+            ...(manifest.after === "pending" || manifest.after === "partial" ? { incomplete: true } : {}),
+        });
+    }
+    return { changes, more: false };
+}
+/** A settings file Claude Code reads: your user file, or settings(.local).json in a .claude folder. */
+function isSettingsFile(env, path) {
+    if (path === join(env.claudeDir, "settings.json"))
+        return true;
+    return (["settings.json", "settings.local.json"].includes(basename(path)) &&
+        basename(dirname(path)) === ".claude");
+}
+/**
+ * Every value ccdesk shows hidden and never changes in a settings file: env and headers objects,
+ * and URLs with a user, password or query.
+ */
+function hiddenValues(text) {
+    const found = [];
+    const walk = (value) => {
+        if (Array.isArray(value))
+            value.forEach(walk);
+        if (!isRecord(value))
+            return;
+        for (const [key, inner] of Object.entries(value)) {
+            if ((key === "env" || key === "headers") && isRecord(inner))
+                found.push(inner);
+            else if (key === "url" && typeof inner === "string" && shownUrl(inner) !== inner)
+                found.push(inner);
+            else
+                walk(inner);
+        }
+    };
+    try {
+        walk(text === null ? null : JSON.parse(text));
+    }
+    catch {
+        return text ?? "";
+    }
+    return JSON.stringify(found);
+}
+/** Settings are shown parsed with env and header values hidden, as everywhere else in ccdesk. */
+function shownSettings(text) {
+    if (text === null)
+        return null;
+    try {
+        return `${JSON.stringify(redactSecrets(JSON.parse(text)), null, 2)}\n`;
+    }
+    catch {
+        return "(not valid JSON; open the file to see it)\n";
+    }
+}
+async function planRestore(env, id) {
+    const manifest = await readManifest(env, id);
+    if (!manifest)
+        throw new RefusedError("That backup is gone or was not made by ccdesk.");
+    const root = await realpath(backupRoot(env));
+    const dir = await realpath(join(root, id));
+    if (!isWithin(root, dir) || dir === root)
+        throw new RefusedError("Not a ccdesk backup.");
+    let target = manifest.target;
+    if (manifest.kind === "settings" && !isSettingsFile(env, target))
+        throw new RefusedError("This backup does not point at a settings file.");
+    if (manifest.kind === "memory-index" && basename(target) !== "MEMORY.md")
+        throw new RefusedError("This backup does not point at a MEMORY.md.");
+    if (manifest.kind !== "settings") {
+        const store = await assertMemoryDir(env, dirname(target));
+        // The same confinement as any other MEMORY.md change: a link out of the folder is refused.
+        target =
+            manifest.kind === "memory-index" ? await indexPathIn(store) : join(store, basename(target));
+        // A deleted memory comes back only as a topic file, as ccdesk deletes only those.
+        if (manifest.kind === "memory-delete" &&
+            (!target.endsWith(".md") || basename(target) === "MEMORY.md"))
+            throw new RefusedError("This backup does not point at a memory file.");
+    }
+    let saved = null;
+    if (manifest.before !== revisionOf(null)) {
+        const snapshot = join(dir, SNAPSHOT);
+        if (!(await lstat(snapshot).catch(() => null))?.isFile())
+            throw new RefusedError("The backed-up file is missing from the backup folder.");
+        saved = await readFile(snapshot, "utf8");
+        if (revisionOf(saved) !== manifest.before)
+            throw new RefusedError("The backed-up file was changed after ccdesk saved it.");
+    }
+    const plan = {
+        manifest: { ...manifest, target },
+        current: await readIfExists(env, target),
+        saved,
+    };
+    if (manifest.kind === "memory-delete") {
+        const path = await indexPathIn(dirname(target));
+        const text = await readIfExists(env, path);
+        const missing = (manifest.removedIndexLines ?? []).filter((l) => !(text ?? "").split("\n").includes(l));
+        plan.index = { path, text, missing };
+    }
+    return plan;
+}
+/** What a restore must find unchanged: the file, and for a deleted memory MEMORY.md as well. */
+function planRevision({ current, index }) {
+    return index ? revisionOfBoth(current, index.text) : revisionOf(current);
+}
+function blockedReason({ manifest, current, saved }) {
+    if (saved === null)
+        return "ccdesk created this file, so there is no earlier version to put back. Change it in place instead.";
+    if (manifest.kind === "settings" && hiddenValues(current) !== hiddenValues(saved))
+        return "Hidden values in this file (env, headers or a URL's key) changed since the backup. ccdesk does not show or change those, so restore this one by hand.";
+    // A retry after a restore that wrote the memory but not MEMORY.md finds the memory already back.
+    if (manifest.kind === "memory-delete" && current !== null && current !== saved)
+        return "A memory with this file name exists again; delete or rename it first.";
+    return undefined;
+}
+export async function previewRestore(env, id) {
+    const plan = await planRestore(env, id);
+    const { manifest, current, saved, index } = plan;
+    const shown = manifest.kind === "settings" ? shownSettings : shownText;
+    const before = shown(current);
+    const after = shown(saved) ?? "";
+    const blocked = blockedReason(plan);
+    return {
+        id,
+        kind: manifest.kind,
+        target: manifest.target,
+        before,
+        after,
+        revision: planRevision(plan),
+        ...(blocked ? { blocked } : {}),
+        ...(index && index.missing.length > 0 ? { indexLines: index.missing } : {}),
+    };
+}
+/** Puts a backed-up file back, if the file is still as it was when the restore was reviewed. */
+export function restoreBackup(env, id, expectedRevision) {
+    return serially(async () => {
+        const plan = await planRestore(env, id);
+        const { manifest, current, saved, index } = plan;
+        const blocked = blockedReason(plan);
+        if (blocked || saved === null)
+            throw new RefusedError(blocked);
+        if (planRevision(plan) !== expectedRevision)
+            throw new RefusedError("The file changed since you reviewed this restore; review it again.");
+        const { target } = manifest;
+        if (manifest.kind !== "memory-delete") {
+            await recordChange(env, { kind: manifest.kind, target, before: current }, async () => {
+                await writeAtomic(env, target, saved, revisionOf(current));
+                return { revision: revisionOf(saved) };
+            });
+            return { target };
+        }
+        // A memory and its MEMORY.md lines come back together: when the index cannot be written, the
+        // memory just put back is removed again, so a refused restore leaves both as they were.
+        const created = current === null;
+        if (created)
+            await writeAtomic(env, target, saved, revisionOf(null));
+        try {
+            if (index && index.missing.length > 0) {
+                const lines = (index.text ?? "").split("\n");
+                while (lines.at(-1) === "")
+                    lines.pop();
+                const next = `${[...lines, ...index.missing].join("\n")}\n`;
+                await recordChange(env, { kind: "memory-index", target: index.path, before: index.text }, async () => {
+                    await writeAtomic(env, index.path, next, revisionOf(index.text));
+                    return { revision: revisionOf(next) };
+                });
+            }
+        }
+        catch (error) {
+            if (created)
+                await removeExactly(target, revisionOf(saved));
+            throw error;
+        }
+        return { target };
+    });
+}

package/dist/server/cli.js

@@ -0,0 +1,92 @@
+#!/usr/bin/env node
+import { spawn } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import { fileURLToPath } from "node:url";
+import { parseArgs } from "node:util";
+import { scanEnvFromProcess } from "./scan/env.js";
+import { createCcdeskServer } from "./server.js";
+const HELP = `ccdesk: see and manage what shapes Claude Code on this machine
+
+Usage: npx ccdesk [options]
+
+Options:
+  --port <n>   Port to listen on (default: a free port)
+  --no-open    Print the URL instead of opening a browser
+  -h, --help   Show this help
+
+ccdesk reads ~/.claude (or $CLAUDE_CONFIG_DIR) and opens on the directory you run it from.
+It listens on 127.0.0.1 only.`;
+const DEV_PORT = 4319;
+const DEV_TOKEN = "dev";
+function options() {
+    try {
+        return parseArgs({
+            options: {
+                port: { type: "string" },
+                open: { type: "boolean", default: true },
+                dev: { type: "boolean", default: false },
+                help: { type: "boolean", short: "h", default: false },
+            },
+            allowNegative: true,
+        }).values;
+    }
+    catch (error) {
+        console.error(`ccdesk: ${error.message}\n\n${HELP}`);
+        process.exit(2);
+    }
+}
+function main() {
+    const values = options();
+    if (values.help) {
+        console.log(HELP);
+        return;
+    }
+    const dev = values.dev;
+    const port = values.port ? Number(values.port) : dev ? DEV_PORT : 0;
+    if (!Number.isInteger(port) || port < 0 || port > 65535) {
+        console.error(`ccdesk: invalid --port ${values.port}`);
+        process.exitCode = 2;
+        return;
+    }
+    const token = dev ? DEV_TOKEN : randomBytes(18).toString("base64url");
+    const server = createCcdeskServer({
+        env: scanEnvFromProcess(),
+        launchDir: process.cwd(),
+        token,
+        uiDir: dev ? null : fileURLToPath(new URL("../ui", import.meta.url)),
+    });
+    server.on("error", (error) => {
+        console.error(error.code === "EADDRINUSE"
+            ? `ccdesk: port ${port} is already in use`
+            : `ccdesk: ${error.message}`);
+        process.exitCode = 1;
+    });
+    server.listen(port, "127.0.0.1", () => {
+        const address = server.address();
+        const actual = typeof address === "object" && address ? address.port : port;
+        if (dev) {
+            console.log(`ccdesk API on http://127.0.0.1:${actual} (dev token "${DEV_TOKEN}"); run \`pnpm dev:ui\` for the UI`);
+            return;
+        }
+        const url = `http://127.0.0.1:${actual}/#token=${token}`;
+        console.log(`ccdesk is running at ${url}\nPress Ctrl+C to stop.`);
+        if (values.open)
+            openBrowser(url);
+    });
+    process.once("SIGINT", () => {
+        // An open browser tab keeps a connection alive, which would hold close() open.
+        server.close(() => process.exit(0));
+        server.closeAllConnections();
+    });
+}
+function openBrowser(url) {
+    const [command, args] = process.platform === "darwin"
+        ? ["open", [url]]
+        : process.platform === "win32"
+            ? ["cmd", ["/c", "start", "", url]]
+            : ["xdg-open", [url]];
+    const child = spawn(command, args, { stdio: "ignore", detached: true });
+    child.on("error", () => console.log("Could not open a browser; open the URL above."));
+    child.unref();
+}
+main();