mcp-housekeeping-claude
AGENTS.md0 starsChanged 3 days agoMITView on GitHub
Use Bun (>= 1.3) for install, development, and tests; use bun run test, never bun test. The published dist/ MCP runs under Node (>= 22). Keep NODE_ENV=development confined to dev and inspector commands; production configuration comes from the host environment. Keep configuration injectable: no module-level environment reads or config singleton. The server loads config once and passes it to registration functions. Tool modules validate and adapt MCP envelopes only; implementation belongs in src/main/ and receives the smallest config primitive it…
- Reads credentials
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 32,671 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repositoryOne other file it gives its agents.
- CLAUDE.mdCLAUDE.md
The file
We split this AGENTS.md into the rules it gives an agent
5 rules. About 0 are common, 1 is distinctive, and 4 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 5
Use Bun (>= 1.3) for install, development, and tests.
- Very specific: line 11
Use snake_case <app>_<resource>_<action> tool names.
- Very specific: line 17
Keep the tool catalogue in README and the practical instructions in docs/guides/, under the audience that needs them.
- Very specific: line 29
Run bun run with no args for the full script list.
- Distinctive: line 68
Every access level touches files anywhere under four configured roots.
≈ “Common” is an estimate: at least 1 in 5 of the 41,581 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
AGENTS.md
Runtime
Use Bun (>= 1.3) for install, development, and tests; use bun run test, never bun test. The published dist/ MCP runs under Node (>= 22). Keep NODE_ENV=development confined to dev and inspector commands; production configuration comes from the host environment.
MCP architecture
Keep configuration injectable: no module-level environment reads or config singleton. The server loads config once and passes it to registration functions. Tool modules validate and adapt MCP envelopes only; implementation belongs in src/main/ and receives the smallest config primitive it needs as its first argument. Keep reusable, config-agnostic helpers in src/utils/.
Use snake_case <app>_<resource>_<action> tool names. Register through the annotation-driven access gate; every tool must use an explicit annotation preset. The access level controls visibility and never substitutes for effect-level safeguards.
Safety and tests
Constrain every filesystem path to its configured root, including symlink-aware containment. Validate user-controlled identifiers with tight schemas. Invoke subprocesses through argv APIs, never shell strings. Mutating or non-idempotent tools require an explicit, default-true dry_run where applicable. Keep Zod schemas strict. Tests use isolated fixtures and never exercise real user roots.
Keep the tool catalogue in README and the practical instructions in docs/guides/, under the audience that needs them; keep shared repository guidance here and only Claude-specific deltas in CLAUDE.md.
Repository-specific implementation guidance follows. User-facing setup and tool documentation live in README.md and docs/guides/.
Bun vs Node
This project uses Bun (≥ 1.3) for install and dev scripts, but the compiled dist/ runs under Node (≥ 22) — that's what Claude Desktop launches.
bun run test(NOTbun test— the latter invokes Bun's own runner instead of vitest).- Bun auto-loads
.env.${NODE_ENV}from the CWD; Node needs the explicitprocess.loadEnvFile()call insideloadConfig()in src/config/index.ts. The try/catch swallows theTypeErrorBun raises (noprocess.loadEnvFile), so the same code works under both. NODE_ENVis set todevelopmentonly byki:server:mcp:devandki:server:mcp:inspect. Claude Desktop doesn't set it, so.env.*is ignored in production —MCP_HOUSEKEEPING_CLAUDE_PATHmust come from the Claude Desktop configenvblock.
Run bun run with no args for the full script list.
Architecture Invariants
Project layout & config injection (the workspace MCP shape)
This is the canonical layout we roll out across the MCPs:
- src/config/index.ts —
loadConfig(env?) → Config. Reads env (optionally hydrated from.env.${NODE_ENV}) into a plainConfigvalue. There is no module-level config singleton — nothing reads env at import time.ConfigcarrieshousekeepingPath,accessLevel, the three derived target roots (claudeCodeRootPath,claudeDesktopRootPath,vscodeWorkspaceStorageRootPath), and the audit-log knobs (auditLogMode/auditLogPath/auditLogMaxBytes/auditLogKeep). Exported types/constants (AccessLevel,ACCESS_LEVELS,ACCESS_LEVEL_RANK,AuditLogMode) live here too. - src/mcp-server/index.ts — the stdio MCP wrapper. Calls
loadConfig()once, builds theAuditConfigslice, setsserver.registerTool = makeAccessGatedRegister(server, config.accessLevel, audit), and threadsconfiginto eachregister<group>Tools(server, config). Keeps the startup logging. - src/tools/ — MCP tool definitions only. Thin: validate args, call a
main/function (passing the relevantcfgslice as the first arg), map result/throw to an MCP envelope viajsonResult/errorResult. Excluded from coverage. - src/main/ — the real implementation, usable outside the MCP server (e.g. from a script). Grouped by concern:
main/claude-code/,main/claude-desktop/,main/vscode/. Everymainentry point takes the config it needs as its first argument — a root path (projectsList(claudeRoot),storageSummary(root, args)) orhousekeepingPath(reportWrite(housekeepingPath, args)). No hidden state. Tests are co-located. - src/utils/ — cross-MCP reusable helpers; keep in sync with sibling repos. These take the specific config primitive they need (
makeAccessGatedRegister(server, accessLevel, audit),withAuditLog(audit, name, level, cb),resolveWithinRoot(root, …)), not the wholeConfig, so they stay MCP-agnostic.utils.tsholds the generic FS/format helpers anddiscoverWorkspaces(root).
To use the code from a script: const cfg = loadConfig(); await projectsList(cfg.claudeCodeRootPath).
This dependency direction is enforced, not just described: .dependency-cruiser.ts states each boundary as a named rule and src/boundaries.test.ts cruises the source graph and proves every rule still rejects a deliberate crossing. Tool modules may reach only the main/ modules their surface index.ts re-exports, config/index.ts, and the annotations.ts and utils.ts helpers. The checker runs from its own install root, tooling/depcruise, because dependency-cruiser needs a TypeScript below 7.
Naming convention
Tool names follow <app>_<resource>_<action> (snake_case). <app> ∈ {claude_desktop, claude_code, vscode}. <resource> is plural for collection ops, singular for single-item ops. <action> is a verb or view (list, read, write, delete, prune, relocate, summary, status, health, inventory, clear, obsolete).
Access-level gate — driven by annotations, not names
src/utils/access-level.ts makeAccessGatedRegister() decides at startup whether to register each tool, based on config.annotations:
readOnlyHint: true→readdestructiveHint: true→destructive- explicit
readOnlyHint: falseANDdestructiveHint: false→write(non-destructive mutation; reserved — no such tools today) - anything else (unannotated / partially annotated) →
destructive(fail-safe)
A tool registers when its derived level is at or below MCP_HOUSEKEEPING_CLAUDE_ACCESS_LEVEL (default: read). Levels nest: read registers only readers; write adds non-destructive mutations; destructive adds prune/relocate/delete. New tools MUST set annotations to one of the presets in src/utils/annotations.ts: READ_ONLY, DESTRUCTIVE, or DESTRUCTIVE_ONESHOT. Do not bypass the proxy. The gate controls visibility; the dry_run: true default on destructive tools controls effect — both layers are required.
Workspace discovery (Cowork only)
CLAUDE_DESKTOP_ROOT_PATH is walked at every tool invocation. A directory is a workspace if it contains any of .claude.json, artifacts.json, spaces.json, cowork_settings.json, or local_*.json. If the root itself has those marker files, it's treated as a single workspace with id . (back-compat with hard-coded inner-UUID configs). The other two roots (Claude Code, VSCode) discover their children differently and never aggregate.
Security Requirements
Every access level touches files anywhere under four configured roots. New tools and changes to existing tools MUST preserve every invariant below.
- Path containment at every
path.join(<root>, <user-input>)site. Wrap withresolveWithinRoot()(lexical guard) ANDassertRealPathWithinRoot()(symlink-aware) from src/utils/utils.ts. Both apply toargs.workspace,args.project,args.session, memoryargs.name, and any new identifier that becomes a path segment. - Tighten input schemas, not just call sites. Identifier inputs that become path segments must have a regex constraint excluding
/,\, and... Existing patterns:workspaceArg(hex),projectArg(alphanumeric/._-),sessionArg(alphanumeric/._-+.json[l]suffix), memoryname(must end.md). Barez.string().min(1)is not acceptable for path-segment inputs. - Destructive tools require
dry_rundefaulttrue. Every tool registered at thedestructivelevel (i.e. deleting or renaming files) must exposedry_run: boolean, default to preview, and only mutate when explicitly disabled. TheDESTRUCTIVE_ONESHOTannotation is required on tools whose effect depends on current FS contents (prune, relocate, delete). - Batch deletes are scoped by filename pattern, never wildcard. Report cleanup matches
cowork-audit-*.md; session pruning matches*.jsonl(Claude Code),local_*.jsonplus matching sidecars (Claude Desktop), or*.json[l](VSCode). New batch-delete tools must declare and test their pattern — neverfs.rmarbitrary entries the user named. - Access-level gate is the registration boundary, keyed off annotations. See Access-level gate above.
- No shell-string interpolation.
duis invoked viaspawn('du', ['-sk', target])— argv form. New tools that shell out must useexecFileorspawnwith an argv array. - Zod schemas are
.strict(). Already true everywhere; new schemas must continue this. - Tests MUST NOT touch the real root paths.
Config.claudeCodeRootPath,Config.claudeDesktopRootPath, andConfig.vscodeWorkspaceStorageRootPathresolve to live user directories (~/.claude/, the Cowork sessions dir, VSCodeworkspaceStorage). Test files MUST NOT callloadConfig()and feed its derived roots into amain/function. Instead, define a per-suite tmpdir, e.g.const CLAUDE_CODE_ROOT = path.join(os.tmpdir(), 'mcp-housekeeping-<group>-<file>-tests'), and pass that as the first arg to the function under test. Becausemain/functions take their root (orhousekeepingPath) as an injected first argument, this is the natural calling convention — there is no env to mutate. A regression here destroyed real~/.claude/projects/history once — don't do it again.
Traversal-rejection tests live in src/main/vscode/audit.test.ts. Parallel coverage for claudeCode.sessionRead / relocateProject is a follow-up.
Tool registration call sites
Each <app> group registers its tools in src/tools/<app>/index.ts (thin wiring) and implements them in src/main/<app>/. To survey the surface, grep "register(" src/tools/*/index.ts. README's Available Tools tabulates them with purposes.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

