ctxpick 0.2.0

Pick which skills, plugins, and MCPs are active for your AI coding agent.

Agent Context Doctor

Agent Context Doctor is a small CLI/TUI/web tool for finding, explaining, and linting the context layer used by coding agents.

It answers:

• What agent context and memory files exist?
• What is global, project-scoped, or local/private?
• Which agents, skills, commands, rules, settings, and MCP configs are present?
• What likely applies when an agent is launched from a specific path?
• Which files are duplicated, too vague, too large, unsafe, or scoped incorrectly?
• What JSON should be handed to Claude/Codex for semantic review and reorganization suggestions?

Install

From this repository:

python -m pip install -e .

Optional TUI:

python -m pip install -e '.[tui]'

Commands

acdoc
acdoc scan
acdoc lint
acdoc tree --json
acdoc explain ./path/to/file.py
acdoc review-pack . --out agent-context-audit.json
acdoc prompt
acdoc tui
acdoc web
acdoc mcp
acdoc mcp defaults
acdoc mcp ls
acdoc mcp apply

Running acdoc or cmdoc with no subcommand opens the main control center. It shows the current project, context counts, lint status, MCP state, and actions for browsing/editing context, project/global configuration, MCP management, tree view, lint, and effective-context explanation.

The package also installs compatibility aliases:

cmdoc scan
claude-memory-doctor scan

Agent skill

This repo includes a portable skill for Claude/Codex agents:

skills/agent-context-doctor/

The skill tells agents to use acdoc tree --json, acdoc lint --json, acdoc explain --json, and the web UI before manually digging through memory, skills, settings, hooks, and MCP files.

Local install and move notes are in:

docs/agent-skill-install.md

What it scans

Global/user scope:

~/.claude/CLAUDE.md
~/.claude/settings.json
~/.claude/settings.local.json
~/.claude/memory/*.md
~/.claude/hooks/*
~/.claude/agents/*.md
~/.claude/skills/*/SKILL.md
~/.claude/skills/*/references/*
~/.claude/commands/*.md
~/.claude/rules/*.md

Project scope:

CLAUDE.md
CLAUDE.local.md
.claude/CLAUDE.md
.claude/settings.json
.claude/settings.local.json
.claude/agents/*.md
.claude/skills/*/SKILL.md
.claude/skills/*/references/*
.claude/commands/*.md
.claude/rules/*.md
.claude/hooks/*
.mcp.json

Claude Code project memory:

~/.claude/projects/<current-project-path>/memory/*.md
~/.claude/projects/<parent-project-path>/memory/*.md

Only memory/*.md files are scanned under ~/.claude/projects; session transcripts and cache files are intentionally skipped.

It intentionally skips common heavy directories such as .git, node_modules, .venv, dist, build, target, .next, and caches.

Example

acdoc scan --json

{
  "root": "/home/user/projects/example-agent-project",
  "files": [
    {
      "kind": "claude_memory",
      "scope": "project",
      "name": "CLAUDE.md",
      "path": "/home/user/projects/example-agent-project/CLAUDE.md"
    }
  ]
}

acdoc tree --json

Emits the same inventory as a source/type/path tree for agents:

• source: Claude global, Claude project, Agent global, etc.
• section: loaded memory, related memory, available skills and references, tools/MCP, hooks, reusable agents/commands/rules
• folder path: compact path hierarchy, using ~ for home-relative global files
• file leaf: full file metadata plus lint finding counts

acdoc lint

Potential findings:

warning  long-memory-file               ./CLAUDE.md
warning  local-file-not-gitignored      ./.claude/settings.local.json
warning  duplicate-agent                ./.claude/agents/code-reviewer.md
warning  forced-agent-delegation        ~/.claude/CLAUDE.md
warning  hook-delegates-retrieval-to-agent ~/.claude/hooks/knowledge-recall.sh
warning  weak-tool-use-sentinel         ~/.claude/settings.json
info     duplicate-memory-topic         ~/.claude/memory/feedback_x.md
info     procedure-in-memory            ./CLAUDE.md

acdoc explain ./news/scrapers/foo.py

Shows the approximate effective context for that path:

• global memory
• project memory hierarchy
• global memory notes and matching ~/.claude/projects/.../memory/*.md notes
• local memory
• settings
• agents
• skills
• skill reference files
• commands
• rules
• MCP config

For debugging surprising Claude behavior from a project root, start with:

acdoc explain . --json

The loaded_at_start section is the estimated startup memory stack. The lazy_or_related section includes global memory notes plus the current project's Claude Code memory notes, which may be pulled in by recall workflows or used as project-corresponding context.

acdoc web .

Opens a local browser UI at http://127.0.0.1:8765/ for browsing the same scan results, lint findings, and file text. It defaults to an estimated context stack grouped by role: loaded at startup, local/private, related memory, available skills, tools/MCP, hooks, and reusable agents/commands/rules.

The web UI can edit and save files found by the current scan. Use Edit for the selected file or Edit visible to show the filtered files one under the other as editable textareas. Save operations are allowlisted to scanned files, and truncated large-file previews are read-only.

The web UI can also write project-local disable controls to .claude/settings.local.json via Disable here / Enable here:

• skills and commands: skillOverrides
• CLAUDE.md and rules files: claudeMdExcludes
• project .mcp.json servers: disabledMcpjsonServers
• project auto memory: autoMemoryEnabled
• hooks: disableAllHooks
• agents: permissions.deny

Some Claude Code controls are broad. Disabling a hook file disables all hooks for the project, and disabling an auto-memory note disables auto memory for the project rather than one topic file.

acdoc configure .

Runs a quick terminal selector for project-local defaults. In an interactive terminal it opens a Rich checklist; use --ui textual for a fuller Textual screen with directory-grouped trees, or --ui prompt for the plain numbered prompt. It writes .claude/settings.local.json and, for named user/connector MCP servers, the current project's disabledMcpServers entry in ~/.claude.json. It can keep only selected items enabled:

In the Textual UI, folder rows are tri-state controls. Space toggles the current leaf or the whole highlighted folder; a enables the active section, n disables it, r resets it to the starting state, and w or Ctrl+S finishes. Changed rows and folders are marked in-line.

• standalone skills: skillOverrides
• plugins: enabledPlugins
• project .mcp.json servers: enableAllProjectMcpServers, enabledMcpjsonServers, and disabledMcpjsonServers
• named user, connector, and local MCP servers: ~/.claude.json project disabledMcpServers

Use --disabled-skill-state user-invocable-only if unselected skills should be hidden from automatic use but still callable explicitly.

Use --scope user to set global default skill/plugin visibility in ~/.claude/settings.json. The same command also lists named MCP servers and can save an Agent Context Doctor MCP default allowlist in ~/.claude/agent-context-doctor/mcp-defaults.json. Claude Code does not read that defaults file directly; Agent Context Doctor uses it to seed per-project disabledMcpServers the next time you run project-scope configure.

For MCP-only work, use the shorter commands:

acdoc mcp              # open the MCP control center
acdoc mcp project      # edit MCPs for this project directly
acdoc mcp defaults     # edit global Agent Context Doctor MCP defaults
acdoc mcp ls           # show default and project MCP state
acdoc mcp apply        # apply saved defaults to this project

acdoc mcp shows the available MCP actions and current state in one screen, so you do not have to remember the subcommands. project and defaults default to the Textual tree UI. ls and apply are non-interactive status/apply commands; add --no-live to skip calling claude mcp list.

Lint rules

Static checks include:

• duplicate agent names
• duplicate skill names
• duplicate command names
• missing or malformed YAML frontmatter
• missing/vague descriptions
• long memory files
• large skill files
• invalid JSON in settings/MCP files
• local files not gitignored
• project-specific content in global memory
• absolute user paths in project-scoped files
• likely secrets/tokens
• procedural checklist content inside memory files
• multiple package managers mentioned in one memory file

The linter is intentionally deterministic. Claude/Codex should be used for semantic review after this tool creates a bounded review pack.

LLM review workflow

Generate an audit pack:

acdoc review-pack . --out agent-context-audit.json
acdoc prompt --out review-prompt.md

Then run your coding agent with:

Review @agent-context-audit.json using @review-prompt.md.
Recommend organization changes and propose diffs only.

Recommended review boundaries:

• Do not let the LLM discover files itself.
• Do not let the LLM directly edit memory files at first.
• Give it the generated JSON inventory and findings.
• Ask for a patch plan and exact diffs.
• Apply changes manually or in small approved steps.

Development

python -m pip install -e '.[dev]'
pytest
ruff check .

Current limitations

• Effective context is an approximation. It currently models common Claude Code memory stacking, but it does not introspect a live agent session.
• .gitignore matching is intentionally simple and only handles common cases.
• The TUI is basic in v0.1.
• The web UI only edits files included in the current scan.
• The tool is Claude-first. Codex/Gemini/Windsurf adapters can be added later.

Roadmap

v0.1

• deterministic scanner
• deterministic linter
• effective context explanation
• JSON review pack
• basic TUI
• basic local web UI

v0.2

• richer TUI with file preview and filtering
• better gitignore matching
• more conflict rules
• optional live Claude hook log ingestion

v0.3

• review-plan format
• safe patch preview/apply
• support for Codex/Gemini/Cursor/Windsurf equivalents

Naming

Product name: Agent Context Doctor

Primary CLI name: acdoc

Compatibility aliases: cmdoc, claude-memory-doctor