SparseRead

Agents are good at reasoning, but their default reading action is often still:

read everything -> put everything in context -> start reasoning

That is expensive for long reports, PDFs, workspaces, logs, spreadsheets, and
multi-file audits. SparseRead adds a small control plane in front of native
agent tools:

artifact -> Read Gate -> Reader Backend -> EvidencePack -> refine / verify / stop

The agent still decides what it needs. SparseRead makes the request bounded,
source-anchored, and reversible when native access is the better path.

Results

The current paper evaluation covers 125 tasks, five workload scenarios, and six
frontier models: Claude Opus 5, Qwen3.6-Plus, DeepSeek-V4-Flash,
DeepSeek-V4-Pro, GLM-5.1, and Kimi-K2.5.

The gain is not tied to one model: the evaluation includes strong reasoning
models as well as general-purpose frontier models, and the paper reports
benefits for all six models across the full matrix. See the
paper for definitions, baselines, and the
complete results.

Cross-framework results

The paper's end-to-end portability table evaluates the same protocol and
reader backends in three frameworks:

Claude Code is the fourth supported integration in the single-repository
release. It uses MCP plus PreToolUse/PostToolUse session hooks rather than
an npm plugin. The local Claude Code validation report is available at
benchmarks/qwenclawbench/claude_final_aggregate_20260805.md;
it is not part of the three-framework table in the paper.

Install

The current release baseline is a source-install release. It builds a managed
runtime for the selected framework, so the installed integration does not
import from this checkout at runtime.

Requirements: Python 3.11+, uv, Node.js 22+
for OpenCode/OpenClaw, and the target agent CLI.

The installer validates the selected Python before changing a workspace. If the
shell's default Python is too old, use the documented uv run form above or
pass --python /path/to/python3.12; PDF/XLSX readers are installed by default,
and --reader-extras none is available for text-only installations.

git clone https://github.com/Zedong-Liu/SparseReading.git
cd SparseReading

# Verify the core, adapters, bridge protocol, and release fixture first.
PYTHONPATH="packages/sparseread-core/src:integrations/nanobot/python/src:integrations/opencode/python/src:integrations/openclaw/python/src:integrations/claude/python/src" \
  uv run --project . --extra test pytest tests/test_release_fixtures.py -q

Choose one integration:

# OpenCode: install into an existing workspace
uv run --project . python scripts/install_sparseread.py \
  --platform opencode \
  --opencode-workspace /path/to/your/project \
  --doctor

# OpenClaw: install into the current OpenClaw profile
uv run --project . python scripts/install_sparseread.py \
  --platform openclaw \
  --doctor

# Claude Code: install MCP and session hooks into a workspace
uv run --project . python scripts/install_sparseread.py \
  --platform claude \
  --claude-workspace /path/to/your/project \
  --doctor

For NanoBot, install sparseread-core and sparseread-nanobot as Python
dependencies; see the NanoBot adapter guide.
The full installation and platform matrix is in
docs/sparseread_installation.md (Chinese)
and the shorter English installation guide.

After installation, users do not need to call sro_preview or write a
HintSpec by hand. Ask the agent to use SparseRead for a large artifact, for
example:

Use SparseRead to inspect this large report. Extract only the evidence needed
to answer the question, then stop reading once the evidence is sufficient.

Quick test

The repository includes a small long-document fixture:

opencode run "Use SparseRead to inspect tests/fixtures/quick_test/incident-report.md and report ROOT_CAUSE, MITIGATION_OWNER, and FINAL_DEADLINE."

The same request works in an OpenClaw, Claude Code, or NanoBot session after the
corresponding adapter is installed.

How it works

• Read Gate — selects auto, native, or advisory behavior from artifact
  shape and task economics. Low-benefit computation and small-file work stays
  on native tools.
• Reader Backends — provide typed, bounded views for text/PDF, structured
  data, and multi-file collections.
• EvidencePack — returns compact evidence with source anchors, unresolved
  requirements, and a suggested next action.
• Stateful protocol — supports preview, targeted reading, refinement,
  verification, explicit raw fallback, and stopping.

The public production entrypoints are framework-facing tools; users normally
do not need to invoke them directly:

sro_preview(path) -> bounded preview + FileCard
sro_read(target, mode, hint) -> EvidencePack
sro_raw(raw_ref) -> explicit raw fallback

Repository layout

packages/sparseread-core/       framework-neutral core and tests
integrations/<framework>/       NanoBot, OpenCode, OpenClaw, Claude Code adapters
scripts/install_sparseread.py   source installer and doctor
tests/                          release, bridge, gate, and installer tests
benchmarks/                     reproducibility runners and selected fixtures
docs/                           installation, architecture, and design notes

The core and adapters are intentionally separate. A framework adapter owns only
the host-specific bridge, lifecycle hooks, and installation surface; it does
not fork the reading protocol.

Development

Run the core suite independently:

uv run --project packages/sparseread-core --with pytest --with pytest-asyncio \
  pytest packages/sparseread-core/tests -q

Run the full release suite:

PYTHONPATH="packages/sparseread-core/src:integrations/nanobot/python/src:integrations/opencode/python/src:integrations/openclaw/python/src:integrations/claude/python/src" \
  uv run --project . --extra test pytest -q

Build the Python distributions and JavaScript plugins through the same CI path:

npm --prefix integrations/opencode/plugin ci
npm --prefix integrations/opencode/plugin run build
npm --prefix integrations/openclaw/plugin ci
npm --prefix integrations/openclaw/plugin run build

Benchmark runners and historical result files are kept for reproducibility;
they are not imported by any release package. See the
release architecture before adding a new
integration.

Release scope and limitations

• The current baseline is v0.1.1 and is installable from source.
• PyPI, npm, and official framework-marketplace publishing are not wired yet;
  the source installer is the supported distribution path today.
• Claude Code is supported through MCP and session hooks. Its Windows MCP path
  still needs separate verification in environments where the host CLI or
  permissions differ.
• SparseRead is selective by design. Native access remains the right choice for
  small files, exact full-table computation, and other low-sparsity tasks.

Contributing

Please read CONTRIBUTING.md before opening a pull request.
Bug reports and focused integration feedback are welcome.

Citation

@article{liu2026readless,
  title   = {Read Less, Solve More: Token-Efficient Sparse Reading for AI Agents},
  author  = {Liu, Zedong and Wu, Jiaan and Ma, Xinyang and Xu, Le and Wang, Kai and Hu, Yuanchao and Tao, Dingwen and Tan, Guangming},
  journal = {arXiv preprint arXiv:2608.22237},
  year    = {2026}
}

License

SparseRead is released under the MIT License.