Context Doctor

Context Doctor makes context engineering easier. Describe the agent behavior you want and what is happening instead; it maps the instructions, memory, skills, commands, settings, and hooks around the task, then identifies context that may be helping or interfering.

What it achieves

• Finds contradictory, stale, duplicated, or unexpectedly scoped context.
• Explains how each relevant artifact could affect the behavior you see.
• Distinguishes a discovered file from evidence that a harness actually loaded it.
• Suggests narrow isolation tests and minimal context changes instead of guesswork.
• Produces a reusable context map across Claude Code, Codex, OpenCode, Gemini CLI, and other Agent Skills-compatible harnesses.

The diagnosis is read-only. Project context is examined by default; user-level configuration and memory remain opt-in.

Principles

• Start from the requested behavior, not from a provider-specific checklist.
• Treat every discovered artifact as a candidate until load or scope is evidenced.
• Diagnose the current project by default.
• Read user-level configuration and memory only when explicitly requested.
• Never print hook commands, environment values, tokens, or unrelated memories.
• Diagnose first. The doctor does not modify context.

Requirements

• Node.js 18 or newer

The deterministic inventory command has no runtime dependencies.

Install

Claude Code

After this repository is published:

claude plugin marketplace add DheerG/context-doctor
claude plugin install context-doctor@context-doctor --scope user

Restart Claude Code, then invoke:

/context-doctor:diagnose-agent-context The agent keeps rewriting tests when I asked it to diagnose only.

For local development:

claude --plugin-dir ./plugins/context-doctor

Codex

After this repository is published:

codex plugin marketplace add DheerG/context-doctor

Install context-doctor from that marketplace in the Codex plugin UI, then invoke:

$context-doctor:diagnose-agent-context Find context that makes the agent over-format every response.

For local development, add the absolute path to this repository as a local marketplace.

OpenCode, Gemini CLI, and Agent Skills harnesses

Clone the repository, then install the entry points you need:

node plugins/context-doctor/scripts/install.mjs --harness opencode
node plugins/context-doctor/scripts/install.mjs --harness gemini
node plugins/context-doctor/scripts/install.mjs --harness agents

Use --harness all for all three. Existing targets are preserved unless --force is supplied.

Invoke /diagnose-agent-context <behavior and mismatch> in OpenCode or Gemini CLI. Agent Skills-compatible harnesses can invoke diagnose-agent-context by name.

Direct inventory command

Link the command during development:

npm link

Run it from the project being diagnosed:

context-doctor self-check
context-doctor inventory
context-doctor inventory --format json
context-doctor inventory --include-global

--include-global is an explicit privacy boundary. The command lists candidate paths and limited metadata; it does not emit artifact contents. The agent reads only evidence relevant to the behavior under diagnosis.

Use in a plan

The diagnosis is read-only, so it can run during planning:

Use diagnose-agent-context before proposing changes. Compare the behavior I want
with project context, and do not inspect user-level memory without asking.

If remediation is later approved, keep inventory, diagnosis, edits, and verification as separate plan steps.

Diagnosis model

Findings are classified as:

• direct conflict;
• likely interference;
• conditional or ambiguous;
• complementary.

Each finding should include the path and relevant lines, the affected behavior, a plausible mechanism, confidence, and a narrow confirmation test. “No likely interference found” is a valid result.

Development

npm test
npm run validate
npm run version:check

Releases

Every merge to main receives a SemVer bump, an immutable v<version> tag, and a GitHub Release.

• Apply the major label to a pull request for a major bump.
• Apply the minor label for a minor bump.
• With neither label, the workflow applies a patch bump.

Repository setup:

1. Create the major and minor pull-request labels.
2. Give GitHub Actions read/write repository permission.
3. Permit github-actions[bot] to push its version-only commit to main. If branch rules prevent that, add a write-capable DEPLOY_KEY repository secret.

The workflow keeps package.json, both plugin manifests, and both marketplace entries on the same version. Tags are never moved.

License

MIT