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

hljs language-bash

# Run with uvx
uvx zread

# Or with pipx
pipx run zread

MCP Server

hljs language-bash

# 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:

hljs language-bash

export ZREAD_TOKEN=your-token

Usage:

hljs language-bash

# Interactive multi-turn chat
zread ai openclaw/openclaw

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

CLI Commands

hljs language-bash

# 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

hljs language-bash

# 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:

hljs language-json

{
  "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:

Visit https://zread.ai and sign in
Press F12 to open the browser console

Run:

hljs language-javascript

prompt(
  "copy token",
  JSON.parse(localStorage.getItem("CGX_AUTH_STORAGE")).state.token,
);

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):

hljs language-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.

zread

Zread - AI Repository Reading Assistant

Features

Screenshots

Quick Start

CLI Tool

MCP Server

AI Q&A

CLI Commands

Global Options

Examples

MCP Client Configuration

MCP Tools

Get a Token

Environment Variables

Configuration File

Contributing

License

Similar Packages

Tags

Original Author

Publisher