my-claude — document your setup

Caution

A local-config dump stops being enough once the setup grows. Plugins, hooks, custom agents, alternative providers, project rules — a flat snapshot of settings.json and a couple of CLAUDE.md files does not explain how any of it fits together, and there is nothing to compare against next month.

Tip

/brewdoc:my-claude goes further. Internal mode maps everything in ~/.claude and your project’s .claude, then runs an independent Explore agent to validate every file path and count before writing. External mode synthesizes hook/context/agent architecture from official Anthropic docs, GitHub releases, and community forums. Research mode launches parallel agents across multiple live sources for any Claude Code query — with per-fact source citations and a reliability table.

Quick reference

FieldValue
Command/brewdoc:my-claude
Arguments[ext [context]] | [r <query>] — no args = internal installation docs
Modelopus
Invocationuser-only (disable-model-invocation: true)
Contextmain conversation
ToolsRead, Write, Edit, Glob, Grep, Bash, Agent, Task, WebFetch, WebSearch, AskUserQuestion

When to use

  • New team member onboarding — generate a complete map of your Claude Code setup as a shareable doc
  • Plugin audit before a release — snapshot your current skills, agents, hooks, and rules
  • Architecture research — pull official Anthropic docs on hooks, context injection, agent schema into one place
  • Custom investigation — research any Claude Code topic across multiple live sources with citations
  • Version tracking — INDEX entries persist across runs; compare docs over time

Examples

# Internal mode — maps your full &#126;/.claude + project .claude
/brewdoc:my-claude

# External mode — official architecture docs (hooks, context, agents)
/brewdoc:my-claude ext

# External mode, context-schema sub-mode — focuses on additionalContext / updatedInput
/brewdoc:my-claude ext context

# Research mode — any Claude Code query, multi-source with citations
/brewdoc:my-claude r plugin hooks additionalContext regression

vs built-in /team-onboarding

Built-in /team-onboarding (Claude Code 2.1.101+) is enough for a quick teammate handoff doc from local config. Use /brewdoc:my-claude instead when the job needs web research, EXTERNAL architecture synthesis, RESEARCH mode, or the persistent .claude/brewdoc/INDEX.jsonl with citations.

Modes

ArgumentModeWhat it does
(none)INTERNALAnalyzes &#126;/.claude + project .claude — rules, agents, skills, memories
ext or externalEXTERNAL (default)Official docs + local hook analysis + recent releases
ext contextEXTERNAL (context-schema)Focuses on context injection schema: additionalContext, updatedInput
r <query> or research <query>RESEARCHCustom query across GitHub, Reddit, forums, marketplaces

Flow

  1. Detect mode

    Reads $ARGUMENTS and selects INTERNAL, EXTERNAL, or RESEARCH. Loads the corresponding reference file from references/.

  2. Parallel discovery

    INTERNAL: spawns 3 parallel Explore agents — (1) global ~/.claude config, (2) project .claude config, (3) memory files. EXTERNAL/RESEARCH: spawns general-purpose agents per source group (official docs, GitHub, forums).

  3. Aggregate findings

    Merges agent outputs into a structured Markdown document. RESEARCH mode tracks source URL per fact for the citations table.

  4. Validation pass

    Spawns an independent agent to validate facts — file paths exist, counts match, no invented file names. INTERNAL uses Explore, since the check is read-only path existence. EXTERNAL and RESEARCH use general-purpose, which has the WebFetch / WebSearch access needed to re-check sources. Fixes are applied before the final doc is written.

  5. Write output

    Writes to .claude/brewdoc/my-claude/YYYYMMDD_my-claude-{mode}.md (project-relative — ~/.claude/* is protected and blocked in headless claude -p sessions, even under bypassPermissions). Creates the directory if needed with mkdir -p.

  6. INDEX entry

    Appends a record to .claude/brewdoc/INDEX.jsonl with timestamp, mode, path, title, and version. If an entry for this mode already exists, asks via AskUserQuestion whether to update (bump version) or create a new entry alongside the existing one.

Delegation — how every spawn is briefed

The rule applies to every Explore and general-purpose spawn in all three modes: a big task handed to one agent = an agent gone for an hour. You cannot observe it, cannot correct it, and it usually drifts off-target.

One subagent = ONE bounded unit — one source group, about 5 files and 10 steps at most. Anything bigger is split into N tasks and all of them are spawned in a single message.

Every spawn prompt carries six fields:

FieldContent
GOALthe overall task and why it exists — the point beyond the file edit
ROLEwhat this agent owns; what it must NOT touch
SCOPEexact paths and commands in bounds + explicit out-of-bounds
CONTEXTwhat is already done, by whom, what runs in parallel — trimmed to what this agent needs
CONSUMERwho or what uses the result next, and the shape it must fit
DONEacceptance criteria + the exact report shape expected back

A bare one-line task is never enough. INTERNAL mode uses this shape for its three Explore groups; EXTERNAL and RESEARCH use it per source group.

Internals — output paths, INDEX schema, document structures

Output directory: .claude/brewdoc/my-claude/ (project-relative) — the only supported target. &#126;/.claude/* is blocked by Claude Code’s protected-path policy in headless sessions, even under bypassPermissions. Earlier versions also offered a plugin-data path; nothing has set that variable since v4.0.0, so a run taking that branch wrote into a literal directory named after the unexpanded variable. That branch is gone.

Every generated doc opens with provenance frontmatter, before the # heading, in all three modes:

---
doc_type: user
version: "{PLUGIN_VERSION}"
generated_by: "brewdoc:my-claude"
last_updated: "{LAST_UPDATED}"
---

{PLUGIN_VERSION} is read from the brewdoc plugin’s own plugin.json by self-location, never hardcoded; {LAST_UPDATED} is date +%F. Re-generating an existing doc refreshes all three quoted values and leaves a hand-edited doc_type (llm / skip) as the user set it.

INTERNAL sources analyzed:

  • &#126;/.claude/CLAUDE.md — global instructions
  • &#126;/.claude/rules/*.md — global rules
  • &#126;/.claude/agents/*.md — global agents
  • &#126;/.claude/skills/ — global skills
  • Project CLAUDE.md and .claude/rules/*.md
  • &#126;/.claude/projects/**/memory/MEMORY.md — memory files

INDEX format:

{"ts":"2026-02-28T10:00:00","mode":"internal","path":".claude/brewdoc/my-claude/20260228_my-claude-internal.md","title":"Internal Claude Setup Overview","version":"1.0"}

Legacy migration: if &#126;/.claude/brewdoc/INDEX.jsonl exists and the project INDEX is empty, entries are merged once (read-only). The legacy file is never written to. A notice is printed: ℹ️ Migrated {N} entries from legacy &#126;/.claude/brewdoc/INDEX.jsonl.

INTERNAL output structure:

# Claude Code Internal Setup — {date}
## Global Configuration
### Instructions (CLAUDE.md) | Rules ({N}) | Agents ({N}) | Skills ({N})
## Project Configuration
### Project Instructions | Project Rules
## Memory
### Active Memories ({N} entries)
## Summary
| Component | Count | Location |

RESEARCH output structure:

# Research: {query} — {date}
## Findings
### {Source Group 1} ...
## Sources
| Fact | Source | Reliability |
## Review Verdict

EXTERNAL context-schema sub-mode writes to .claude/brewdoc/my-claude/external/YYYYMMDD_context-schema.md instead of the default path.

RESEARCH agent count: 2–5 general-purpose agents spawned in parallel, one per source group (official docs, GitHub issues, Reddit/forums, marketplaces, community Discord).

🔄

docsync-setup

Track doc staleness — keeps Markdown, MDX, and knowledge files current by date.

🧠

memory-sync-setup

Generates a project-local /memory-sync skill for CLAUDE.md, rules and conventions — delete-first, non-growth.

🔗

GitHub source

Source code, reference files, and mode instructions.

📄

brewdoc overview

All brewdoc skills — docsync-setup, my-claude, memory-sync-setup, md-to-pdf, publish.

Updating plugins

Use /brewtools:plugin-update to check and update the brewcode plugin suite in one command. See the FAQ for details.