yread 0.1.0

Local lightweight repo-to-wiki generator inspired by zread.

yread

Turn a local source repository into a structured Markdown wiki.

yread is a lightweight, installable Python CLI inspired by zread. It uses a two-phase LLM workflow to inspect a local repository, plan a wiki outline, and write one Markdown page per topic.

The y is intentional: it is zread's alphabet neighbor, and it also hints at "yet another" small local implementation.

Why

Zread popularized the idea of generating a developer guide from a GitHub repository. yread keeps the same core idea, but narrows the scope:

• Local repositories only
• Direct OpenAI-compatible provider calls
• A small, readable Python implementation
• Markdown output that can be checked into notes, opened in Obsidian, or served locally

This is not a hosted wiki platform. It is a local code-reading tool.

How It Works

yread runs two LLM-driven phases:

Phase 1: Catalog Agent
  Inspect the repository
  Plan sections, groups, and topics
  Attach relevant source paths to each topic

Phase 2: Page Agents
  Start one fresh conversation per topic
  Inspect the relevant source files
  Write Markdown wrapped as a wiki page

Agents only receive three read-only tools:

Tool	Purpose
get_dir_structure	Show a filtered directory tree
view_file_in_detail	Read source files by line range
run_bash	Run conservative read-only commands; disable with ENABLE_SHELL=0

Install and Run

From a checkout, generate defaults to the current directory:

cd /path/to/repo
uv run yread generate          # or: uv run yread generate /path/to/repo

Install as a uv tool:

uv tool install .
cd /path/to/repo && yread generate

Output defaults to:

<repo>/.yread/wiki/
├── current
└── versions/<YYYY-MM-DD-HHMMSS>/
    ├── <slug>.md
    ├── wiki.json
    ├── manifest.json
    └── SUMMARY.md

Provider Configuration

yread can use minimax-cn, deepseek, or any OpenAI Chat Completions compatible endpoint.

For a generic OpenAI-compatible provider:

cp .env.yread.example .env.yread
$EDITOR .env.yread
uv run yread generate /path/to/repo --env-file .env.yread

All tunables (provider, model, language, concurrency, output) live in config rather than on the generate command, keeping the command surface lean.

Persistent config lives at:

~/.yread/config.env

Set it up interactively:

yread config init

Or manage individual keys:

yread config path
yread config set PROVIDER openai-compatible
yread config set BASE_URL https://api.example.com/v1
yread config set API_KEY sk-...
yread config set MODEL your-model
yread config set DOC_LANG en
yread config show

Config precedence is:

process environment > --env-file > ~/.yread/config.env > defaults

Key	Default	Description
PROVIDER	minimax-cn	minimax-cn, deepseek, or openai-compatible
BASE_URL	auto-resolved	OpenAI-compatible /v1 endpoint
API_KEY	auto-resolved	Provider API key
MODEL	provider default	Model name
DOC_LANG	en	Documentation language code, e.g. zh, en
MAX_STEPS	24	Max tool-call rounds per agent
MAX_TOPICS	30	Catalog topic cap
CONCURRENCY	1	Parallel page agents
ENABLE_SHELL	1	Expose run_bash to agents
OUTPUT_DIR	<repo>/.yread/wiki	Default export directory

For minimax-cn and deepseek, missing credentials are resolved from ~/.pi/agent/models.json and ~/.pi/agent/auth.json when available.

Export to Obsidian

Set OUTPUT_DIR to a directory inside your vault:

yread config set OUTPUT_DIR "/path/to/Obsidian Vault/Code Wikis/yread"
yread generate /path/to/repo

Resume and Regenerate

If a previous run was interrupted or left failed pages, a plain yread generate auto-detects the incomplete version and resumes it instead of starting a new one (use --force to start fresh). A build that produces no pages never replaces a previously-good wiki.

Explicitly resume the current version, regenerating only missing, failed, or source-affected pages:

yread generate /path/to/repo --resume

Regenerate one page by slug, title, or Markdown filename:

yread generate /path/to/repo --page 1-overview

Disable shell access for agents (config-only):

yread config set ENABLE_SHELL 0

Browse Locally

The source repository is recorded in wiki.json at generation time, so source citations resolve automatically — from inside the repo, just run:

yread browse                       # serves ./.yread/wiki

Or point at a wiki explicitly; --repo overrides the recorded source root:

uv run yread browse /path/to/repo/.yread/wiki --host localhost --port 8000

Codex Skill

A companion Codex skill is available at skills/yread/SKILL.md.

Install it for local discovery:

cp -R skills/yread "${CODEX_HOME:-$HOME/.codex}/skills/"

Example Output

See examples/sample-wiki for a static sample of the output layout. It demonstrates wiki.json, manifest.json, and Markdown page files; it is not a real model-generated run.

Development

uv run --dev pytest -q
uv build

Privacy

yread runs locally, but source snippets read by its tools are sent to the configured LLM provider. Do not run it on private or sensitive repositories unless that provider is acceptable for the code.

The file-reading tools block common secret files such as .env, private keys, and credential files. run_bash uses an allowlist and does not invoke a shell.

Design Notes

• No hosted service: output is local Markdown.
• No AST parser: repository understanding is LLM-driven.
• No symbolic incremental engine: resume uses a file-level manifest plus per-page associated paths.
• Standard package layout: src/yread/core.py for generation, src/yread/cli.py for CLI/config, and src/yread/viewer.py for the local browser.

Related Projects

• zread.ai
• ZreadAI/zread_cli
• bb-boy680/open-zread
• ejfkdev/zread

License

MIT