agentleFS
knowledgeislandsknowledgeislands/mcp-housekeeping-claude/AGENTS.md

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.

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
  1. Very specific:

    Use Bun (>= 1.3) for install, development, and tests.

    line 5
  2. Very specific:

    Use snake_case <app>_<resource>_<action> tool names.

    line 11
  3. Very specific:

    Keep the tool catalogue in README and the practical instructions in docs/guides/, under the audience that needs them.

    line 17
  4. Very specific:

    Run bun run with no args for the full script list.

    line 29
  5. Distinctive:

    Every access level touches files anywhere under four configured roots.

    line 68

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
AGENTS.md

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 (NOT bun test — the latter invokes Bun's own runner instead of vitest).
  • Bun auto-loads .env.${NODE_ENV} from the CWD; Node needs the explicit process.loadEnvFile() call inside loadConfig() in src/config/index.ts. The try/catch swallows the TypeError Bun raises (no process.loadEnvFile), so the same code works under both.
  • NODE_ENV is set to development only by ki:server:mcp:dev and ki:server:mcp:inspect. Claude Desktop doesn't set it, so .env.* is ignored in production — MCP_HOUSEKEEPING_CLAUDE_PATH must come from the Claude Desktop config env block.

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 plain Config value. There is no module-level config singleton — nothing reads env at import time. Config carries housekeepingPath, 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 the AuditConfig slice, sets server.registerTool = makeAccessGatedRegister(server, config.accessLevel, audit), and threads config into each register<group>Tools(server, config). Keeps the startup logging.
  • src/tools/ — MCP tool definitions only. Thin: validate args, call a main/ function (passing the relevant cfg slice as the first arg), map result/throw to an MCP envelope via jsonResult / 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/. Every main entry point takes the config it needs as its first argument — a root path (projectsList(claudeRoot), storageSummary(root, args)) or housekeepingPath (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 whole Config, so they stay MCP-agnostic. utils.ts holds the generic FS/format helpers and discoverWorkspaces(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 → read
  • destructiveHint: true → destructive
  • explicit readOnlyHint: false AND destructiveHint: 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.

  1. Path containment at every path.join(<root>, <user-input>) site. Wrap with resolveWithinRoot() (lexical guard) AND assertRealPathWithinRoot() (symlink-aware) from src/utils/utils.ts. Both apply to args.workspace, args.project, args.session, memory args.name, and any new identifier that becomes a path segment.
  2. 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), memory name (must end .md). Bare z.string().min(1) is not acceptable for path-segment inputs.
  3. Destructive tools require dry_run default true. Every tool registered at the destructive level (i.e. deleting or renaming files) must expose dry_run: boolean, default to preview, and only mutate when explicitly disabled. The DESTRUCTIVE_ONESHOT annotation is required on tools whose effect depends on current FS contents (prune, relocate, delete).
  4. Batch deletes are scoped by filename pattern, never wildcard. Report cleanup matches cowork-audit-*.md; session pruning matches *.jsonl (Claude Code), local_*.json plus matching sidecars (Claude Desktop), or *.json[l] (VSCode). New batch-delete tools must declare and test their pattern — never fs.rm arbitrary entries the user named.
  5. Access-level gate is the registration boundary, keyed off annotations. See Access-level gate above.
  6. No shell-string interpolation. du is invoked via spawn('du', ['-sk', target]) — argv form. New tools that shell out must use execFile or spawn with an argv array.
  7. Zod schemas are .strict(). Already true everywhere; new schemas must continue this.
  8. Tests MUST NOT touch the real root paths. Config.claudeCodeRootPath, Config.claudeDesktopRootPath, and Config.vscodeWorkspaceStorageRootPath resolve to live user directories (~/.claude/, the Cowork sessions dir, VSCode workspaceStorage). Test files MUST NOT call loadConfig() and feed its derived roots into a main/ 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. Because main/ functions take their root (or housekeepingPath) 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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.