Churn

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

Open source. Bring your own AI provider key — free and unlimited, forever.

---

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 doctor

Instantly scores a project's health — no AI call, runs in a fraction of a second.

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

Checks README and ARCHITECTURE quality (heuristic — length, headings, keyword coverage), plus presence of a LICENSE, Docker setup, CI/CD (GitHub Actions or other), .gitignore, and a tests folder. Gives a weighted overall grade and a short list of concrete fixes.

Output Example

  README         ●●●●●●●●●○  9/10
  Architecture   ●●●●●●●●○○  8/10
  License        ✗ Missing
  Docker         ✓ Present
  CI/CD          ✗ Missing
  GitHub Actions ✗ Missing
  .gitignore     ✓ Present
  Tests          ✗ Missing

  Overall: B+ (87.0%)

  → Add a LICENSE file — takes 30 seconds and shows the project is usable.
  → No CI/CD detected — even a basic test-on-push workflow helps.
  → No tests folder found — interviewers often ask about testing strategy.

Run this before an interview — it flags exactly what a reviewer or interviewer is likely to notice missing, before they do.

doctor vs interview — what's the difference? churn doctor is a fast, external checklist — it looks at what's around your code (README, LICENSE, CI config, tests folder) and tells you what's missing, instantly, with no AI call. churn interview goes deeper — it actually reads your code and generates questions about your logic, design decisions, and tradeoffs, the way a real interviewer would probe inside the project. Run doctor first for a quick fix-list, then interview to prep for the harder questions about how it actually works.

---

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.

Why bring your own key? The CLI is fully open source and runs entirely on your machine — Churn never sees or stores your code. Since it's your key making the API calls, the CLI itself has no usage limits and costs you nothing beyond your own provider's rate limits. A hosted, no-setup version (no key required) is planned as a separate paid offering — see Premium / Hosted below.

---

Premium / Hosted (Planned)

The CLI will always be free and open source, using your own AI provider key.

For people who don't want to manage a key or install anything, a hosted version is planned — you paste a GitHub URL on the website (or hit the REST API), Churn uses its own key on the backend, and you get output with zero setup. Because that costs Churn money per request, it'll be a paid, tiered offering (Free / Starter / Pro — see the PRD for details). This hosted backend is a separate, closed-source service and is not part of this repository.

---

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
• churn doctor — instant, no-AI project health score (README/arch heuristics + file-presence checks)
• VS Code Extension
• Custom focus flag — --focus security
• Rich progress bars (replace plain click.echo status lines)
• Hosted REST API + website (paid, Churn's own key, zero setup)

---

License

MIT © 2026 dhawalshankar

The CLI is fully open source — it uses your own AI provider API key, so it stays free and unlimited for everyone. The planned hosted REST API / website is a separate, closed-source offering for people who'd rather not manage a key themselves.