{"id":50478314,"url":"https://github.com/etherman-os/ctx-shrink","last_synced_at":"2026-06-01T15:03:56.341Z","repository":{"id":349316106,"uuid":"1201852580","full_name":"etherman-os/ctx-shrink","owner":"etherman-os","description":"Codebase analyzer for the AI era — generates smart context maps for AI agents and catches packaging mistakes before they leak. ","archived":false,"fork":false,"pushed_at":"2026-04-05T09:11:59.000Z","size":13,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-05T11:14:42.149Z","etag":null,"topics":["ai","code-analysis","code-review","developer-tools","git","open-source","python","security","static-analysis"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/etherman-os.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-05T08:54:33.000Z","updated_at":"2026-04-05T09:24:48.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/etherman-os/ctx-shrink","commit_stats":null,"previous_names":["etherman-os/ctx-shrink"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/etherman-os/ctx-shrink","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/etherman-os%2Fctx-shrink","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/etherman-os%2Fctx-shrink/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/etherman-os%2Fctx-shrink/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/etherman-os%2Fctx-shrink/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/etherman-os","download_url":"https://codeload.github.com/etherman-os/ctx-shrink/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/etherman-os%2Fctx-shrink/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33780090,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-01T02:00:06.963Z","response_time":115,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","code-analysis","code-review","developer-tools","git","open-source","python","security","static-analysis"],"created_at":"2026-06-01T15:03:54.654Z","updated_at":"2026-06-01T15:03:56.333Z","avatar_url":"https://github.com/etherman-os.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🛡️ ctx-shrink\n\n\u003e Codebase analyzer for the AI era — generates smart context maps for AI agents and catches packaging mistakes before they leak.\n\n[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)\n[![Zero Dependencies](https://img.shields.io/badge/dependencies-zero-brightgreen.svg)]()\n[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](./LICENSE)\n\n---\n\nIn March 2026, 512,000 lines of source code leaked through a single forgotten `*.map` file in a public npm package.\n\n**`ctx-shrink` catches these mistakes BEFORE you publish — and generates smart project maps for AI coding agents.**\n\n## ✅ What it does\n\n| Check | What it catches |\n|-------|----------------|\n| 📊 **Project Analysis** | Architecture, endpoints, models, dependencies — a smart map for AI agents |\n| 🛡️ **Gitignore Audit** | `.env`, secrets, keys that aren't in `.gitignore` |\n| 📦 **Publish Safety** | Source maps, private keys, certs that would leak on `npm publish` / `pip install` |\n\n**Zero dependencies. No API. No telemetry. Just Python.**\n\n## 🚀 Install\n\n### Option 1: Clone and run (recommended)\n\nClone the repo and run the checked-in script (reviewable; no blind remote execute):\n\n```bash\ngit clone https://github.com/etherman-os/ctx-shrink.git\ncd ctx-shrink\nchmod +x ctx-shrink\npython3 ctx-shrink /path/to/your/project\n```\n\n### Option 2: Add to your PATH (user directory)\n\n```bash\nmkdir -p ~/.local/bin\nln -sf \"$(pwd)/ctx-shrink\" ~/.local/bin/ctx-shrink\n# Ensure ~/.local/bin is on PATH (e.g. in ~/.profile)\n```\n\nPinned [GitHub Releases](https://github.com/etherman-os/ctx-shrink/releases) may publish checksums for artifacts; prefer those over ad-hoc downloads when available.\n\n## 📊 Usage\n\n### Analyze a project\n\n```bash\nctx-shrink .\n```\n\n**Output:** `AI-CONTEXT.md` — a smart project map you can feed to AI coding agents (Aider, Claude Code, Cursor, Codex CLI).\n\n```\n📦 ctx-shrink v2: Analyzing my-api-project...\n   Found 142 files (32,450 lines)\n   Analyzing architecture, endpoints, models, dependencies...\n   Checking .gitignore safety...\n\n   ⚠️ 1 publish-safety issue(s) found\n\n✅ Project analysis saved to: AI-CONTEXT.md\n   142 files → 12.3 KB (389 lines)\n```\n\n### Flags\n\n```bash\nctx-shrink . --max-depth 4      # Limit directory depth\nctx-shrink . --format json      # JSON output\nctx-shrink . --out report.md    # Custom output file\n```\n\n## 🔍 Example output\n\n### 🛡️ Gitignore Audit\n\nCatches sensitive files you forgot to ignore:\n\n```\n## 🛡️ Gitignore Audit\n\n⚠️ 2 sensitive file(s) found that are NOT in .gitignore!\n\n| File              | Size | Risk        |\n|-------------------|------|-------------|\n| .env.production   | 2.1 KB| 🔴 CRITICAL |\n| config/secrets.yml| 145 B | 🔴 CRITICAL |\n\n### 🔧 Quick Fix\nAdd these to your `.gitignore`:\n\n.env.production\nsecrets.yml\n```\n\n### 📦 Publish Safety Audit\n\nCatches packaging mistakes **before** you publish:\n\n```\n## 📦 Publish Safety Audit\n\n⚠️ 1 file(s) that should NOT be in a published package:\n\n| File              | Size | Reason                        |\n|-------------------|------|-------------------------------|\n| dist/index.js.map | 59 MB| Can expose entire source code |\n\n### ⚠️ Warnings\n- Large file (2.0 MB): dist/assets/index.js — could bloat package\n```\n\n### 📊 Project Analysis\n\n```\n## 📊 Overview\n\n- **Files:** 142\n- **Lines of Code:** 32,450\n- **Size:** 1,240.5 KB\n- **Project Type:** Python FastAPI, Docker\n- **Languages:**\n  - `.py`  ██████████████████████████████░░░░░░░░░░░░░░  58.2%  (18,890 lines)\n  - `.ts`  ████████████░░░░░░░░░░░░░░░░░░░░░░░░░░░░  25.1%  (8,150 lines)\n\n## 🌐 API Endpoints\n\n| Method | Path              | File              |\n|--------|-------------------|-------------------|\n| GET    | /api/users        | routers/users.py  |\n| POST   | /api/auth/login   | routers/auth.py   |\n| GET    | /api/products     | routers/items.py  |\n```\n\n## 🤖 Works with AI Agents\n\nFeed `AI-CONTEXT.md` to any AI coding agent:\n\n- ✅ **Aider** → `aider --read AI-CONTEXT.md`\n- ✅ **Claude Code** → paste into chat\n- ✅ **Cursor** → use as context\n- ✅ **Codex CLI** → feed as context\n\nInstead of wasting tokens on 100K+ lines of code, the AI gets a **smart map** and reads specific files on demand.\n\n## 🧩 What it analyzes\n\n```\nYour Project\n│\n├── scan_files() ────────→ AI-CONTEXT.md (project map)\n│                          • Architecture tree\n│                          • API endpoints\n│                          • Data models\n│                          • Functions catalog\n│                          • Import dependencies\n│\n├── check_gitignore() ───→ Missing .gitignore rules\n│\n└── check_publish_safety() → Packaging issues (source maps, keys, certs)\n```\n\n**No AI. No API. No internet needed.** Pure file analysis with regex and pattern matching.\n\n## ⚙️ How it works\n\n1. **Scans** your project, skipping build artifacts and `node_modules`\n2. **Detects** project type (FastAPI, Express, React, etc.)\n3. **Extracts** API endpoints from route decorators\n4. **Models** database schemas, ORM classes, Pydantic models\n5. **Maps** imports to understand dependencies\n6. **Audits** `.gitignore` for missing rules\n7. **Checks** for files that shouldn't be published (like source maps)\n\n## 📈 Before vs After\n\n### Before ctx-shrink\n- ❌ 100K+ lines → AI can't fit in context window\n- ❌ `.env` files leaked to git or published\n- ❌ Source maps accidentally included in npm packages\n- ❌ No quick overview of a new codebase\n\n### After ctx-shrink\n- ✅ **12 KB** smart analysis → fits any context window\n- ✅ Secret files flagged before they leak\n- ✅ Source maps, keys, certs caught before publish\n- ✅ Full architecture map in seconds\n\n## 📝 License\n\nMIT — use it however you want.\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n**Made because `*.map` shouldn't expose 512,000 lines of code.**\n\n⭐ Star this repo if you found it useful.\n\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fetherman-os%2Fctx-shrink","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fetherman-os%2Fctx-shrink","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fetherman-os%2Fctx-shrink/lists"}