ccdesk 0.0.0-stage → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,90 @@
+# Changelog
+
+## [0.2.0](https://github.com/ayagmar/ccdesk/compare/v0.1.0...v0.2.0) (2026-10-12)
+
+### Features
+
+* **agents:** create, change and delete subagent files ([1d8d011](https://github.com/ayagmar/ccdesk/commit/1d8d011c93c08dc8435ad304f5061378e8c4c1b7)), references [sub-agents#supported-frontmatter-fields](https://github.com/sub-agents/issues/supported-frontmatter-fields)
+* **cli:** add --config-dir to read another Claude folder ([777712a](https://github.com/ayagmar/ccdesk/commit/777712aeb91da62f3f323292c8050b600ff59f5a))
+* compare the settings of two directories ([9ec5e56](https://github.com/ayagmar/ccdesk/commit/9ec5e56b0d4f1cfc85b48accaea00ac59cf592c2))
+* describe a claude -p or SDK session as well as an interactive one ([45c0ad1](https://github.com/ayagmar/ccdesk/commit/45c0ad180c1a26074d151375f99b80ddb20dd99e)), references [permissions#what-runs-before-you-trust-a-folder](https://github.com/permissions/issues/what-runs-before-you-trust-a-folder) [#when-your-local-settings-file-needs-trust](https://github.com/ayagmar/ccdesk/issues/when-your-local-settings-file-needs-trust) [hooks#workspace-trust](https://github.com/hooks/issues/workspace-trust)
+* **hooks:** add, change and remove hooks in settings files ([7307b6b](https://github.com/ayagmar/ccdesk/commit/7307b6b1f3b7baa1ced8db4be6695e8456c87ef8))
+* list claude mcp edits in Recent changes ([bfc153c](https://github.com/ayagmar/ccdesk/commit/bfc153c5f3489143d73c2cfcc75a5fc2c1175e93))
+* **mcp:** add, change and remove MCP servers ([40f88a6](https://github.com/ayagmar/ccdesk/commit/40f88a6cce41f4c04d3816dfbd540cb2435482e9))
+* **mcp:** check server entries against a schema of the documented fields ([3bfac6c](https://github.com/ayagmar/ccdesk/commit/3bfac6c884c07c03430fd896fe5ec2ba558cbc43))
+* **mcp:** say what approved, rejected or holds a .mcp.json server ([1a42288](https://github.com/ayagmar/ccdesk/commit/1a4228880a81a24468caebab84aa27e85fdbde62))
+* **site:** add the documentation site with llms.txt ([25148e4](https://github.com/ayagmar/ccdesk/commit/25148e43f4f5190c000f0e3f4aaeb98872c9ef53))
+* **site:** capture frames for a video with screenshots --video ([e754f1f](https://github.com/ayagmar/ccdesk/commit/e754f1fd910834044158ca3c2125d706e3ca5d1c))
+* **site:** light up each scope's rows in the hero screenshot ([af20413](https://github.com/ayagmar/ccdesk/commit/af204130ea0e1eee8cd428ba7a67df10bb0a6ffa))
+* **site:** open each landing page question to the rows that answer it ([29d6815](https://github.com/ayagmar/ccdesk/commit/29d6815b628e68751d9de91d10c07a5805d27bc1))
+* **site:** open screenshots in place, add motion and load faster ([340ee81](https://github.com/ayagmar/ccdesk/commit/340ee817449d06910fbc3ae3f6f2003c804014d9))
+* **ui:** say that the page describes an interactive session ([c618a77](https://github.com/ayagmar/ccdesk/commit/c618a776a1313d44f8b88c05c9a660e64e55bb38))
+* undo a change that created its file by removing the file ([e6297e3](https://github.com/ayagmar/ccdesk/commit/e6297e35296b0c2a9f4fd222bfff71f78216211e))
+
+### Bug Fixes
+
+* **agents:** save a new agent typed as reviewer.md as reviewer.md, not reviewer.md.md ([2d07508](https://github.com/ayagmar/ccdesk/commit/2d07508eeb50dd9fff98e9816e58c1eaa25abc21))
+* **backups:** record restored memories and restore halfway deletes ([3bfcbcf](https://github.com/ayagmar/ccdesk/commit/3bfcbcfd487956dd9eddd9f7252c9093887f95d9))
+* hide keys in MCP server args ([922475c](https://github.com/ayagmar/ccdesk/commit/922475c067b313f75aee2332f01066bc4739ab55))
+* **hooks:** hide the user name, password and query of an http hook's URL ([8b40d25](https://github.com/ayagmar/ccdesk/commit/8b40d25867ca6cbf76164a27584a15309803bb44))
+* **instructions:** head your user CLAUDE.md as ~/.claude/CLAUDE.md, not .claude/CLAUDE.md ([683b1c8](https://github.com/ayagmar/ccdesk/commit/683b1c88bd244f1b033b3f546f7944599a0327de))
+* **instructions:** say why a linked rule with paths does not load ([922788d](https://github.com/ayagmar/ccdesk/commit/922788d34fdc9333679d8792eb1865aa70acd831))
+* match what Claude Code loads and keep hidden values out of edits ([9997c26](https://github.com/ayagmar/ccdesk/commit/9997c2652be271f1c6b3326f84218cfbe27f031d))
+* **mcp:** count a "use all servers" answer to the .mcp.json prompt ([3008f9c](https://github.com/ayagmar/ccdesk/commit/3008f9c9792174d2334ce641555167962b7f67e3))
+* **mcp:** hide a server's secrets in claude's own error message ([2b7882b](https://github.com/ayagmar/ccdesk/commit/2b7882b5e1df3d3540c06a5c8d7c559ec6ce4328))
+* **mcp:** pass names safely to claude mcp and keep servers when it fails ([69b9353](https://github.com/ayagmar/ccdesk/commit/69b9353be3ecd96de2c29ed91183bfce0dfc6274))
+* **mcp:** read and add local servers under the repository root only ([c536737](https://github.com/ayagmar/ccdesk/commit/c536737a8e8d05946d43b0bbe74364a890141cd8))
+* **memory:** remove a [[name]] index line when its memory is deleted ([a08fbdf](https://github.com/ayagmar/ccdesk/commit/a08fbdf899c17e958c0ac98678d44e4b9b259dd5))
+* **memory:** stop flagging a 200-line MEMORY.md that ends in a newline as cut off ([07a670b](https://github.com/ayagmar/ccdesk/commit/07a670b209593d315e7850e6145e8443b5c01554))
+* **permissions:** say that ccdesk reads commands and addresses to match rules ([ca60592](https://github.com/ayagmar/ccdesk/commit/ca605920235512d041b03b0fbea57c4967f1ac70))
+* **readme:** link each screenshot to its full-size image ([18837fc](https://github.com/ayagmar/ccdesk/commit/18837fc055aede576926f15d90b031c3b6a19fa9))
+* **scan:** hold back settings-file hooks until the folder is trusted ([ab9ea97](https://github.com/ayagmar/ccdesk/commit/ab9ea973e153b343530ae5c945b8f71a28dd7895)), references [hooks#workspace-trust](https://github.com/hooks/issues/workspace-trust)
+* **scan:** name plugin skills and commands with their plugin ([43d178a](https://github.com/ayagmar/ccdesk/commit/43d178a0f14c9479b576c6260eea1541f5fb6d53)), references [skills#how-a-skill-gets-its-command-name](https://github.com/skills/issues/how-a-skill-gets-its-command-name) [plugins-reference#name](https://github.com/plugins-reference/issues/name)
+* **server:** put a file back when ccdesk cannot read it while removing it ([bfa4931](https://github.com/ayagmar/ccdesk/commit/bfa49318dc4df99605cc570e004cf6ed0b41543e))
+* **server:** refuse a hard link to the credentials file ([8689378](https://github.com/ayagmar/ccdesk/commit/86893788ee20e1c0fc53464306167a5329968d6e))
+* **server:** refuse a restore that would change hidden keys in args ([5ab6b40](https://github.com/ayagmar/ccdesk/commit/5ab6b409db633d82ac2cea37833639eff1d88c8d))
+* **server:** refuse to save a file that has other hard links ([4fe7445](https://github.com/ayagmar/ccdesk/commit/4fe7445daba710babba8e5bc3826060389857f24))
+* **server:** stop on SIGTERM and answer a malformed URL with 400 ([a519fcb](https://github.com/ayagmar/ccdesk/commit/a519fcb7b0f34c21ac35b81b606ec0bc350119d6))
+* **server:** watch what a scan read even when the watch starts after it ([554a3d5](https://github.com/ayagmar/ccdesk/commit/554a3d58e9361c209313d258f665b54a09792757))
+* **settings:** leave out sandbox fields Claude Code ignores from a file ([97bf3a9](https://github.com/ayagmar/ccdesk/commit/97bf3a95407a21682b0579482bd558071698f40a))
+* **settings:** say why a value that may only tighten a key is ignored ([6e01ce8](https://github.com/ayagmar/ccdesk/commit/6e01ce882f08d3a34d1a2725f5371852e6c5b9ce))
+* **settings:** show a value set only in the older local file in the details ([57cbc45](https://github.com/ayagmar/ccdesk/commit/57cbc453449eb1b3562062817091f8baa449ccef))
+* **site:** draw the GitHub icon in the text colour ([f8dce1c](https://github.com/ayagmar/ccdesk/commit/f8dce1c184b98ed168e3f516f040ce22269a4dd3))
+* **site:** line the header search up with the landing page's wider column ([95a1762](https://github.com/ayagmar/ccdesk/commit/95a176252a28e8f98253bd816212af0f8f54111e))
+* **site:** name the app section each landing page question is answered in ([977a65c](https://github.com/ayagmar/ccdesk/commit/977a65c41b43fe03320a9181cbb02e1011c3be64))
+* **tools:** list a whole-Bash rule under Monitor, whose commands it covers ([52e09b5](https://github.com/ayagmar/ccdesk/commit/52e09b5ead6570c620d0ef9ba9ba5cb8a880ac28))
+* **tools:** show a failed count as unknown instead of counting forever ([b7b628d](https://github.com/ayagmar/ccdesk/commit/b7b628d2d6d672a245d9940d51edcfbc42f29f3a))
+* **ui:** give the session switch its own line so the directory name keeps its room ([c43db64](https://github.com/ayagmar/ccdesk/commit/c43db642f6d980f8efea19387d09f11d3082272c))
+* **ui:** give the tables the room until a row is picked and keep the directory name whole ([8059bea](https://github.com/ayagmar/ccdesk/commit/8059bea410755683637338814413fcc7f1b7844a))
+* **ui:** keep an edited draft when the file changes underneath it ([5f72626](https://github.com/ayagmar/ccdesk/commit/5f726268c96160ba703fcec684fd420b0c7a9d3d))
+* **ui:** keep the save toast above sticky table headers ([711c670](https://github.com/ayagmar/ccdesk/commit/711c6706fa276511ebe4968f05d105f7244722cf))
+* **ui:** line up the columns on Recent changes ([112e732](https://github.com/ayagmar/ccdesk/commit/112e732a3eb776ce121e479538521c2f078551cc))
+* **ui:** offer no undo for a change that created its file ([8103ddc](https://github.com/ayagmar/ccdesk/commit/8103ddc8c78ac323039a778be83c3d89f830851a))
+* **ui:** offer only settings files that exist here when adding a rule or hook ([34bc591](https://github.com/ayagmar/ccdesk/commit/34bc5914cd23d87da8b2574bf7e4a5402a1571f8))
+* **ui:** say that claude mcp edits pass values on claude's command line ([06d971e](https://github.com/ayagmar/ccdesk/commit/06d971e3ff9c7af693bbf9b1d9226b82dcf16100))
+* **ui:** ship the small font files instead of inlining them past the CSP ([166ad6a](https://github.com/ayagmar/ccdesk/commit/166ad6a29df96b5df8c6b043e6ed23654226e978))
+* **usage:** answer a stopped count even while one of its reads hangs ([9495017](https://github.com/ayagmar/ccdesk/commit/9495017641d050f15ba33d19e13db0b2fc9c0ed9))
+* **usage:** stop tool-call counts nobody waits for or that run too long ([cc89847](https://github.com/ayagmar/ccdesk/commit/cc898474b3588c5a64c38fca1635e9bed20f1a27))
+
+### Performance Improvements
+
+* **server:** cap the usage cache and keep only what matching reads ([6e5eeea](https://github.com/ayagmar/ccdesk/commit/6e5eeea66ce209c9598a417540ae0eb3415986b9))
+* **server:** reuse a current scan for the path tester ([cb48481](https://github.com/ayagmar/ccdesk/commit/cb484810daa5a5469cef5688d740ba7a418a3756))
+
+### Reverts
+
+* **site:** drop screenshots --video ([0009af4](https://github.com/ayagmar/ccdesk/commit/0009af451f02da3a2d41847e1ce21fbda2d6e892))
+
+## 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,132 @@
-# 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)](https://github.com/ayagmar/ccdesk/blob/master/package.json)
+[![license](https://img.shields.io/github/license/ayagmar/ccdesk?style=flat-square&color=141414)](https://github.com/ayagmar/ccdesk/blob/master/LICENSE)
+
+See and change everything Claude Code loads on your machine: instruction files, settings, permissions, hooks, MCP servers, subagents, skills, plugins and auto memory.
+
+```sh
+npx ccdesk
+```
+
+Each piece lives in its own file, at one of six scopes: managed, user, project, local, auto memory or a plugin. ccdesk opens in your browser on the directory you ran it from, lists everything that applies there in the order Claude Code loads it, and names the file behind each piece. When something is wrong, change it on the same page: you review the diff first, and every edit has a backup and an undo. It is not a session viewer or a usage dashboard.
+
+**Docs:** [ayagmar.github.io/ccdesk](https://ayagmar.github.io/ccdesk/)
+
+<a href="https://raw.githubusercontent.com/ayagmar/ccdesk/master/site/src/assets/screenshots/directory-dark.webp"><picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/ayagmar/ccdesk/master/site/src/assets/screenshots/directory-dark.webp" /><img alt="ccdesk on a made-up project: the load order across the top, then instruction files and settings, each marked with the scope it comes from" src="https://raw.githubusercontent.com/ayagmar/ccdesk/master/site/src/assets/screenshots/directory-light.webp" /></picture></a>
+
+## Questions it answers
+
+- Why does Claude ask me before every `git push` here? ([Permissions](https://ayagmar.github.io/ccdesk/permissions/))
+- Which model does this repository use, and which file set it? ([Settings](https://ayagmar.github.io/ccdesk/settings/))
+- Is my `AGENTS.md` loaded at all? ([Instructions](https://ayagmar.github.io/ccdesk/instructions/))
+- How much context does my config take before I type anything? ([What Claude sees](https://ayagmar.github.io/ccdesk/what-claude-sees/))
+- What do I keep approving by hand, and which allow rules have I stopped needing? ([Permissions](https://ayagmar.github.io/ccdesk/permissions/#suggested-rules))
+- Which project MCP servers still wait for approval? ([MCP servers](https://ayagmar.github.io/ccdesk/mcp-servers/))
+
+## What it covers
+
+| | What you see | What you can change | Docs |
+| --- | --- | --- | --- |
+| **Instructions** | Every `CLAUDE.md`, `AGENTS.md` and `.claude/rules/*.md` that applies, in load order, with why a file is skipped and who else sees it | Open it in your editor | [Instructions](https://ayagmar.github.io/ccdesk/instructions/) |
+| **Settings** | The value Claude Code ends up using for each key, the file it comes from, and the values it overrides | Set or remove any documented key in user, project or local settings, picked from the schema | [Settings](https://ayagmar.github.io/ccdesk/settings/) |
+| **Permissions** | Every allow, ask and deny rule, which ones never take effect, and allow rules that covered no call | Add, move or remove rules; accept allow rules suggested from the calls you approved | [Permissions](https://ayagmar.github.io/ccdesk/permissions/) |
+| **Built-in tools** | What happens when Claude reaches for each tool here, and how often it did | Turn a tool off with a deny rule, or back on | [Tool usage](https://ayagmar.github.io/ccdesk/tool-usage/) |
+| **Hooks** | Every hook with its scope, and the ones that are turned off | Add, change or remove hooks in user, project or local settings | [Hooks](https://ayagmar.github.io/ccdesk/hooks/) |
+| **MCP servers** | Every server, and the ones waiting for approval, off, rejected or overridden | Add, change or remove servers in `.mcp.json`, or through `claude mcp` for user and local ones | [MCP servers](https://ayagmar.github.io/ccdesk/mcp-servers/) |
+| **Subagents** | Every agent from managed, project, user and plugin folders, and which definition wins | Create, change or delete agent files | [Subagents](https://ayagmar.github.io/ccdesk/subagents/) |
+| **Skills and plugins** | Skills, commands, output styles and plugins, by scope | Open them in your editor | [Skills and plugins](https://ayagmar.github.io/ccdesk/skills-and-plugins/) |
+| **Memory** | Auto memory for the directory, with memories missing from `MEMORY.md`, broken links and duplicates flagged | Delete a memory and its index line, fix the index | [Memory](https://ayagmar.github.io/ccdesk/memory/) |
+| **What Claude sees** | What your config puts in context when a session starts, with sizes and estimated tokens | | [What Claude sees](https://ayagmar.github.io/ccdesk/what-claude-sees/) |
+
+<table>
+  <tr>
+    <td width="50%"><a href="https://raw.githubusercontent.com/ayagmar/ccdesk/master/site/src/assets/screenshots/permissions-dark.webp"><picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/ayagmar/ccdesk/master/site/src/assets/screenshots/permissions-dark.webp" /><img alt="The permissions table with rules from user, project and local settings, and three suggested allow rules" src="https://raw.githubusercontent.com/ayagmar/ccdesk/master/site/src/assets/screenshots/permissions-light.webp" /></picture></a></td>
+    <td width="50%"><a href="https://raw.githubusercontent.com/ayagmar/ccdesk/master/site/src/assets/screenshots/context-dark.webp"><picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/ayagmar/ccdesk/master/site/src/assets/screenshots/context-dark.webp" /><img alt="What Claude sees: instruction files, memory and skill listing in load order, with sizes and token estimates" src="https://raw.githubusercontent.com/ayagmar/ccdesk/master/site/src/assets/screenshots/context-light.webp" /></picture></a></td>
+  </tr>
+  <tr>
+    <td>Permissions, with allow rules suggested from the calls you approved</td>
+    <td>What Claude sees when a session starts here</td>
+  </tr>
+  <tr>
+    <td><a href="https://raw.githubusercontent.com/ayagmar/ccdesk/master/site/src/assets/screenshots/memory-dark.webp"><picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/ayagmar/ccdesk/master/site/src/assets/screenshots/memory-dark.webp" /><img alt="Auto memory for a directory, with checks on the MEMORY.md index" src="https://raw.githubusercontent.com/ayagmar/ccdesk/master/site/src/assets/screenshots/memory-light.webp" /></picture></a></td>
+    <td><a href="https://raw.githubusercontent.com/ayagmar/ccdesk/master/site/src/assets/screenshots/changes-dark.webp"><picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/ayagmar/ccdesk/master/site/src/assets/screenshots/changes-dark.webp" /><img alt="Recent changes: every edit ccdesk made, each one restorable" src="https://raw.githubusercontent.com/ayagmar/ccdesk/master/site/src/assets/screenshots/changes-light.webp" /></picture></a></td>
+  </tr>
+  <tr>
+    <td>Auto memory and its index</td>
+    <td>Every change ccdesk made, ready to restore</td>
+  </tr>
+</table>
+
+## How changes are made
+
+<a href="https://raw.githubusercontent.com/ayagmar/ccdesk/master/site/src/assets/screenshots/review-dark.webp"><picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/ayagmar/ccdesk/master/site/src/assets/screenshots/review-dark.webp" /><img align="right" width="300" alt="Changing the model setting: the files that set it, the value Claude Code uses, and the diff to project settings before saving" src="https://raw.githubusercontent.com/ayagmar/ccdesk/master/site/src/assets/screenshots/review-light.webp" /></picture></a>
+
+- You see the exact diff before anything is written, and Save writes exactly that diff. If the file changed in the meantime, ccdesk asks you to review again.
+- Settings and hooks are checked against Claude Code's settings schema. Other keys in the file stay as they are.
+- The old file is backed up to `~/.claude/backups/ccdesk/` first. Undo is one click, and **Recent changes** can restore any earlier edit.
+- A settings file that is a symlink, such as one in a dotfiles repository, is written through and stays a link.
+- A file with other hard links is not saved: replacing it would split it from its other names. Edit it in your editor.
+- ccdesk never writes `~/.claude.json`. User and local MCP server changes go through Claude Code's own `claude mcp` command, so they need `claude` on your PATH.
+
+Details: [Recent changes, backups and undo](https://ayagmar.github.io/ccdesk/recent-changes/)
+
+<br clear="right" />
+
+## Keyboard
+
+| Key | Action |
+| --- | --- |
+| `j` / `k` | Next / previous row |
+| `1` to `9` | Jump to a section |
+| `/` | Filter rows |
+| `Ctrl K` / `⌘ K` | Jump to any directory, file, setting, rule or memory |
+| `Esc` | Close details |
+
+More in [Reading the interface](https://ayagmar.github.io/ccdesk/interface/).
+
+## Options
+
+```
+npx ccdesk [options]
+
+  --port <n>            Port to listen on (default: a free port)
+  --no-open             Print the URL instead of opening a browser
+  --config-dir <path>   Claude folder to read, as CLAUDE_CONFIG_DIR sets it for Claude Code
+                        (wins over $CLAUDE_CONFIG_DIR)
+  -h, --help            Show this help
+```
+
+ccdesk reads `~/.claude` and `~/.claude.json`, or `$CLAUDE_CONFIG_DIR` when it is set, as Claude Code does. To look at another profile without exporting the variable, pass `--config-dir <path>`. Edits made in another editor or by Claude show up within a second. Requires Node.js 22.19 or newer. See [Platform notes](https://ayagmar.github.io/ccdesk/platforms/) for Windows, macOS and WSL.
+
+## Privacy and safety
+
+- The server listens on `127.0.0.1` only, and every API call needs a token generated for that run. Nothing leaves your machine.
+- Values under `env` and `headers`, and keys in an MCP server's `args` (after flags such as `--token` or `--api-key`, or starting like `sk-` or `ghp_`), are hidden everywhere in the UI, diffs included, and ccdesk refuses any edit that would change them.
+- ccdesk never reads `~/.claude/.credentials.json`.
+- From your transcripts, only counts and rule patterns (a command's program and subcommand, a fetch's domain) reach the page, never commands or file contents.
+- Backups are readable only by you on Linux and macOS.
+
+The full list is in [Safety and privacy](https://ayagmar.github.io/ccdesk/safety-and-privacy/).
+
+## Development
+
+```sh
+pnpm install
+pnpm dev        # API on 127.0.0.1:4319
+pnpm dev:ui     # UI with hot reload on localhost:4320
+pnpm check      # typecheck, lint, format, tests, build
+```
+
+Tests never touch your real `~/.claude`; each one builds a throwaway home directory. The settings schema, scopes and built-in tools are generated from [`@anthropic-ai/claude-agent-sdk`](https://www.npmjs.com/package/@anthropic-ai/claude-agent-sdk) and Claude Code's docs, and a daily workflow opens a pull request when they change. [Contributing](https://ayagmar.github.io/ccdesk/contributing/) covers the generators, the docs site and releases.
+
+## License
+
+MIT

package/dist/server/agent-edit.js

@@ -0,0 +1,77 @@
+import { join, resolve } from "node:path";
+import {} from "../shared/types.js";
+import {} from "./scan/env.js";
+import { gitRoot, revisionOf, shownText } from "./scan/files.js";
+import { scanDirectory } from "./scan/index.js";
+import { agentProblems } from "./scan/inventory.js";
+import { RefusedError, readIfExists, recordChange, removeExactly, serially, StaleError, writeAtomic, } from "./write.js";
+/** The file an edit changes: an agent the scan shows here, or a new one in your or the project's folder. */
+async function targetOf(env, edit) {
+    const dir = resolve(edit.dir);
+    if (edit.path !== undefined) {
+        const agent = (await scanDirectory(env, dir)).inventory.agents.find((a) => a.path === edit.path);
+        if (!agent)
+            throw new RefusedError("That agent is no longer here; review it again.");
+        if (agent.scope !== "user" && agent.scope !== "project")
+            throw new RefusedError(agent.scope === "plugin"
+                ? "This agent comes with its plugin; change it in the plugin."
+                : "Managed agents are set by your organisation.");
+        return agent.path;
+    }
+    if (!edit.create)
+        throw new RefusedError("An agent edit needs the agent or where a new one goes.");
+    const { scope } = edit.create;
+    // The folder gives the .md; a name typed with it would otherwise end in .md.md.
+    const file = edit.create.file.replace(/\.md$/i, "");
+    if (!/^[\w][\w.-]*$/.test(file))
+        throw new RefusedError("A file name has letters, digits, '.', '-' or '_', and no folders.");
+    const folder = scope === "user"
+        ? join(env.claudeDir, "agents")
+        : join((await gitRoot(dir)) ?? dir, ".claude", "agents");
+    return join(folder, `${file}.md`);
+}
+async function plan(env, edit) {
+    const path = await targetOf(env, edit);
+    const raw = await readIfExists(env, path);
+    if (!edit.path && raw !== null)
+        throw new RefusedError(`${path} already exists; open that agent to change it.`);
+    const before = shownText(raw);
+    // The page shows the file with env, header and URL values hidden, so a changed file written back
+    // from it would lose them; it can still be deleted, as a whole.
+    if (edit.text !== null && before !== raw)
+        throw new RefusedError(`${path} has env, header or URL values ccdesk does not show; edit it in your editor instead.`);
+    const errors = edit.text === null ? [] : agentProblems(edit.text);
+    return {
+        path,
+        raw,
+        preview: {
+            path,
+            before,
+            after: errors.length > 0 ? (before ?? "") : (shownText(edit.text) ?? ""),
+            revision: revisionOf(raw),
+            reformats: false,
+            errors,
+        },
+    };
+}
+export async function previewAgentEdit(env, edit) {
+    return (await plan(env, edit)).preview;
+}
+/** Writes or deletes an agent file, backed up first, only while it is as reviewed. */
+export function saveAgentEdit(env, edit, expectedRevision) {
+    return serially(async () => {
+        const { path, raw, preview } = await plan(env, edit);
+        if (preview.errors.length > 0)
+            throw new RefusedError(preview.errors.join(" "));
+        if (preview.revision !== expectedRevision)
+            throw new RefusedError("The agent changed since you reviewed this; review it again.");
+        const { text } = edit;
+        return recordChange(env, { kind: "agent", target: path, before: raw }, async () => {
+            if (text !== null)
+                await writeAtomic(env, path, text, expectedRevision);
+            else if (!(await removeExactly(path, expectedRevision)))
+                throw new StaleError(`${path} changed while ccdesk deleted it; nothing was deleted.`);
+            return { target: path, revision: revisionOf(text) };
+        });
+    });
+}

package/dist/server/backups.js

@@ -0,0 +1,303 @@
+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, revisionOf, shownText } from "./scan/files.js";
+import { hiddenValues, shown } from "./secrets.js";
+import { backupRoot, forgetChange, MANIFEST, RefusedError, readIfExists, recordChange, removeExactly, SHOWN_AFTER, SNAPSHOT, StaleError, serially, writeAtomic, } from "./write.js";
+const KINDS = new Set([
+    "settings",
+    "mcp",
+    "agent",
+    "memory-index",
+    "memory-delete",
+    "memory-restore",
+    "mcp-claude",
+]);
+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)) ||
+        (data.undoCommands !== undefined && !strings(data.undoCommands)))
+        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");
+}
+/** A `.md` file in your agents folder or a project's `.claude/agents`, or a subfolder of one. */
+function isAgentFile(env, path) {
+    if (!path.endsWith(".md"))
+        return false;
+    if (isWithin(join(env.claudeDir, "agents"), path))
+        return true;
+    const parts = path.split(/[/\\]/);
+    return parts.some((part, i) => part === ".claude" && parts[i + 1] === "agents" && i + 2 < parts.length);
+}
+/** 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 shown(JSON.parse(text));
+    }
+    catch {
+        return "(not valid JSON; open the file to see it)\n";
+    }
+}
+/** A backup's manifest and its folder, which must be inside the backup folder. */
+async function backupAt(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.");
+    return { manifest, dir };
+}
+const MADE_BY_CLAUDE = "Claude Code made this change through claude mcp, so ccdesk cannot undo it. Run the commands below to put it back.";
+/**
+ * What a change made through `claude mcp` did, as ccdesk recorded it: the servers before and
+ * after, values hidden, and the commands that put them back.
+ */
+async function claudeMcpPreview(id, manifest, dir) {
+    const read = async (name, revision) => {
+        const text = await readFile(join(dir, name), "utf8").catch(() => null);
+        if (text === null || revisionOf(text) !== revision)
+            throw new RefusedError("The record of this change is missing or was changed.");
+        return text;
+    };
+    return {
+        id,
+        kind: manifest.kind,
+        target: manifest.target,
+        before: await read(SNAPSHOT, manifest.before),
+        after: await read(SHOWN_AFTER, manifest.after),
+        revision: manifest.after,
+        blocked: MADE_BY_CLAUDE,
+        undoCommands: manifest.undoCommands ?? [],
+    };
+}
+async function planRestore(env, id) {
+    const { manifest, dir } = await backupAt(env, id);
+    if (manifest.kind === "mcp-claude")
+        throw new RefusedError(MADE_BY_CLAUDE);
+    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 === "mcp" && basename(target) !== ".mcp.json")
+        throw new RefusedError("This backup does not point at a .mcp.json.");
+    if (manifest.kind === "agent" && !isAgentFile(env, target))
+        throw new RefusedError("This backup does not point at a subagent 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" && manifest.kind !== "mcp" && manifest.kind !== "agent") {
+        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-index" &&
+            (!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,
+        linked: (await lstat(target).catch(() => null))?.isSymbolicLink() ?? false,
+    };
+    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);
+}
+/**
+ * A delete that stopped halfway, after Claude rewrote the memory: the memory was never removed, so
+ * only the MEMORY.md lines the delete took out come back, and the memory stays as it is now.
+ */
+function onlyIndexLines({ manifest, current, saved, index }) {
+    return (manifest.kind === "memory-delete" &&
+        manifest.after === "partial" &&
+        current !== null &&
+        current !== saved &&
+        (index?.missing.length ?? 0) > 0);
+}
+function blockedReason(plan) {
+    const { manifest, current, saved } = plan;
+    if (saved === null && manifest.kind === "memory-restore")
+        return "This put a deleted memory back. To undo it, delete the memory again.";
+    // Undoing a change that created its file removes the file, but only the one ccdesk wrote.
+    if (saved === null) {
+        if (manifest.after === "pending" || manifest.after === "partial")
+            return "This change stopped halfway, so ccdesk cannot tell what it wrote. Remove the file by hand if you need to.";
+        if (current === null)
+            return "The file ccdesk created is gone already.";
+        if (plan.linked || revisionOf(current) !== manifest.after)
+            return "The file changed after ccdesk created it, so ccdesk does not remove it. Change it in place instead.";
+        return undefined;
+    }
+    if (onlyIndexLines(plan))
+        return undefined;
+    // A file broken since the backup has no values ccdesk could keep; the backup is the way out of it,
+    // and the broken file is itself backed up before the restore replaces it.
+    const now = hiddenValues(current);
+    if ((manifest.kind === "settings" || manifest.kind === "mcp") &&
+        current !== null &&
+        now !== null &&
+        now !== hiddenValues(saved))
+        return "Hidden values in this file (env, headers, a URL's key or a key in args) 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 { manifest: recorded, dir } = await backupAt(env, id);
+    if (recorded.kind === "mcp-claude")
+        return claudeMcpPreview(id, recorded, dir);
+    const plan = await planRestore(env, id);
+    const { manifest, current, saved, index } = plan;
+    const show = manifest.kind === "settings" || manifest.kind === "mcp" ? shownSettings : shownText;
+    const before = show(current);
+    const after = (onlyIndexLines(plan) ? before : show(saved)) ?? "";
+    const blocked = blockedReason(plan);
+    return {
+        id,
+        kind: manifest.kind,
+        target: manifest.target,
+        before,
+        after,
+        revision: planRevision(plan),
+        ...(saved === null ? { removes: true } : {}),
+        ...(blocked ? { blocked } : {}),
+        ...(index && index.missing.length > 0
+            ? { indexLines: index.missing.map((line) => shownText(line) ?? line) }
+            : {}),
+    };
+}
+/**
+ * Puts a backed-up file back, or removes a file ccdesk created, if the file is still as it was
+ * when the restore was reviewed. A removed file is backed up first, so it can be put back too.
+ */
+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)
+            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 (saved === null) {
+            await recordChange(env, { kind: manifest.kind, target, before: current }, async () => {
+                if (!(await removeExactly(target, revisionOf(current))))
+                    throw new StaleError(`${target} changed while ccdesk was removing it; nothing was removed. Review it again.`);
+                return { revision: revisionOf(null) };
+            });
+            return { target };
+        }
+        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, with its record, so a refused restore leaves both as
+        // they were.
+        const created = current === null
+            ? await recordChange(env, { kind: "memory-restore", target, before: null }, async () => {
+                await writeAtomic(env, target, saved, revisionOf(null));
+                return { revision: revisionOf(saved) };
+            })
+            : 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))))
+                await forgetChange(env, created.id);
+            throw error;
+        }
+        return { target };
+    });
+}