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]"

Requires Python 3.8+ and a Gemini API key from aistudio.google.com

Usage

Churn has two commands: interview for interview prep, and docs for documentation generation.

churn interview /path/to/your/project
churn docs /path/to/your/project

First run pe Gemini API key maangega — ek baar enter karo, save ho jaata hai globally.

churn interview

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

churn interview /path/to/project
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 /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

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)

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.

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]".

Global Flags

churn --version   # show version
churn --help      # show all options

What It Does

Churn scans a local project directory, identifies the most frequently edited files using git log, compresses the code, and sends it to the Gemini API.

• 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).

Files Scanned

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

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

Privacy

• No code is stored at any point
• Everything runs locally — no backend server
• Code is sent to Gemini API for processing only
• Gemini API does not use API request data for model training

Tech Stack

• Python 3.8+
• google-genai — Gemini API SDK
• click — CLI
• python-dotenv — environment variables
• questionary — interactive prompts
• markdown + xhtml2pdf — PDF report export (optional)

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, Claude) — --provider
• GitHub public repo URL support
• VS Code Extension
• Custom focus flag — --focus security

License

Personal project. All rights reserved. © 2026 dhawalshankar