{"id":47282409,"url":"https://github.com/ejfkdev/zread","last_synced_at":"2026-04-08T05:02:29.674Z","repository":{"id":344691830,"uuid":"1182735110","full_name":"ejfkdev/zread","owner":"ejfkdev","description":"AI-powered CLI and MCP server for browsing GitHub project documentation","archived":false,"fork":false,"pushed_at":"2026-04-08T03:52:46.000Z","size":3212,"stargazers_count":10,"open_issues_count":0,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-04-08T04:21:09.726Z","etag":null,"topics":["ai","cli","code-assistant","developer-tools","documentation","knowledge-base","mcp","repository-tools"],"latest_commit_sha":null,"homepage":"https://zread.ai","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/ejfkdev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","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-03-15T22:37:16.000Z","updated_at":"2026-04-08T03:51:27.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/ejfkdev/zread","commit_stats":null,"previous_names":["ejfkdev/zread"],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/ejfkdev/zread","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ejfkdev%2Fzread","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ejfkdev%2Fzread/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ejfkdev%2Fzread/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ejfkdev%2Fzread/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ejfkdev","download_url":"https://codeload.github.com/ejfkdev/zread/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ejfkdev%2Fzread/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31540826,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-07T16:28:08.000Z","status":"online","status_checked_at":"2026-04-08T02:00:06.127Z","response_time":54,"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","cli","code-assistant","developer-tools","documentation","knowledge-base","mcp","repository-tools"],"created_at":"2026-03-16T02:10:11.567Z","updated_at":"2026-04-08T05:02:29.662Z","avatar_url":"https://github.com/ejfkdev.png","language":"Python","readme":"# Zread - AI Repository Reading Assistant\n\n[中文](README.zh.md) | English\n\n[![Python](https://img.shields.io/badge/Python-3.10%2B-blue)](https://www.python.org/)\n[![zread](https://img.shields.io/badge/Ask_Zread-_.svg?style=flat\u0026color=00b0aa\u0026labelColor=000000\u0026logo=data%3Aimage%2Fsvg%2Bxml%3Bbase64%2CPHN2ZyB3aWR0aD0iMTYiIGhlaWdodD0iMTYiIHZpZXdCb3g9IjAgMCAxNiAxNiIgZmlsbD0ibm9uZSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj4KPHBhdGggZD0iTTQuOTYxNTYgMS42MDAxSDIuMjQxNTZDMS44ODgxIDEuNjAwMSAxLjYwMTU2IDEuODg2NjQgMS42MDE1NiAyLjI0MDFWNC45NjAxQzEuNjAxNTYgNS4zMTM1NiAxLjg4ODEgNS42MDAxIDIuMjQxNTYgNS42MDAxSDQuOTYxNTZDNS4zMTUwMiA1LjYwMDEgNS42MDE1NiA1LjMxMzU2IDUuNjAxNTYgNC45NjAxVjIuMjQwMUM1LjYwMTU2IDEuODg2NjQgNS4zMTUwMiAxLjYwMDEgNC45NjE1NiAxLjYwMDFaIiBmaWxsPSIjZmZmIi8%2BCjxwYXRoIGQ9Ik00Ljk2MTU2IDEwLjM5OTlIMi4yNDE1NkMxLjg4ODEgMTAuMzk5OSAxLjYwMTU2IDEwLjY4NjQgMS42MDE1NiAxMS4wMzk5VjEzLjc1OTlDMS42MDE1NiAxNC4xMTM0IDEuODg4MSAxNC4zOTk5IDIuMjQxNTYgMTQuMzk5OUg0Ljk2MTU2QzUuMzE1MDIgMTQuMzk5OSA1LjYwMTU2IDE0LjExMzQgNS42MDE1NiAxMy43NTk5VjExLjAzOTlDNS42MDE1NiAxMC42ODY0IDUuMzE1MDIgMTAuMzk5OSA0Ljk2MTU2IDEwLjM5OTlaIiBmaWxsPSIjZmZmIi8%2BCjxwYXRoIGQ9Ik0xMy43NTg0IDEuNjAwMUgxMS4wMzg0QzEwLjY4NSAxLjYwMDEgMTAuMzk4NCAxLjg4NjY0IDEwLjM5ODQgMi4yNDAxVjQuOTYwMUMxMC4zOTg0IDUuMzEzNTYgMTAuNjg1IDUuNjAwMSAxMS4wMzg0IDUuNjAwMUgxMy43NTg0QzE0LjExMTkgNS42MDAxIDE0LjM5ODQgNS42MDE1NiAxNC4zOTg0IDQuOTYwMVYyLjI0MDFDMTQuMzk4NCAxLjg4NjY0IDE0LjExMTkgMS42MDAxIDEzLjc1ODQgMS42MDAxWiIgZmlsbD0iI2ZmZiIvPgo8cGF0aCBkPSJNNCAxMkwxMiA0TDQgMTJaIiBmaWxsPSIjZmZmIi8%2BCjxwYXRoIGQ9Ik00IDEyTDEyIDQiIHN0cm9rZT0iI2ZmZiIgc3Ryb2tlLXdpZHRoPSIxLjUiIHN0cm9rZS1saW5lY2FwPSJyb3VuZCIvPgo8L3N2Zz4K\u0026logoColor=ffffff)](https://zread.ai/ejfkdev/zread)\n[![MCP](https://img.shields.io/badge/MCP-Protocol-green)](https://modelcontextprotocol.io/)\n[![CLI](https://img.shields.io/badge/Interface-CLI-2E8B57)](https://pypi.org/project/zread/)\n[![Transport](https://img.shields.io/badge/Transport-stdio%20%7C%20http%20%7C%20sse-6A5ACD)](https://github.com/ejfkdev/zread)\n[![I18N](https://img.shields.io/badge/I18N-zh%20%7C%20en-FF8C00)](https://github.com/ejfkdev/zread)\n[![PyPI](https://img.shields.io/badge/PyPI-zread-blue)](https://pypi.org/project/zread/)\n[![Downloads](https://img.shields.io/pypi/dm/zread)](https://pypi.org/project/zread/)\n[![License](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n\nZread helps you and your AI understand codebases faster. Skip the manual source dive and ask directly. It connects to [Zread.ai](https://zread.ai), an AI-powered GitHub project documentation service.\n\n**Two roles**:\n\n- 🖥️ **CLI tool** - run directly in your terminal with minimal setup\n- 🔌 **MCP server** - integrate with AI assistants such as Claude and Cline\n\n**Highlights**:\n\n- 🔍 Browse docs, search code, and discover repositories without a token\n- 🤖 AI Q\u0026A powered by repository documentation\n- 🌐 Multiple transports: stdio, HTTP, and SSE\n- ⚡ One command to run, zero-friction startup\n\n## Features\n\n- 📖 **Read docs** - browse GitHub repository docs directly in the terminal\n- 🔍 **Search docs** - search keywords across repository documentation\n- 🌟 **Discover repos** - browse trending rankings and recommended projects\n- 📥 **Export docs** - export repository docs locally and generate `llms.txt` and `llms-full.txt` (CLI only)\n- 🤖 **AI Q\u0026A** - ask the repository AI assistant questions (requires a free account token)\n- 📄 **Read source files** - inspect source file contents directly\n- 🔌 **MCP integration** - connect seamlessly with AI assistants\n\n## Screenshots\n\n\u003ctable\u003e\n  \u003ctr\u003e\n    \u003ctd align=\"center\"\u003e\n      \u003cstrong\u003eHelp\u003c/strong\u003e\u003cbr\u003e\n      \u003ccode\u003ezread -h\u003c/code\u003e\u003cbr\u003e\u003cbr\u003e\n      \u003cimg src=\"https://raw.githubusercontent.com/ejfkdev/zread/refs/heads/main/image/help.png\" alt=\"zread help\" width=\"100%\"\u003e\n    \u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\n      \u003cstrong\u003eDocumentation Outline\u003c/strong\u003e\u003cbr\u003e\n      \u003ccode\u003ezread ls openclaw/openclaw\u003c/code\u003e\u003cbr\u003e\u003cbr\u003e\n      \u003cimg src=\"https://raw.githubusercontent.com/ejfkdev/zread/refs/heads/main/image/ls.png\" alt=\"zread ls\" width=\"100%\"\u003e\n    \u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\n      \u003cstrong\u003eRead a Doc Page\u003c/strong\u003e\u003cbr\u003e\n      \u003ccode\u003ezread cat openclaw/openclaw\u003c/code\u003e\u003cbr\u003e\u003cbr\u003e\n      \u003cimg src=\"https://raw.githubusercontent.com/ejfkdev/zread/refs/heads/main/image/cat-wiki.png\" alt=\"zread cat wiki\" width=\"100%\"\u003e\n    \u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\n      \u003cstrong\u003eRead a GitHub File\u003c/strong\u003e\u003cbr\u003e\n      \u003ccode\u003ezread cat facebook/react README.md\u003c/code\u003e\u003cbr\u003e\u003cbr\u003e\n      \u003cimg src=\"https://raw.githubusercontent.com/ejfkdev/zread/refs/heads/main/image/cat-github.png\" alt=\"zread cat github\" width=\"100%\"\u003e\n    \u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd align=\"center\"\u003e\n      \u003cstrong\u003eSearch Repositories\u003c/strong\u003e\u003cbr\u003e\n      \u003ccode\u003ezread find ai sandbox\u003c/code\u003e\u003cbr\u003e\u003cbr\u003e\n      \u003cimg src=\"https://raw.githubusercontent.com/ejfkdev/zread/refs/heads/main/image/find-repo.png\" alt=\"zread find repo\" width=\"100%\"\u003e\n    \u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\n      \u003cstrong\u003eSearch Documentation\u003c/strong\u003e\u003cbr\u003e\n      \u003ccode\u003ezread find openclaw/openclaw gateway\u003c/code\u003e\u003cbr\u003e\u003cbr\u003e\n      \u003cimg src=\"https://raw.githubusercontent.com/ejfkdev/zread/refs/heads/main/image/find-wiki.png\" alt=\"zread find wiki\" width=\"100%\"\u003e\n    \u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\n      \u003cstrong\u003eTrending Repos\u003c/strong\u003e\u003cbr\u003e\n      \u003ccode\u003ezread top\u003c/code\u003e\u003cbr\u003e\u003cbr\u003e\n      \u003cimg src=\"https://raw.githubusercontent.com/ejfkdev/zread/refs/heads/main/image/top.png\" alt=\"zread top\" width=\"100%\"\u003e\n    \u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\n      \u003cstrong\u003eRandom Recommendation\u003c/strong\u003e\u003cbr\u003e\n      \u003ccode\u003ezread rand agent-skills\u003c/code\u003e\u003cbr\u003e\u003cbr\u003e\n      \u003cimg src=\"https://raw.githubusercontent.com/ejfkdev/zread/refs/heads/main/image/rand.png\" alt=\"zread rand\" width=\"100%\"\u003e\n    \u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd align=\"center\"\u003e\n      \u003cstrong\u003eSingle-turn AI Q\u0026A\u003c/strong\u003e\u003cbr\u003e\n      \u003ccode\u003ezread ai openclaw/openclaw \"introduce this project briefly\"\u003c/code\u003e\u003cbr\u003e\u003cbr\u003e\n      \u003cimg src=\"https://raw.githubusercontent.com/ejfkdev/zread/refs/heads/main/image/ai-ask.png\" alt=\"zread ai ask\" width=\"100%\"\u003e\n    \u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\n      \u003cstrong\u003eInteractive AI Chat\u003c/strong\u003e\u003cbr\u003e\n      \u003ccode\u003ezread ai openclaw/openclaw\u003c/code\u003e\u003cbr\u003e\u003cbr\u003e\n      \u003cimg src=\"https://raw.githubusercontent.com/ejfkdev/zread/refs/heads/main/image/ai-chat.png\" alt=\"zread ai chat\" width=\"100%\"\u003e\n    \u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\n      \u003cstrong\u003eExport Repository Docs\u003c/strong\u003e\u003cbr\u003e\n      \u003ccode\u003ezread cp openclaw/openclaw\u003c/code\u003e\u003cbr\u003e\u003cbr\u003e\n      \u003cimg src=\"https://raw.githubusercontent.com/ejfkdev/zread/refs/heads/main/image/cp.png\" alt=\"zread cp\" width=\"100%\"\u003e\n    \u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\n      \u003cstrong\u003eMCP HTTP Service\u003c/strong\u003e\u003cbr\u003e\n      \u003ccode\u003ezread mcp http :8080\u003c/code\u003e\u003cbr\u003e\u003cbr\u003e\n      \u003cimg src=\"https://raw.githubusercontent.com/ejfkdev/zread/refs/heads/main/image/mcp-http.png\" alt=\"zread mcp http\" width=\"100%\"\u003e\n    \u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\n## Quick Start\n\n### CLI Tool\n\n```bash\n# Run with uvx\nuvx zread\n\n# Or with pipx\npipx run zread\n```\n\n### MCP Server\n\n```bash\n# stdio mode\nuvx zread mcp\n\n# HTTP mode\nuvx zread mcp http\n```\n\n### AI Q\u0026A\n\nAI Q\u0026A requires a free token from your [Zread.ai](https://zread.ai) account.\n\n**Set your token:**\n\n```bash\nexport ZREAD_TOKEN=your-token\n```\n\n**Usage:**\n\n```bash\n# Interactive multi-turn chat\nzread ai openclaw/openclaw\n\n# Single question\nzread ai facebook/react \"How is this project structured?\"\n```\n\n## CLI Commands\n\n```bash\n# Start the MCP server\nzread mcp [stdio|http|sse] [address] [options]\n\n# Show the documentation outline\nzread ls \u003crepo\u003e [-l zh|en] [-j] [-p]\n\n# Read a documentation page or a source file\nzread cat \u003crepo\u003e [slug_or_path] [-l zh|en] [-j] [-p]\n#\n# Automatic argument detection:\n# - If the first argument is only repo and the second is a slug/index (for example 1-overview, 1), it reads a zread doc page\n# - Other forms (for example README.md, owner/repo/README.md#L1-10, github.com/owner/repo/README.md#L1-10) read a GitHub file\n\n# Search\nzread find \u003cquery\u003e                        # Search GitHub repositories\nzread find \u003crepo\u003e \u003cquery\u003e                 # Search within a repository's docs\n\n# Discover recommended repositories\nzread rand [topic] [-l zh|en] [-j] [-p]\n\n# Show trending repositories\nzread top [weeks] [-l zh|en] [-j] [-p]\n\n# Show repository status and metadata\nzread stat \u003crepo\u003e [-l zh|en] [-j] [-p]\n\n# Ask the repository AI (requires a free account token)\nzread ai \u003crepo\u003e [question] [-l zh|en] [-t token] [-p] [-j] [-m model]\n\n# Export repository docs locally and generate llms.txt / llms-full.txt\nzread cp \u003crepo\u003e [output_dir] [-l zh|en] [-c concurrency]\n```\n\n### Global Options\n\nThe CLI supports plain text and JSON output and works well in pipelines:\n\n| Option               | Description                                                            |\n| -------------------- | ---------------------------------------------------------------------- |\n| `-l, --lang {zh,en}` | Language priority: `--lang` \u003e `ZREAD_LANG` \u003e system locale, default `en`. |\n| `-j, --json`         | Output as JSON                                                         |\n| `-p, --plain`        | Output plain text                                                      |\n| `-t, --token`        | ZREAD_TOKEN                                                            |\n| `-h, --help`         | Show help                                                              |\n| `-v, --version`      | Show version                                                           |\n\n### Examples\n\n```bash\n# MCP server\nuvx zread mcp                          # stdio mode (default)\nuvx zread mcp http                     # HTTP mode\nuvx zread mcp http :8080               # Custom port\nuvx zread mcp http 0.0.0.0:3000/custom # Custom address and path\n\n# Docs\nuvx zread ls golang/go\nuvx zread cat vuejs/vue\nuvx zread cat vuejs/vue 1\nuvx zread cat vuejs/vue 1-overview\nuvx zread cat golang/go README.md\nuvx zread cat python/cpython Lib/http/client.py\nuvx zread cat github.com/facebook/react/README.md#L1-10\nuvx zread cat facebook/react/README.md#L1-10\nuvx zread cat facebook/react README.md 5 10\nuvx zread cat facebook/react README.md 5-10\nuvx zread cat facebook/react README.md 5~\nuvx zread cat facebook/react/README.md 5:\nuvx zread find facebook/react hooks\n\n# Discovery\nuvx zread top\nuvx zread top 4\nuvx zread rand python\nuvx zread rand awesome-list\n\n# Repository info\nuvx zread stat torvalds/linux\n\n# AI Q\u0026A\nuvx zread ai golang/go \"How do I choose between channels and mutexes?\" -t your-token\nuvx zread ai python/cpython --model claude-sonnet-4.5 -t your-token\nuvx zread ai rust-lang/rust\n\n# Export docs\nuvx zread cp golang/go\nuvx zread cp python/cpython -l zh\nuvx zread cp vuejs/vue -c 20\n```\n\n## MCP Client Configuration\n\nAdd the following configuration to any MCP-compatible client:\n\n```json\n{\n  \"mcpServers\": {\n    \"zread\": {\n      \"command\": \"uvx\",\n      \"args\": [\"--env\", \"ZREAD_TOKEN=your-token\", \"zread\", \"mcp\"]\n    }\n  }\n}\n```\n\n## MCP Tools\n\n| Tool              | Description                                                                 |\n| ----------------- | --------------------------------------------------------------------------- |\n| `read_doc`        | Get the content of a specific documentation page                            |\n| `search_wiki`     | Search keywords in repository documentation                                 |\n| `get_doc_outline` | Get the repository documentation outline                                    |\n| `discover_repo`   | Discover a recommended repository at random                                 |\n| `get_trending`    | Get trending repository rankings                                            |\n| `get_repo_info`   | Get repository information and indexing status                              |\n| `read_source_file`| Read source code file contents                                              |\n| `ask_ai`          | Ask the repository AI a question (token required), supports `glm-4.7` and `claude-sonnet-4.5` |\n\n## Get a Token\n\nAI Q\u0026A requires a free JWT token from your Zread.ai account:\n\n1. Visit https://zread.ai and sign in\n2. Press F12 to open the browser console\n3. Run:\n   ```javascript\n   prompt(\n     \"copy token\",\n     JSON.parse(localStorage.getItem(\"CGX_AUTH_STORAGE\")).state.token,\n   );\n   ```\n4. Copy the token from the popup dialog\n\n## Environment Variables\n\n| Variable       | Description                                                        |\n| -------------- | ------------------------------------------------------------------ |\n| `ZREAD_TOKEN`  | Free JWT token from your zread.ai account, only required for AI Q\u0026A |\n| `ZREAD_LANG`   | Default language (`zh` / `en`), lower priority than `--lang` and higher than system locale |\n\n## Configuration File\n\nYou can also configure zread using a config file. The priority is: **CLI arguments \u003e Environment variables \u003e Config file**.\n\n**Config file locations:**\n- macOS: `~/.config/zread/zread.toml`\n- Linux: `$XDG_CONFIG_HOME/zread/zread.toml` (if set) or `~/.config/zread/zread.toml`\n- Windows: `%APPDATA%\\zread\\zread.toml`\n\n**Config file format (TOML):**\n\n```toml\n[zread]\ntoken = \"your-token-here\"\nlang = \"zh\"  # optional, defaults to \"zh\"\n```\n\n## Contributing\n\nContributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for details.\n\n## License\n\nMIT License. See [LICENSE](LICENSE) for details.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fejfkdev%2Fzread","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fejfkdev%2Fzread","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fejfkdev%2Fzread/lists"}