junio 0.1.0a1

Conversational CLI agent that composes academic literature reviews from a workspace folder of papers, with sentence-level citation grounding.

junio

A conversational CLI agent that composes academic literature reviews from a workspace folder of papers — with sentence-level citation grounding and a verifier that checks every claim against the actual source passage.

Built on the OpenAI Agents Python SDK, defaulting to GLM-5.1 via Zhipu's OpenAI-compatible endpoint.

What it does

1. You drop PDF/DOCX papers into a workspace folder.
2. You run junio in your IDE terminal.
3. You converse with the agent: "Compose a review on retrieval-augmented generation, ~5000 words".
4. The agent drafts an outline, composes each section in parallel, runs a verifier on every claim against the actual paper passages, and renders the result as report.docx and report.pdf.
5. You give feedback in the REPL: "Section 3 should be more critical" — the agent revises that section and re-renders.
6. Conversation persists across junio invocations in the same workspace, so you can pick up where you left off.

Status

Alpha. First prototype is functional end-to-end on a small fixture corpus.

Quick start

pip install -e .                # from a clone
export ZHIPU_API_KEY=...         # or put it in a .env file
cd ~/projects/my-review
mkdir -p papers
cp ~/Downloads/*.pdf papers/
junio

Workspace layout

<workspace>/
├── papers/           user drops PDF/DOCX here (auto-discovered)
├── template.docx     optional — overrides built-in templates
├── junio.toml        optional — language, citation style, defaults
├── .junio/           agent-managed state (gitignore'd)
│   ├── cache/        parsed text + embeddings
│   ├── session.db    conversation state (resumable)
│   ├── sandbox/      temp scripts for run_python tool
│   └── runs/<ts>/    every render archived
├── report.docx       latest output
└── report.pdf        latest output

CLI flags

Flag	Effect
--workspace <path>	Override workspace (default: cwd)
--fresh	Delete .junio/session.db and start over
--no-resume	Don't auto-load previous session, but don't delete it
--lang {en,zh,auto}	Override language detection
--cite {apa,ieee,chicago,gb7714}	Override citation style
--config <toml>	Use alternate config file
--debug	Verbose logging

License

MIT — see LICENSE.

Design

See docs/superpowers/specs/2026-04-30-literature-review-agent-design.md for the architecture spec.