{"id":50366844,"url":"https://github.com/rishiskhare/readzip","last_synced_at":"2026-05-30T04:30:58.705Z","repository":{"id":354297656,"uuid":"1223018284","full_name":"rishiskhare/readzip","owner":"rishiskhare","description":null,"archived":false,"fork":false,"pushed_at":"2026-04-28T02:04:06.000Z","size":54,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-28T02:12:33.013Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Rust","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/rishiskhare.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-04-27T23:53:11.000Z","updated_at":"2026-04-28T02:04:06.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/rishiskhare/readzip","commit_stats":null,"previous_names":["rishiskhare/readzip"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/rishiskhare/readzip","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rishiskhare%2Freadzip","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rishiskhare%2Freadzip/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rishiskhare%2Freadzip/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rishiskhare%2Freadzip/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rishiskhare","download_url":"https://codeload.github.com/rishiskhare/readzip/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rishiskhare%2Freadzip/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33680522,"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-05-30T02:00:06.278Z","response_time":92,"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":[],"created_at":"2026-05-30T04:30:58.634Z","updated_at":"2026-05-30T04:30:58.691Z","avatar_url":"https://github.com/rishiskhare.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"assets/brand/readzip.png\" alt=\"READZIP\" width=\"820\"\u003e\n\n  \u003ch2\u003eHigh-performance file-read CLI for AI coding agents\u003c/h2\u003e\n  \u003cp\u003e\u003ci\u003e~80% fewer tokens on large files. Zero new tools to learn.\u003c/i\u003e\u003c/p\u003e\n\n  \u003cp\u003e\n    \u003ca href=\"https://github.com/rishiskhare/readzip/actions\"\u003e\u003cimg alt=\"CI\" src=\"https://img.shields.io/github/actions/workflow/status/rishiskhare/readzip/test.yml?label=CI\u0026labelColor=0b1220\u0026color=4ea8ff\"\u003e\u003c/a\u003e\n    \u003ca href=\"https://github.com/rishiskhare/readzip/releases/latest\"\u003e\u003cimg alt=\"release\" src=\"https://img.shields.io/github/v/release/rishiskhare/readzip?label=release\u0026labelColor=0b1220\u0026color=4ea8ff\"\u003e\u003c/a\u003e\n    \u003cimg alt=\"license\" src=\"https://img.shields.io/badge/license-MIT-7f88ff?labelColor=0b1220\"\u003e\n    \u003cimg alt=\"claude code\" src=\"https://img.shields.io/badge/Claude%20Code-native%20hook-4ea8ff?labelColor=0b1220\"\u003e\n    \u003cimg alt=\"tree-sitter\" src=\"https://img.shields.io/badge/tree--sitter-16%20languages-7f88ff?labelColor=0b1220\"\u003e\n  \u003c/p\u003e\n\u003c/div\u003e\n\nreadzip parses large source files with tree-sitter and returns a structural skeleton — symbols + exact line ranges — instead of dumping the full source. Single Rust binary, 16 supported languages.\n\n## Token savings (real measurement on this repo)\n\n| File | Lang | Lines | Original tokens | Skeleton tokens | Savings |\n|---|---|---:|---:|---:|---:|\n| `crates/readzip-cli/src/main.rs` | Rust | 1,086 |  9,561 | 1,199 | **−87.5%** |\n| `crates/readzip-core/src/lib.rs` | Rust |   941 |  7,917 | 1,276 | **−83.9%** |\n| **Total** |     | 2,027 | 17,478 | 2,475 | **−85.8%** |\n\nAcross files over 500 lines, average reduction is **~80%**. Run `readzip stats` after a session to see your actual numbers.\n\n## Install\n\n### One-line install (Linux / macOS)\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/rishiskhare/readzip/main/install.sh | sh\n```\n\nThe installer fetches a pre-built binary, drops it in `~/.local/bin`, and auto-wires the Claude Code `PreToolUse` hook if Claude Code is installed. (For Codex, it also drops an `AGENTS.md` snippet so the agent knows about the CLI commands.) No `init` step required. Restart your AI tool and you're done.\n\n### Cargo\n\n```bash\ncargo install --git https://github.com/rishiskhare/readzip readzip-cli\n```\n\n### Pre-built binaries\n\nDownload from [releases](https://github.com/rishiskhare/readzip/releases):\n\n- macOS: `readzip-x86_64-apple-darwin.tar.gz` / `readzip-aarch64-apple-darwin.tar.gz`\n- Linux: `readzip-x86_64-unknown-linux-gnu.tar.gz` / `readzip-aarch64-unknown-linux-gnu.tar.gz`\n\n## Verify\n\n```bash\nreadzip --version    # readzip 0.1.0\nreadzip doctor       # confirms the Claude Code hook is wired up\nreadzip stats        # tokens saved so far (zero on a fresh install)\nreadzip demo         # see compression on a 492-line bundled fixture\n```\n\n## Quick start — Claude Code\n\nAfter install, restart Claude Code. The hook intercepts native `Read` calls on files \u003e500 lines and returns a tree-sitter skeleton instead of the full source. The agent picks the section it wants and re-reads with `offset`/`limit`. Nothing else to configure.\n\n```text\n$ readzip stats\n\n  files intercepted:    14\n  tokens saved:         87.4K\n  avg reduction:        82.3%\n  cache dir:            ~/.cache/readzip\n```\n\n## Quick start — any other agent (Codex, Cursor, Cline, Windsurf, Gemini, Aider, …)\n\nreadzip is also a regular CLI. Tell your agent it has these commands available; it can call them from Bash like any other utility:\n\n```bash\nreadzip read \u003cfile\u003e                       # smart cat: skeleton if large, full if small\nreadzip section \u003cfile\u003e \u003coffset\u003e \u003climit\u003e   # scoped slice (1-indexed lines)\nreadzip skeleton \u003cfile\u003e                   # always print the skeleton\n```\n\nThat's the whole API surface for non-Claude agents. No setup, no special tool registration, no protocol shim — just three Bash commands. Same compression as Claude Code; the difference is the agent invokes it explicitly instead of being intercepted.\n\n```bash\n$ readzip read crates/readzip-core/src/lib.rs\n# crates/readzip-core/src/lib.rs -- 924 lines (Rust) skeleton view\nL1-7    imports / module header\nL14-21  struct pub struct Config\nL184-187  fn build_skeleton(path: \u0026Path, config: \u0026Config) -\u003e io::Result\u003cSkeleton\u003e\nL227-313  fn cached_skeleton(path: \u0026Path, config: \u0026Config) -\u003e io::Result\u003cSkeleton\u003e\n... (full output truncated)\n\n$ readzip section crates/readzip-core/src/lib.rs 184 4\n   184  pub fn build_skeleton(path: \u0026Path, config: \u0026Config) -\u003e io::Result\u003cSkeleton\u003e {\n   185      let source = fs::read_to_string(path)?;\n   186      Ok(build_skeleton_from_source(path, \u0026source, config))\n   187  }\n```\n\n## What gets a skeleton vs. what passes through\n\n| Read call | Behavior |\n|---|---|\n| Source file ≥ 500 lines, no offset/limit | **Skeleton + deny** (Claude) or **skeleton on stdout** (CLI). |\n| Source file \u003c 500 lines | Full content. |\n| Scoped `Read(path, offset=N, limit=M)` | Full content for the requested range, regardless of file size. |\n| Binary file (`.png`, `.so`, etc.) | Full content. |\n| Unknown extension (`.txt`, `.log`, `.csv`) | Full content. |\n| Files in `force_full_for` (`*.md`, `package.json`, …) | Full content. |\n| Files with zero top-level symbols (config-style, all-constants) | Full content. |\n\n**Every byte of every file is still reachable.** readzip never blocks content — it just inserts a structural signpost on the first read of large source files.\n\n## Supported languages\n\nreadzip uses **tree-sitter** — the same incremental parser GitHub, Neovim, Helix, and Zed use — for symbol extraction across:\n\n| | | | |\n|---|---|---|---|\n| Python | JavaScript | TypeScript | Go |\n| Rust | Java | Ruby | C |\n| C++ | C# | PHP | Swift |\n| Kotlin | Scala | Lua | Bash |\n\nSymbol end-lines come from the actual closing-brace position in the parse tree, not indent heuristics. When tree-sitter parses a file with \u003e 5% `ERROR` / `MISSING` nodes (broken or partially-edited source), readzip falls back to a line-prefix heuristic so you always get *something*. Adding a 17th language is a 4-file PR — see [docs/adding-a-language.md](docs/adding-a-language.md).\n\n## Supported AI tools\n\n| Agent | How it uses readzip |\n|---|---|\n| **Claude Code** | Transparent — the `PreToolUse` hook intercepts native `Read` automatically. Auto-wired by `install.sh`. |\n| Codex | CLI commands above. `install.sh` drops an `AGENTS.md` snippet at `~/.codex/readzip-AGENTS-snippet.md` so the agent learns about them. |\n| Cursor / Cline / Windsurf / Gemini CLI / Aider / OpenCode / anything with shell access | CLI commands above. **No setup.** Just tell the agent the three commands exist and it'll use them when reading source. |\n\nreadzip is a single-purpose CLI by design — no MCP server, no agent-specific protocol shim, no plugin to load. If your agent can run Bash, it can use readzip.\n\n## Commands\n\n```bash\n# Primary\nreadzip read \u003cfile\u003e                      # smart cat: skeleton if large, full if small\nreadzip section \u003cfile\u003e \u003coffset\u003e \u003climit\u003e  # scoped line range\nreadzip skeleton \u003cfile\u003e                  # always print the skeleton\nreadzip stats [--json]                   # tokens saved so far\n\n# Diagnostics\nreadzip doctor [--json]                  # Claude hook + Codex hint status\nreadzip demo [--json]                    # bundled fixture\nreadzip --version\n\n# Install / uninstall\nreadzip init [--yes]                     # auto-run by install.sh; rerun if needed\nreadzip uninstall [--keep-cache] [--purge]  # --purge also wipes ~/.config/readzip\n\n# Advanced (rarely run by hand)\nreadzip hook                             # PreToolUse handler — Claude Code calls this\n```\n\n## Configuration\n\n`~/.config/readzip/config.toml`\n\n```toml\nmin_lines = 500              # files smaller than this pass through\nmax_skeleton_tokens = 1500   # cap skeleton size\nskeleton_detail = \"medium\"   # minimal | medium | verbose\nbypass_for = []              # globs that always pass through\nforce_full_for = [\"*.md\", \"package.json\"]\n```\n\nForce a specific file to always pass through:\n\n```toml\nbypass_for = [\"src/generated/schema.rs\", \"vendor/**\"]\n```\n\n## Stats\n\nLocal-only. Always recording. No network calls, ever.\n\n```bash\nreadzip stats\n```\n\nEach intercepted Read appends one line to `~/.cache/readzip/stats.tsv` recording timestamp, hashed file path, original token estimate, and skeleton token estimate. The hashed path is a 64-bit Rust `DefaultHasher` digest, never the original path. To wipe: `rm ~/.cache/readzip/stats.tsv`.\n\n## Performance\n\nPer-`Read` overhead measured on macOS arm64:\n\n| Path | Latency |\n|---|---:|\n| Non-Read tool / scoped Read / passthrough | ~30 ms |\n| Large file intercept, **cold cache** | ~60 ms |\n| Large file intercept, **warm cache** | ~30 ms |\n\nThe ~30 ms floor is the cost of spawning a 28 MB Rust binary that links 16 tree-sitter grammars. Compared to Claude Code's LLM round-trips at 1-3 seconds, this is **~1-3% overhead per Read** — indistinguishable from noise in real sessions.\n\n## Uninstall\n\nOne-liner, symmetric with install:\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/rishiskhare/readzip/main/uninstall.sh | sh\n```\n\nManual:\n\n```bash\nreadzip uninstall              # hook + Codex hint + cache\nreadzip uninstall --purge      # also delete ~/.config/readzip/\nrm -f ~/.local/bin/readzip     # delete the binary\n```\n\n`readzip uninstall` writes `.bak` files of every settings.json it touches before editing, so you can restore with `mv ~/.claude/settings.json.readzip-bak-* ~/.claude/settings.json` if needed.\n\n## Privacy\n\n100% local. Tree-sitter parses on disk; no network calls, ever. No telemetry. Stats live at `~/.cache/readzip/stats.tsv` and never leave your machine. The `readzip hook` and CLI commands run entirely in-process under your user, with the same filesystem privileges as the agent itself.\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frishiskhare%2Freadzip","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frishiskhare%2Freadzip","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frishiskhare%2Freadzip/lists"}