Metadata-Version: 2.4
Name: ctxpick
Version: 0.2.0
Summary: Pick which skills, plugins, and MCPs are active for your AI coding agent.
Author: Agent Context Doctor contributors
License: MIT
Requires-Python: >=3.11
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.7
Requires-Dist: typer>=0.12
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Requires-Dist: textual>=0.79; extra == 'dev'
Provides-Extra: tui
Requires-Dist: textual>=0.79; extra == 'tui'
Description-Content-Type: text/markdown

# 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:

```bash
python -m pip install -e .
```

Optional TUI:

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

## Commands

```bash
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:

```bash
cmdoc scan
claude-memory-doctor scan
```

## Agent skill

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

```text
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:

```text
docs/agent-skill-install.md
```

## What it scans

Global/user scope:

```text
~/.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:

```text
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:

```text
~/.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

```bash
acdoc scan --json
```

```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"
    }
  ]
}
```

```bash
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

```bash
acdoc lint
```

Potential findings:

```text
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
```

```bash
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:

```bash
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.

```bash
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.

```bash
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:

```bash
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:

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

Then run your coding agent with:

```text
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

```bash
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**
