readthrough
Busy repos have fifty-plus open pull requests. I wanted two things from a queue like that: a picture of where the work is landing in the architecture, and a way to review PRs that leaves me actually understanding them, instead of skimming a diff and clicking approve.
readthrough does both, for repos on GitHub, GitLab, Forgejo (Codeberg), or Azure DevOps. It pulls the open PRs (the hundred most recently active by default; limit raises it) and places each on the repo's architecture (its layers and components), marking which ones come from outside contributors and which have CI trouble. It packs the reviewable ones into hour-long sessions grouped by component, then gives each PR a study brief.
From there you can go two ways. A button on each PR starts a deep-review session in a terminal, in the GitHub Copilot CLI or Claude Code, where you predict what the PR does, answer questions about it, explain it back, and list your concerns before the agent shows you its own. Or you study it right in the dashboard: an assistant quizzes you on the change one question at a time and keeps everything you got right and wrong in an append-only study log that becomes part of the brief. Given a model (GitHub Copilot through the Copilot SDK, or Claude or GPT through their own APIs, including Azure OpenAI), the assistant reads the code and grades your answers; without one, a rules-based assistant asks the questions the repo's profile already carries and never pretends to grade.
A repo has to be onboarded first
The map is only as good as readthrough's idea of the architecture, so before it lays out a repo you check that idea with it. Onboarding (in the browser at /setup, or readthrough onboard) drafts an architecture profile from the code, CODEOWNERS, the docs, and where recent PRs actually changed things, measures it against those PRs, and won't accept it until it covers them. A model can write the draft for you by reading the repo. Repos can ship their own profile as readthrough.toml (in .github/, .gitlab/, or the root), and a team can keep a directory of profiles for repos that can't.
Quick start
You need Python 3.11 or newer, uv, and, for GitHub repos, the GitHub CLI signed in (gh auth login). For deep reviews, the Copilot CLI or Claude Code signed in; for the Study tab's model assistant, the [study] extra (GitHub Copilot) or an API key for Claude or OpenAI.
uv tool install "readthrough[study]" # from PyPI; drop [study] to skip the Copilot SDK
readthrough onboard microsoft/vscode --accept # map the repo's architecture (edit the draft first if you like)
readthrough build --open # fetch the PRs and open the dashboard
Repos elsewhere take a --forge: readthrough onboard --forge forgejo forgejo/forgejo, --forge gitlab gitlab-org/cli, or --forge ado organization/project/repository. Those are read through the platform's REST API, with a token from its own CLI (glab, az) or an environment variable when there is one, and anonymously otherwise, which is enough for public repos.
That gives you a static dashboard you rebuild when you want. For one that stays fresh, run the live server (readthrough serve, or readthrough install server to start it at logon on Windows) and open http://127.0.0.1:8765/; with nothing onboarded yet it walks you through onboarding, with a model drafting the profile if you like. readthrough install skill teaches the review agents the deep-review routine, and readthrough doctor tells you what's missing.
Docs
- Using readthrough: onboarding, the dashboard, deep reviews, studying, keeping it fresh, configuration, and troubleshooting.
- Writing a profile: how to describe a repo's architecture well, and how to share it.
- Maintaining readthrough: the checks, error handling, logging, settings, plugins, and the pages' structure.
- Working on readthrough: the exact commands and the conventions that aren't obvious.
- Examples: runnable scripts, including one that needs nothing but the standard library.
- Changelog.
How it's put together
One package, src/readthrough, with no runtime dependencies beyond the standard library (and the gh CLI for GitHub repos); the [study] extra adds the GitHub Copilot SDK (one of the model runtimes the study assistant can run on; the Anthropic and OpenAI ones need only a key).
cli.py the commands; every failure ends in one line or an error id
config.py config.toml: repos, machine-wide choices, validated with did-you-mean errors
tuning.py operational numbers, typed and ranged; defaults.toml documents them
limits.py safety limits that only change by a deliberate commit
profile.py architecture profiles, and where a repo's comes from (a registry of sources)
onboard.py drafting a profile from the repo and measuring it against recent PRs
onboard_model.py the same, with a model reading the repo (on the configured runtime)
model.py the pull request as the analysis sees it, whichever forge it came from
forges/ a registry of forge adapters: github (gh), gitlab, forgejo, azure_devops (REST); the diff cache
faults.py how outside calls fail, classified from a CLI's stderr or an HTTP status
process.py running programs: UTF-8, timeouts, secrets that never reach a log
build.py one build: fetch, analyze, write data.json, the dashboard, and the briefs
analyze.py lanes, signals, line heuristics, overlaps, and the burn-down plan
ci.py which checks are required, failing, or also failing on main
brief.py the Markdown brief a reviewer reads before the diff
review.py deep-review sessions, worktrees, and the index linking agent sessions to PRs
agents.py a registry of review agents: copilot (the Copilot CLI) and claude (Claude Code)
study.py the append-only study log and its rendering into the brief
engine.py the Study tab's loop: records the learner's side, runs the assistant
assistants.py a registry of study assistants: the model one (reads code, grades) and rules (no model)
runtimes/ a registry of model runtimes the assistant runs on: copilot (the SDK), anthropic, openai
usage.py the usage ledger: every model call, in the provider's own units, and who paid
terminals.py a registry of terminal launchers for review sessions
registry.py the generic plugin registry with validated per-plugin options
serve.py the live server: refreshes, pushes changes to open pages, watches the config
web_setup.py the API behind the browser's onboarding and settings page
system.py the readthrough:// URL handler and the Windows scheduled tasks
logs.py the logger: build context on every line, error ids, JSON format
assets/web/ the pages as separate HTML, CSS, and JS, inlined into one served file
assets/vendor/ Cytoscape, marked, DOMPurify, and Lucide icons, with their licenses
To extend it: a new forge, a new place profiles can come from, a new review agent, a new terminal, or a new study assistant is a registry entry with an options dataclass, described in Maintaining readthrough. Everything repo-specific is data in a profile, described in Writing a profile.
Development
git clone https://github.com/spencrr/readthrough.git
cd readthrough
uv sync
git config core.hooksPath .githooks # once: run the checks before every commit
uv run python scripts/check.py # lint, format, types, and tests with the coverage floor
The same gate runs in CI on Linux, macOS, and Windows for every supported Python. The browser tests use an installed Edge or Chrome; locally they skip without one, on CI they fail. See SECURITY.md for what the tool trusts and how to report a vulnerability.
Metadata
Release files for readthrough 0.4.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| readthrough-0.4.0.tar.gz | 802.7 kB | With provenance | Details for readthrough-0.4.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| readthrough-0.4.0-py3-none-any.whl | Python 3 | none | any | Details for readthrough-0.4.0-py3-none-any.whl |
Total release size: 1.3 MB
Release files / readthrough-0.4.0.tar.gz
| Download URL | readthrough-0.4.0.tar.gz |
|---|---|
| Size | 802.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
561f2b5fe632e5a65947e06d42a074dde235181f9e30137ca6fc9db614a7c9ce
|
|
BLAKE2b-256 checksum How to use checksums |
2c26454a60960fc1e93ce73944fb4d2bf380e22b1bf9fc3fa39c249173b25879
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 30, 2026.
Transparency logRelease files / readthrough-0.4.0-py3-none-any.whl
| Download URL | readthrough-0.4.0-py3-none-any.whl |
|---|---|
| Size | 514.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
361781c488b0dee9d99a765becd7c1c31597c01fb4ded11414bdc6c41239963a
|
|
BLAKE2b-256 checksum How to use checksums |
f63705c087e5c328412e0dbe55842d494d0853021b6140db824593f220593b21
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 30, 2026.
Transparency logSecurity for readthrough 0.4.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for readthrough-0.4.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 30, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.