Churn

One command. Every doc your project needs. Every question your interview demands.

---

Install

pip install churn-cli

For PDF export support (--only pdf):

pip install "churn-cli[pdf]"

For Groq or OpenAI as your provider:

pip install "churn-cli[groq]"
pip install "churn-cli[openai]"

Requires Python 3.8+. By default Churn uses Gemini — get a free key at aistudio.google.com.

---

Usage

Churn has two main commands: interview for interview prep, and docs for documentation generation. Point either at a local folder or a public/private GitHub repo URL — Churn clones it to a temp folder, scans it, and deletes the clone automatically when it's done.

churn interview /path/to/your/project
churn interview https://github.com/owner/repo

churn docs /path/to/your/project
churn docs https://github.com/owner/repo

First run pe active provider ka API key maangega — ek baar enter karo, save ho jaata hai globally (~/.churn/config.json).

---

churn interview

Generates level-wise interview Q&A from your codebase.

churn interview /path/to/project
churn interview https://github.com/owner/repo                # works directly on a GitHub repo
churn interview /path/to/project --level senior          # skip interactive prompt
churn interview /path/to/project --questions 15           # custom question count (default: 10)
churn interview /path/to/project --output report.md        # custom output file
churn interview /path/to/project --format json             # json output instead of markdown
churn interview /path/to/project --ignore tests/ --ignore migrations/   # skip folders

Options

-q, --questions INTEGER           Number of questions  [default: 10]
-l, --level [fresher|mid|senior]  Skip prompt, set level directly
-o, --output TEXT                 Output file  [default: churn-output.md]
-f, --format [md|json]            Output format  [default: md]
-i, --ignore TEXT                 Extra folders to ignore (repeatable)

Output Example

# Churn — MID Level

**Q1: In `matchingService.js`, what are the three criteria for a perfect match?**

The `findMatches` function checks: same campus, userProfile's wantedElectives includes
student's currentElective, and student's wantedElectives includes userProfile's currentElective.

---

---

churn docs

Generates complete project documentation from your codebase.

churn docs /path/to/project
churn docs https://github.com/owner/repo               # works directly on a GitHub repo
churn docs /path/to/project --only readme,prd          # generate only specific docs
churn docs /path/to/project --only readme,prd,arch,pdf # include a combined PDF report
churn docs /path/to/project --output my-docs/           # custom output folder
churn docs /path/to/project --ignore tests/             # skip folders
churn docs /path/to/project --force                     # regenerate even if code is unchanged

Options

--only TEXT        Comma separated: readme, prd, arch, pdf  [default: readme,prd,arch]
-o, --output TEXT  Output folder  [default: churn-docs/]
-i, --ignore TEXT  Extra folders to ignore (repeatable)
--force            Regenerate every doc even if the code hasn't changed since the last run

Output

churn-docs/
├── README.md       — what it does, setup, usage, tech stack
├── PRD.md          — problem, features, roadmap inferred from code
├── ARCHITECTURE.md — folder structure, data flow, key files
└── REPORT.pdf       — all three combined, shareable (only with --only ...,pdf)

Each doc is generated strictly from what's in the code — README, PRD, and ARCHITECTURE don't invent features, flags, or files that aren't actually there. The PRD's roadmap section is inferred from real TODOs and unfinished code paths, not guesses.

Smart caching: Churn hashes your compressed code on every run. If nothing's changed since the last docs run, unchanged doc types are skipped instead of re-generated — saving API calls. Use --force to regenerate anyway. If a doc already exists, Churn updates it instead of rewriting from scratch, preserving wording that's still accurate. This caching is stable even for GitHub URLs — re-cloning the same repo produces the same hash.

PDF export uses xhtml2pdf (pure Python) — no native GTK/Cairo dependencies, so it works out of the box on Windows, macOS, and Linux. Requires pip install "churn-cli[pdf]".

---

GitHub URL Support

Both churn interview and churn docs accept a GitHub repo URL in place of a local path:

churn interview https://github.com/owner/repo
churn docs https://github.com/owner/repo --only readme,prd

What happens under the hood:

1. Churn shallow-clones the repo (git clone --depth 1) into a temp directory
2. Scans and compresses it exactly like a local project
3. Deletes the temp clone the moment it's done — success or failure, the clone never survives past the command

Public repos work with no setup. For private repos (or to avoid GitHub's low unauthenticated rate limits), set a token first:

churn auth github                          # interactive prompt
churn auth github --token ghp_xxxxxxxx     # non-interactive
churn auth github --logout                 # remove the stored token

Fine-grained PAT scope needed: if you're using a fine-grained personal access token, "Repository access" alone isn't enough — under Permissions → Repository permissions, set Contents to at least Read-only, or cloning will fail with a 403 / "Write access to repository not granted" error even for private repos you own.

The token is stored the same way as AI provider keys — locally in ~/.churn/config.json, masked in churn auth status and churn config show, never transmitted anywhere except directly to GitHub during the clone. You can also set it via the GITHUB_TOKEN environment variable instead.

---

churn auth

Manage API key authentication per provider, and your GitHub token.

churn auth login                       # set/update key for the active provider
churn auth login --provider groq       # set/update key for a specific provider
churn auth logout                      # remove key for the active provider
churn auth logout --provider openai    # remove key for a specific provider
churn auth status                      # show active provider + masked key status for all providers + GitHub
churn auth github                      # set/update your GitHub token (for GitHub URL support)
churn auth github --logout             # remove the stored GitHub token

---

churn config

View and edit local Churn configuration.

churn config show                  # print full config (API keys + GitHub token masked)
churn config set theme dark        # set a non-secret config value
churn config provider              # interactively switch active provider
churn config provider groq         # switch active provider directly
churn config open                  # print (and try to open) the config file location

api_key, providers, and active_provider can't be changed via config set — use churn auth login / churn auth github and churn config provider for those.

---

churn update

Check PyPI for a newer version and self-update.

churn update
churn --update   # equivalent global flag

---

Global Flags

churn --version   # show version
churn --update    # check for and install the latest version from PyPI
churn --help      # show all commands and options

---

What It Does

Churn scans a local project directory (or clones a GitHub URL), identifies the most frequently edited files using git log, compresses the code, and sends it to your active AI provider (Gemini by default, Groq or OpenAI as alternatives).

• churn interview returns interview questions with detailed answers, saved as markdown or JSON.
• churn docs returns a full documentation set (README, PRD, ARCHITECTURE, and an optional combined PDF report).

---

Providers

Churn supports multiple AI providers — switch anytime with churn config provider:

Provider	Model	Notes
Gemini (default)	gemini-flash-latest	Auto-falls back to gemini-2.5-flash on 503. Most generous free tier of the three.
Groq	llama-3.3-70b-versatile	Requires pip install "churn-cli[groq]". Free tier has a daily token cap that resets ~24h after it's hit.
OpenAI	gpt-4o-mini	Requires pip install "churn-cli[openai]". No auto-renewing free tier — needs prepaid credits added at platform.openai.com before use.

Keys can also be set via environment variables instead of churn auth login: GEMINI_API_KEY, GROQ_API_KEY, OPENAI_API_KEY — these take precedence over stored keys.

---

Files Scanned

Included: .py .js .ts .tsx .jsx .java .go .cpp .env.example

Ignored: node_modules/ .git/ dist/ build/ __pycache__/ .next/ venv/ churn-env/ .env

User can pass additional folders to ignore via -i/--ignore (repeatable).

---

Privacy

• No code is stored at any point
• Everything runs locally — no backend server
• Code is sent to your active provider's API for processing only
• .env files are never scanned — hardcoded in the ignore list
• API keys and your GitHub token are stored locally at ~/.churn/config.json (file permissions locked to owner-only where supported), never transmitted anywhere else
• GitHub clones are deleted immediately after scanning, whether the run succeeds or fails

---

Tech Stack

• Python 3.8+
• click — CLI framework
• questionary — interactive prompts
• python-dotenv — environment variables
• google-genai — Gemini API SDK
• groq — Groq API SDK (optional)
• openai — OpenAI API SDK (optional)
• markdown + xhtml2pdf — PDF report export (optional)
• git (system binary) — repo history scanning and GitHub URL cloning

---

Local Development

git clone https://github.com/DhawalShankar/project-churn
cd project-churn
python -m venv venv
venv\Scripts\activate        # Windows
source venv/bin/activate     # Mac/Linux
pip install -e ".[pdf]"
churn interview /path/to/project
churn docs /path/to/project

---

Roadmap

• PyPI publish — pip install churn-cli
• Custom question count — --questions
• Custom output path — --output
• JSON export — --format json
• Skip folders — --ignore
• churn docs — README, PRD, ARCHITECTURE generation
• PDF export — REPORT.pdf
• Multi-provider support (Groq, OpenAI) — churn config provider
• Self-update — churn update / --update
• Doc caching — skip unchanged docs, update instead of rewrite
• GitHub public and private repo URL support — clone, scan, auto-cleanup + churn auth github
• VS Code Extension
• Custom focus flag — --focus security
• Rich progress bars (replace plain click.echo status lines)

---

License

Personal project. All rights reserved. © 2026 dhawalshankar