{"id":50185663,"url":"https://github.com/akadeepesh/contextzip","last_synced_at":"2026-05-25T10:01:29.393Z","repository":{"id":357984071,"uuid":"1238352328","full_name":"akadeepesh/contextzip","owner":"akadeepesh","description":"CLI tool for intelligent project packaging with framework detection, smart exclusions, and git-aware file selection.","archived":false,"fork":false,"pushed_at":"2026-05-20T18:18:33.000Z","size":101,"stargazers_count":5,"open_issues_count":2,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-20T23:55:24.994Z","etag":null,"topics":["ai-tools","automation","chatgpt","claude-ai","cli","code-packaging","context-window","developer-tools","devtools","git","github","llm","python","zip"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/contextzip/","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/akadeepesh.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","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-05-14T03:34:35.000Z","updated_at":"2026-05-20T18:43:09.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/akadeepesh/contextzip","commit_stats":null,"previous_names":["akadeepesh/smart-context-packager","akadeepesh/contextzip"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/akadeepesh/contextzip","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/akadeepesh%2Fcontextzip","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/akadeepesh%2Fcontextzip/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/akadeepesh%2Fcontextzip/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/akadeepesh%2Fcontextzip/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/akadeepesh","download_url":"https://codeload.github.com/akadeepesh/contextzip/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/akadeepesh%2Fcontextzip/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33469418,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-25T06:32:55.349Z","status":"ssl_error","status_checked_at":"2026-05-25T06:32:35.322Z","response_time":57,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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-tools","automation","chatgpt","claude-ai","cli","code-packaging","context-window","developer-tools","devtools","git","github","llm","python","zip"],"created_at":"2026-05-25T10:01:21.492Z","updated_at":"2026-05-25T10:01:29.375Z","avatar_url":"https://github.com/akadeepesh.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# contextzip\n\n\u003e Package exactly the right parts of your codebase and paste it into any AI tool — in one command.\n\n```bash\npip install contextzip\n```\n\n---\n\n## Why contextzip\n\nEvery AI session starts the same way: hunt down the relevant files, manually skip `node_modules`, build artifacts, and lock files, zip them, find the zip, upload it. Then do it all again next session.\n\ncontextzip eliminates that entirely. Run it from your project root — it detects your stack, applies smart exclusions, produces a lean ZIP, and opens your file manager with the archive already selected. One `Ctrl+C` and you're done.\n\n---\n\n## Features\n\n- **Smart framework detection** — automatically identifies Node.js, Next.js, Python, Django, FastAPI, Rust, Go, and Ruby, applying the right exclusion rules for each\n- **Respects `.gitignore`** — your existing ignore patterns are honoured automatically\n- **Git-aware packaging** — use `--git-changes` to package only modified, staged, and untracked files; perfect for incremental debugging and PR review sessions\n- **AI-powered file selection** — describe your task in plain English with `--prompt` and Gemini selects the minimum relevant files automatically, no manual hunting required\n- **Terminal error watcher** — wrap any dev server with `contextzip watch` to auto-detect errors and package a ready-to-upload debug context in one keypress\n- **Persistent workspace** — all generated ZIPs land in `.contextzip/` at your project root, discoverable, reusable, and git-ignored automatically\n- **Warns before it's a problem** — flags large (≥ 1 MB) and binary files that AI tools can't read, before you waste an upload\n- **Handles edge cases** — dangling symlinks, unreadable files, and paths outside the project tree are caught and reported, never silently dropped\n- **Full CLI control** — `--include`, `--exclude`, `--dry-run`, `--output`, all composable\n\n---\n\n## Installation\n\n**Requires Python 3.9+**\n\n```bash\npip install contextzip\n```\n\nWith [pipx](https://pipx.pypa.io/) (recommended for CLI tools — keeps it isolated):\n\n```bash\npipx install contextzip\n```\n\nVerify:\n\n```bash\ncontextzip --version\n```\n\n---\n\n## Quick start\n\nNavigate to any project and run:\n\n```bash\ncd ~/projects/my-app\ncontextzip\n```\n\ncontextzip will:\n\n1. Detect your framework (e.g. `Next.js + Node.js`)\n2. Apply the appropriate exclusion rules\n3. Create a compressed ZIP in `.contextzip/` at your project root\n4. Open your file manager with the ZIP selected and ready to copy\n\n---\n\n## Usage\n\n```\ncontextzip [OPTIONS]\n```\n\n| Option | Description |\n|---|---|\n| `-p`, `--prompt TEXT` | Describe your task in plain English — Gemini selects only the relevant files |\n| `-i`, `--include PATH` | Only include files under this path (repeatable) |\n| `-e`, `--exclude PATTERN` | Add exclusion patterns in gitignore syntax (repeatable) |\n| `--git-changes` | Only include files reported by git as modified, staged, or untracked |\n| `-n`, `--dry-run` | Preview what would be included without creating a ZIP |\n| `-o`, `--output FILE` | Write ZIP to a custom path |\n| `-v`, `--verbose` | Show every included and excluded file with sizes |\n| `--no-clipboard` | Skip the clipboard / folder-open step |\n| `--no-gitignore` | Ignore the project's `.gitignore` |\n\n**Subcommands:** `exclude`, `include`, `watch`, `config` — run `contextzip --help` for full details.\n\n---\n\n## Examples\n\n```bash\n# Preview what would be packaged\ncontextzip --dry-run --verbose\n\n# Package only specific directories\ncontextzip --include src --include app\n\n# Exclude additional patterns\ncontextzip --exclude \"*.log\" --exclude \"tests/\"\n\n# Package only git-modified files\ncontextzip --git-changes\n\n# Let AI pick only the files relevant to your task\ncontextzip --prompt \"Change toast color on failed login\"\n\n# Preview AI file selection without creating a ZIP\ncontextzip --prompt \"Refactor auth middleware\" --dry-run\n\n# Save to a custom path\ncontextzip --output ~/Desktop/project-context.zip\n```\n\n---\n\n## AI-powered file selection\n\nThe `--prompt` flag lets you describe a task in plain English. contextzip scans your project, builds a lightweight file map, and asks Gemini to return the minimum set of files needed for that task — typically 2–5, never more than 10. The result is a tightly scoped ZIP with only what you'd actually open to make the change.\n\n```bash\ncontextzip --prompt \"Change toast color on failed login\"\n# → components/ui/toast.tsx, app/login/page.tsx, lib/auth.ts\n```\n\nThe ZIP also includes a `prompt.txt` describing the task, so when you drop it into Claude, ChatGPT, or any other AI tool, it immediately understands what you're trying to do.\n\n**First-time setup:** `--prompt` requires a free Gemini API key from [Google AI Studio](https://aistudio.google.com/apikey) — no credit card needed. On first use, contextzip guides you through obtaining and saving one. You can also skip the setup entirely with an environment variable:\n\n```bash\nexport GEMINI_API_KEY=AIza...\n```\n\nManage your key at any time:\n\n```bash\ncontextzip config               # show current key status\ncontextzip config --reset-key   # clear and re-run setup\n```\n\n---\n\n## Terminal error watcher\n\nThe `watch` command wraps your dev server, buffers its output, and packages a debug-ready ZIP the moment you spot an error — no manual file hunting, no copy-pasting stack traces.\n\n```bash\ncontextzip watch -- npm run dev\ncontextzip watch -- python manage.py runserver\n```\n\ncontextzip starts your process normally. You see output exactly as you would without it. In the background, it watches the stream for errors. When one is detected, a prompt appears directly beneath the error output:\n\n```\n╭─ contextzip · error detected ─────────────────────╮\n│  Press [D] to package debug context  [S] to skip  │\n╰───────────────────────────────────────────────────╯\n```\n\nPress **D** and contextzip immediately writes `.contextzip/debug-context.zip`. Your server keeps running — no restart, no interruption.\n\n**What's in the ZIP:**\n\n| File | Contents |\n|---|---|\n| `prompt.txt` | Auto-generated: detected framework, error type, and task description — ready to paste into any AI tool |\n| `terminal-error.txt` | The cleaned, noise-stripped error block and stack trace |\n| `source-files.zip` | Source files referenced in the stack trace, paths preserved |\n\n**On Ctrl+C:** If no errors were packaged during the session, contextzip offers one final prompt to capture the full session output — useful when something looked wrong but didn't match a known error pattern.\n\n**Supported frameworks:** Python, Django, FastAPI, Node.js, Next.js, React. Each has its own error detection patterns and noise filters so the output stays clean across stacks.\n\n\u003e **Note:** `watch` works best with dev servers that don't read stdin interactively (`npm run dev`, `manage.py runserver`, etc.). PTY emulation is not used — on Windows, color passthrough may be limited.\n\n---\n\n## What gets excluded\n\ncontextzip stacks exclusion rules based on your detected stack, on top of your `.gitignore`.\n\n**Always excluded:** `.git/`, `.env` files, logs, caches, editor config (`.vscode/`, `.idea/`), OS files (`.DS_Store`, `Thumbs.db`), and common binary formats.\n\n**By framework:**\n\n| Stack | Additional exclusions |\n|---|---|\n| Node.js / Next.js | `node_modules/`, `.next/`, `dist/`, `build/`, lock files, `*.min.js`, `*.d.ts` |\n| Python / Django / FastAPI | `__pycache__/`, `.venv/`, `*.pyc`, `migrations/`, `.pytest_cache/`, lock files |\n| Rust | `target/`, `Cargo.lock`, `*.rlib` |\n| Go | `vendor/`, `go.sum`, `bin/` |\n\nDetection is additive — a monorepo with both `package.json` and `pyproject.toml` gets both rule sets applied.\n\n---\n\n## Contributing\n\nContributions are welcome — especially new framework rule sets, edge case fixes, and platform-specific clipboard improvements.\n\nSee [CONTRIBUTING.md](https://github.com/akadeepesh/contextzip/blob/main/CONTRIBUTING.md) for local setup, how to add a new framework, and PR guidelines. Please open an issue before starting a large PR so we can align on the approach first.\n\n---\n\n## License\n\nMIT — see [LICENSE](https://github.com/akadeepesh/contextzip/blob/main/LICENSE) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fakadeepesh%2Fcontextzip","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fakadeepesh%2Fcontextzip","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fakadeepesh%2Fcontextzip/lists"}