Skip to content

compatibility.md

Latest commit

 

History

History
109 lines (100 loc) · 6.63 KB

compatibility.md

File metadata and controls

109 lines (100 loc) · 6.63 KB
Raw

Claude Code compatibility

ccdiet models configuration as Claude Code loads it, rather than treating every file found on disk as startup cost. This page records the supported behavior so upstream changes can become small, reviewable regression cases.

Last checked: 2026-08-07 with Claude Code 2.1.220 and the current official documentation.

Covered now

  • CLAUDE_CONFIG_DIR relocates settings, plugins, transcripts, memory, and the active .claude.json state file. An explicit ccdiet --home wins so fixture and alternate-home audits remain deterministic.
  • Project settings, local settings, MCP approval state, and project plugins are resolved from the repository root. The legacy start-directory local settings file remains readable when both locations exist, with the repository-root value taking precedence.
  • Project skills are discovered from the launch directory through every parent directory up to the repository root.
  • Personal skills override same-name project skills, and effective skills override legacy commands with the same invocation. Hidden, name-only, and disabled listings honor disable-model-invocation, skillOverrides, when_to_use, and the per-description character cap. Plugin skills remain outside skillOverrides, as Claude Code documents. A fixed SLASH_COMMAND_TOOL_CHAR_BUDGET caps aggregate startup descriptions; every name is retained and descriptions are allocated as whole entries. Legacy commands share the same budget. Model-context and frequency-based allocation remains explicitly estimated.
  • Personal and project skill-directory symlinks are followed with bounded reads and canonical-target de-duplication. Direct entry-file symlinks are rejected so project-controlled paths cannot expose unrelated local files.
  • Skills and CLAUDE.md files below the launch directory are marked conditional. They remain visible in JSON inventory but do not contribute to startup cost or dead-weight findings.
  • User and project .claude/rules/**/*.md files are discovered recursively. Rules without paths are startup instructions; path-scoped and nested rules are conditional.
  • Instruction imports resolve relative to the containing file and support absolute and ~/ paths, recursive imports up to five hops, canonical-path de-duplication, and Claude Code's text-extension and 4 MiB file limits. Import-looking text inside code spans, fenced code blocks, and HTML comments is ignored. External project imports load only when the active .claude.json approval is true; user imports remain trusted.
  • claudeMdExcludes arrays merge across the supported user, project, and local settings layers. Wildcard, globstar, bracket, and brace patterns are matched against normalized absolute paths before direct or imported instructions are counted.
  • Skill name, description, and when_to_use support quoted YAML values, inline comments, and literal/folded block scalars. A missing description falls back to the first body paragraph. Personal/project command names still come from their directory, while plugin skills can use frontmatter name for their command.
  • Effective plugins use only the selected installation. Manifest skills paths add to the default directory, while declared commands and agents paths replace their defaults; root SKILL.md and bounded custom files are supported without recursively scanning examples or tests. Default component directories and file-based MCP configuration must resolve inside the plugin root and are bounded before parsing. Project/local plugin installation paths are canonicalized before applicability checks.
  • Transcript JSONL is split with a two-million-byte line buffer, parsed as JSON, and filtered only by valid top-level event timestamps. Timestamp-less summary metadata is ignored; malformed, truncated, oversized, or resource-limited evidence disables cleanup findings. File, directory, discovered-byte, and actual-read budgets bound broad or growing history trees. A recent, well-formed assistant payload is required before a transcript counts as a session.
  • Project usage is retained both by Claude project slug and by absolute event working directory. Cleanup evidence uses canonical absolute cwd identity, because Claude's slash-to-dash project slug is lossy. Signals from legacy events without cwd can conservatively veto an unused finding but cannot open the cleanup gate. Each component is checked against its owning directory, so repository-root components see sibling-package use while package-local components stay isolated. Multi-cwd transcripts de-duplicate session, file, byte, and hook metrics by transcript identity. Unresolvable historical cwd paths remain unscoped used-veto evidence and never open the cleanup gate.
  • Raw MCP tool-use names are retained and matched against configured server invocation prefixes, including when an MCP tool name contains consecutive underscores.
  • MEMORY.md charges only the loadable first 200 lines or 25,000 bytes, whichever comes first. Frontmatter and block-level HTML comments are stripped before measuring, and disabled auto memory contributes zero startup tokens.

Still intentionally incomplete

  • custom autoMemoryDirectory and its project-trust gate
  • rules-directory symlink discovery/de-duplication
  • managed settings and policy-delivered instructions
  • additional directories and command-line setting-source flags
  • CLAUDE_CODE_PLUGIN_CACHE_DIR
  • main-checkout settings resolution from linked git worktrees
  • exact model-context global skill-listing budget and per-skill allocation after Claude Code ranks descriptions by observed invocation frequency

Until these are covered, ccdiet uses review/disable language and withholds dead-weight advice whenever transcript evidence is missing or incomplete.

Primary references