PitchDocs — Frequently Asked Questions

Quick answers to the questions PitchDocs users ask most often. Also surfaced at https://littlebearapps.com/help/pitchdocs/.

How do I install PitchDocs?#

PitchDocs installs as a Claude Code or OpenCode plugin in two commands:

# 1. Add the LBA plugin marketplace (once per machine)
/plugin marketplace add littlebearapps/lba-plugins

# 2. Install PitchDocs
/plugin install pitchdocs@lba-plugins

# 3. Generate a README for any project
/pitchdocs:readme

When installed as a plugin, every command uses the pitchdocs: prefix — /pitchdocs:readme, /pitchdocs:changelog, /pitchdocs:docs-audit, and so on. The unprefixed short forms only work inside the PitchDocs source repository itself.

For other AI tools (Codex CLI, Cursor, Cline, Windsurf, Gemini CLI, Aider, Goose), see the Other AI Tools setup guide.

Does PitchDocs work with AI tools other than Claude Code?#

Yes. PitchDocs is 100% Markdown with zero runtime dependencies, so it works with any AI coding assistant that can read skill files. The Other AI Tools guide walks through setup for Codex CLI, OpenCode, Cursor, Cline, Windsurf, Gemini CLI, Aider, and Goose.

The dist/ directory in the PitchDocs repo ships pre-built distributions for each platform, generated by scripts/build-dist.sh from the canonical .claude/ sources. Slash commands work natively in Claude Code and OpenCode; other tools either copy commands into their prompt directories or reference the skills on demand. Check the Cross-Tool Limitations table to see exactly what each platform supports.

Where does my data go?#

Nowhere external. PitchDocs ships as a Markdown-only plugin with no runtime, no telemetry, and no API calls of its own — your AI coding tool reads the skill files locally and runs entirely on your machine.

When PitchDocs commands generate documentation, the AI tool you already use (Claude Code, OpenCode, Cursor, etc.) handles the model calls under your own account, with the privacy and data-handling guarantees of that vendor. The optional GitHub MCP integration used by /pitchdocs:roadmap and /pitchdocs:changelog calls GitHub through your own gh CLI authentication — PitchDocs never sees or stores credentials.

In short: your code stays on your machine, your model calls go through your existing tool’s account, and PitchDocs itself is just structured Markdown.

Can I run PitchDocs on a private repo?#

Yes. PitchDocs works entirely locally — it reads your codebase via file system access. The optional GitHub MCP integration (for milestones, releases, and issues) requires gh CLI authentication but never exposes your code to external services.

Does PitchDocs overwrite my existing README?#

No. When a README.md already exists, PitchDocs reads it first and improves it rather than replacing it from scratch. Custom sections, screenshots, and content you’ve added manually are preserved. If you want a fresh start, you can rename the existing file or run with explicit overwrite intent in the prompt.

How do I use PitchDocs with a monorepo?#

Point commands at specific packages. For example:

/pitchdocs:readme packages/api
/pitchdocs:features packages/ui
/pitchdocs:changelog packages/cli

Each package can have its own README, CHANGELOG, and feature audit. The Customising Output guide covers monorepo patterns and how to scope commands to a workspace.

What happens if generation fails with a content filter error?#

Claude Code’s API content filter occasionally blocks output (HTTP 400) when generating standardised open-source files like CODE_OF_CONDUCT.md, LICENSE, or SECURITY.md. This is a context-blind copyright filter — it triggers on governance language and verbatim legal text even when the intent is entirely legitimate.

The fix is to fetch high-risk files from canonical URLs rather than generating them inline:

# Contributor Covenant v3.0
curl -sL "https://www.contributor-covenant.org/version/3/0/code_of_conduct/code_of_conduct.md" -o CODE_OF_CONDUCT.md

# MIT License (substitute SPDX identifier as needed)
curl -sL "https://raw.githubusercontent.com/spdx/license-list-data/main/text/MIT.txt" -o LICENSE

For medium-risk files (CHANGELOG.md, CONTRIBUTING.md), write in chunks of 5–10 entries and start with project-specific content before generic sections. Do not retry the same blocked content — the filter is largely deterministic. The full mitigation playbook lives in the Content Filter Errors section of the troubleshooting guide.

Why doesn’t PitchDocs auto-trigger when I use claude -p?#

PitchDocs skills may not auto-activate when invoked through claude -p (headless / non-interactive mode). This is a known Claude Code platform issue affecting all project-local plugins — it isn’t a PitchDocs bug.

What works normally:

• Interactive Claude Code sessions (terminal, IDE extensions, Untether)
• Hooks, rules, and agents — these don’t rely on skill routing
• Explicit slash commands typed in an interactive session

What’s affected:

• Shell scripts calling claude -p "generate a readme" expecting skill auto-activation
• CI pipelines invoking PitchDocs skills via claude -p

If you need PitchDocs in CI today, call commands explicitly through an interactive wrapper or use the pre-built dist/ distribution that targets your platform.

How do I update PitchDocs?#

In Claude Code or OpenCode:

/plugin update pitchdocs@lba-plugins

That pulls the latest tagged release from the LBA plugin marketplace. For other AI tools that installed via scripts/setup.sh, re-run the installer against the latest release tag — it auto-detects your platform and refreshes the relevant files in dist/.

You can check the current version against the latest in the CHANGELOG. PitchDocs follows release-please automation, so every conventional commit on main either bumps the version or queues up the next release PR.

How do I uninstall PitchDocs?#

In Claude Code or OpenCode:

/plugin uninstall pitchdocs@lba-plugins

That removes the plugin itself. If you ran /pitchdocs:activate install (or install strict) inside a project, also delete the per-project files it copied into .claude/:

rm -f .claude/rules/doc-standards.md
rm -f .claude/rules/docs-awareness.md
rm -f .claude/agents/docs-freshness.md
rm -f .claude/hooks/content-filter-guard.sh   # only present in strict mode

Generated documentation (your README.md, CHANGELOG.md, docs/, etc.) stays untouched — it’s yours, and it doesn’t depend on PitchDocs at runtime.

---

Need more help? See SUPPORT.md for contact details and response times, or browse the full Troubleshooting & FAQ guide for deeper debugging.