FazBrowse GitHub Viewer | Trending |
URL:
| Home
Tools: [Download Repo ZIP]   [Original HTTPS Page]

ejfkdev/zread: AI-powered CLI and MCP server for browsing GitHub project documentation (unofficial tool) · GitHub

/ zread Public
BranchesTags

Repository files navigation

Zread - AI Repository Reading Assistant

中文 | English

Zread helps you and your AI understand codebases faster. Skip the manual source dive and ask directly. It connects to Zread.ai, an AI-powered GitHub project documentation service.

Two roles:

  • 🖥️ CLI tool - run directly in your terminal with minimal setup
  • 🔌 MCP server - integrate with AI assistants such as Claude and Cline

Highlights:

  • 🔍 Browse docs, search code, and discover repositories without a token
  • 🤖 AI Q&A powered by repository documentation
  • 🌐 Multiple transports: stdio, HTTP, and SSE
  • ⚡ One command to run, zero-friction startup

Features

  • 📖 Read docs - browse GitHub repository docs directly in the terminal
  • 🔍 Search docs - search keywords across repository documentation
  • 🌟 Discover repos - browse trending rankings and recommended projects
  • 📥 Export docs - export repository docs locally and generate llms.txt and llms-full.txt (CLI only)
  • 🤖 AI Q&A - ask the repository AI assistant questions (requires a free account token)
  • 📄 Read source files - inspect source file contents directly
  • 🔌 MCP integration - connect seamlessly with AI assistants

Screenshots

Help
zread -h

 Documentation Outline
zread ls openclaw/openclaw

 Read a Doc Page
zread cat openclaw/openclaw

 Read a GitHub File
zread cat facebook/react README.md
Search Repositories
zread find ai sandbox

 Search Documentation
zread find openclaw/openclaw gateway

 Trending Repos
zread top

 Random Recommendation
zread rand agent-skills
Single-turn AI Q&A
zread ai openclaw/openclaw "introduce this project briefly"

 Interactive AI Chat
zread ai openclaw/openclaw

 Export Repository Docs
zread cp openclaw/openclaw

 MCP HTTP Service
zread mcp http :8080

Quick Start

CLI Tool

# Run with uvx
uvx zread

# Or with pipx
pipx run zread

MCP Server

# stdio mode
uvx zread mcp

# HTTP mode
uvx zread mcp http

AI Q&A

AI Q&A requires a free token from your Zread.ai account.

Set your token:

export ZREAD_TOKEN=your-token

Usage:

# Interactive multi-turn chat
zread ai openclaw/openclaw

# Single question
zread ai facebook/react "How is this project structured?"

CLI Commands

# Start the MCP server
zread mcp [stdio|http|sse] [address] [options]

# Show the documentation outline
zread ls <repo> [-l zh|en] [-j] [-p]

# Read a documentation page or a source file
zread cat <repo> [slug_or_path] [-l zh|en] [-j] [-p]
#
# Automatic argument detection:
# - 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
# - Other forms (for example README.md, owner/repo/README.md#L1-10, github.com/owner/repo/README.md#L1-10) read a GitHub file

# Search
zread find <query>                        # Search GitHub repositories
zread find <repo> <query>                 # Search within a repository's docs

# Discover recommended repositories
zread rand [topic] [-l zh|en] [-j] [-p]

# Show trending repositories
zread top [weeks] [-l zh|en] [-j] [-p]

# Show repository status and metadata (silently submits unindexed repos and refreshes stale docs)
zread stat <repo> [-l zh|en] [-j] [-p]

# Ask the repository AI (requires a free account token)
zread ai <repo> [question] [-l zh|en] [-t token] [-p] [-j] [-m model]

# Export repository docs locally and generate llms.txt / llms-full.txt
zread cp <repo> [output_dir] [-l zh|en] [-c concurrency]

Global Options

The CLI supports plain text and JSON output and works well in pipelines:

Option Description
-l, --lang {zh,en} Language priority: --lang > ZREAD_LANG > system locale, default en.
-j, --json Output as JSON
-p, --plain Output plain text
-t, --token ZREAD_TOKEN
-h, --help Show help
-v, --version Show version

Examples

# MCP server
uvx zread mcp                          # stdio mode (default)
uvx zread mcp http                     # HTTP mode
uvx zread mcp http :8080               # Custom port
uvx zread mcp http 0.0.0.0:3000/custom # Custom address and path

# Docs
uvx zread ls golang/go
uvx zread cat vuejs/vue
uvx zread cat vuejs/vue 1
uvx zread cat vuejs/vue 1-overview
uvx zread cat golang/go README.md
uvx zread cat python/cpython Lib/http/client.py
uvx zread cat github.com/facebook/react/README.md#L1-10
uvx zread cat facebook/react/README.md#L1-10
uvx zread cat facebook/react README.md 5 10
uvx zread cat facebook/react README.md 5-10
uvx zread cat facebook/react README.md 5~
uvx zread cat facebook/react/README.md 5:
uvx zread find facebook/react hooks

# Discovery
uvx zread top
uvx zread top 4
uvx zread rand python
uvx zread rand awesome-list

# Repository info
uvx zread stat torvalds/linux

# AI Q&A
uvx zread ai golang/go "How do I choose between channels and mutexes?" -t your-token
uvx zread ai python/cpython --model claude-sonnet-4.6 -t your-token
uvx zread ai rust-lang/rust

# Export docs
uvx zread cp golang/go
uvx zread cp python/cpython -l zh
uvx zread cp vuejs/vue -c 20

MCP Client Configuration

Add the following configuration to any MCP-compatible client:

{
  "mcpServers": {
    "zread": {
      "command": "uvx",
      "args": ["--env", "ZREAD_TOKEN=your-token", "zread", "mcp"]
    }
  }
}

MCP Tools

Tool Description
read_doc Get the content of a specific documentation page
search_wiki Search keywords in repository documentation
get_doc_outline Get the repository documentation outline
discover_repo Discover a recommended repository at random
get_trending Get trending repository rankings
get_repo_info Get repository information and indexing status
read_source_file Read source code file contents
ask_ai Ask the repository AI a question (token required), supports glm-5.1 and claude-sonnet-4.6

Get a Token

AI Q&A requires a free JWT token from your Zread.ai account:

  1. Visit https://zread.ai and sign in
  2. Press F12 to open the browser console
  3. Run: 
    prompt(
  "copy token",
  JSON.parse(localStorage.getItem("CGX_AUTH_STORAGE")).state.token,
);
  4. Copy the token from the popup dialog

Environment Variables

Variable Description
ZREAD_TOKEN Free JWT token from your zread.ai account, only required for AI Q&A
ZREAD_LANG Default language (zh / en), lower priority than --lang and higher than system locale
ZREAD_MODEL Default AI model (glm-5.1 / claude-sonnet-4.6), lower priority than --model

Configuration File

You can also configure zread using a config file. The priority is: CLI arguments > Environment variables > Config file.

Config file locations:

  • macOS: ~/.config/zread/zread.toml
  • Linux: $XDG_CONFIG_HOME/zread/zread.toml (if set) or ~/.config/zread/zread.toml
  • Windows: %APPDATA%\zread\zread.toml

Config file format (TOML):

[zread]
token = "your-token-here"
lang = "zh"  # optional, defaults to "zh"
model = "glm-5.1"  # optional, defaults to "glm-5.1", also supports "claude-sonnet-4.6"

Contributing

Contributions are welcome. See CONTRIBUTING.md for details.

License

MIT License. See LICENSE for details.

About

AI-powered CLI and MCP server for browsing GitHub project documentation (unofficial tool)

zread.ai

Topics

aiclicode-assistantdeveloper-toolsdocumentationknowledge-basemcprepository-tools

Resources

Readme
MIT license

Contributing

Contributing
Activity

Stars

46 stars

Watchers

1 watching

Forks

7 forks
Report repository

Releases

Packages

Used by

Contributors

Languages

Back | FazBrowse Home | New Git URL