ccdesk 0.1.0 → 0.2.1

package/CHANGELOG.md

@@ -1,5 +1,91 @@
 # Changelog
 
+## [0.2.1](https://github.com/ayagmar/ccdesk/compare/v0.2.0...v0.2.1) (2026-10-12)
+
+### Features
+
+* **ui:** add a text size control and raise the default sizes ([1a9fe82](https://github.com/ayagmar/ccdesk/commit/1a9fe82b35cc4743936b7bf3c7a6d4244c86779a)), references [#root](https://github.com/ayagmar/ccdesk/issues/root)
+* **ui:** open the docs from the ccdesk logo ([834986a](https://github.com/ayagmar/ccdesk/commit/834986a40df7801e6b4cf12588fd69f65411458a))
+
+### Bug Fixes
+
+* **ui:** keep the section links on one row with the larger text ([f349f19](https://github.com/ayagmar/ccdesk/commit/f349f19c5e81ba3c498ff9f0751f4e3d5d99ade1))
+
+## [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

package/README.md

@@ -7,108 +7,125 @@
 
 [![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)
+[![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 that shapes Claude Code on your machine: instruction files, settings, hooks, MCP servers, subagents, skills, plugins and auto memory.
+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
 ```
 
-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`.
+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`–`9` | Jump to a section |
+| `1` to `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 |
+| `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
-  -h, --help   Show this help
+  --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`, 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.
+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. 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 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 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.
+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 127.0.0.1:4320
+pnpm dev:ui     # UI with hot reload on localhost: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.
+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
 

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) };
+        });
+    });
+}