Qiongli

What It Is

Qiongli is an academic workflow system for researchers who use Codex, Claude Code, Claude Desktop, Antigravity, Hermes, or similar AI agents. Use it when a research task is too important for a one-off prompt and needs visible evidence, repeatable steps, and reviewable outputs.

You can use Qiongli to:

• choose a paper route for empirical, qualitative, systematic review, RCT, theory, and code-first methods projects;
• structure literature search, citation checking, study design, writing, code, review, submission, and rebuttal work;
• keep claims, sources, methods decisions, review notes, and generated artifacts in predictable project paths;
• run lightweight skill/plugin workflows first, then add the full local orchestrator only when you need controlled solo, duo, or triad agent execution.

The name comes from 穷理: keep asking what principle, evidence, and limit sits underneath a claim.

Start Here

Latest Stable Downloads

Current stable release: v1.17.0. These direct links cover the common install paths; use the download guide for subject-specific Desktop ZIPs and maintainer artifacts.

Install Fast

The npm CLI is a Python-free asset manager. It installs the skills surface by default:

npm install -g qiongli
qiongli install --target auto --surface skills
qiongli check

For scripted installs, keep the project directory explicit:

qiongli install --target all --project-dir "$PWD"

--target all writes every supported platform path explicitly. Use --target auto to detect supported client CLIs on PATH and install only those client surfaces.

Use project-local subject guidance instead of reinstalling packages for every topic:

qiongli project init --project-dir "$PWD"
qiongli project set-subject finance --project-dir "$PWD"
qiongli project status --project-dir "$PWD"

For plugin-lite or full runtime paths, use the install guide. It covers Codex and Claude Code marketplace plugins, Claude Desktop direct plugin and fallback Skill ZIPs, the literature MCPB, bootstrap partial/full, npm/npx, pipx, and pip. npm plugin-lite output is opt-in with --surface plugin or --surface both where bundled and supported.

Install Entry Comparison

Runtime Flow

flowchart TB
    Request["Academic request<br/>topic, paper type, constraints"]
    Entry{"Entry point"}
    Client["Client skill/plugin<br/>Codex, Claude Code,<br/>Claude Desktop/Web"]
    Npm["npm/npx asset manager<br/>install, update, check,<br/>project guidance"]
    Full["Full runtime<br/>pipx/pip/bootstrap full"]
    Project["Project guidance<br/>.qiongli/guidance_manifest.yaml<br/>or active_subject: auto"]
    Contract["Task contract<br/>Task ID, stage, outputs,<br/>evidence rules, gates"]
    Runtime{"Smallest runtime<br/>that fits the job"}
    SkillOnly["Skill/plugin only<br/>draft, review, route"]
    Provider["Literature provider<br/>MCPB or bundled Node MCP"]
    Preview["Full runtime preview<br/>doctor, task-plan,<br/>task-run without agents"]
    Execute{"run_agents true?"}
    Agents["Controlled agent run<br/>solo, duo, triad"]
    Outputs["Formal outputs<br/>RESEARCH/[topic]/..."]
    Trace["Trace and guidance proposal<br/>.qiongli/trace/"]

    Request --> Entry
    Entry --> Client
    Entry --> Npm
    Entry --> Full
    Npm --> Project
    Client --> Contract
    Full --> Contract
    Project --> Contract
    Contract --> Runtime
    Runtime --> SkillOnly
    Runtime --> Provider
    Runtime --> Preview
    SkillOnly --> Outputs
    Provider --> Outputs
    Preview --> Execute
    Execute -->|no| Trace
    Execute -->|yes| Agents
    Agents --> Outputs
    Agents --> Trace
    Trace --> Project

The npm path stops at asset management and project guidance. Full runtime commands are explicit, preview-first, and start real agent execution only after run_agents: true plus passing runtime checks.

Recommended CLI Setup Wizard

Use the full runtime wizard when you want the CLI to help choose an install and upgrade path:

pipx install qiongli
qiongli setup
qiongli setup --dry-run
qiongli setup --project-dir "$PWD" --no-doctor

The full runtime wizard covers runtime surface, subject, coverage, --mode copy|link, shell CLI / CLI directory choices, --overwrite / --no-overwrite, optional provider config, and doctor verification. On npm/npx, qiongli setup is the Python-free asset manager shortcut for client assets; full runtime commands such as doctor, mcp serve, provider setup, or customize require pipx install qiongli. If you only need scriptable asset installation, run qiongli install ... directly.

Update Or Refresh

On npm/npx, qiongli update and qiongli refresh stay on the Python-free asset path:

qiongli update
qiongli refresh

On npm/npx, qiongli upgrade is an alias for an overwrite asset refresh from the currently installed npm package; it does not update the npm package or the full Python CLI. Selected release archives, package self-update, and qiongli self-update belong to the full Python runtime: pipx install qiongli.

qiongli upgrade --target all

Runtime Boundary

Installing Qiongli assets is intentionally lighter than running full orchestration.

Actual agent execution starts only when the runtime is configured and an execution command explicitly enables it. Previews and checks are designed to be inspectable before side effects.

Research Boundaries

Qiongli includes the Academic Idea Funnel and Academic Grill Loop as an academic adaptation of Matt Pocock's grill-me idea-discovery pattern. It is tuned for academic idea-discovery, so it asks about evidence, rival explanations, feasibility, venue fit, and boundary review before drafting.

Provider credentials stay in provider config, not generated skill bundles. Use qiongli provider setup for OpenAlex, Semantic Scholar, Crossref, PubMed, and arXiv-supported literature workflows, then qiongli provider doctor to verify. The qiongli-literature-provider .mcpb exposes qiongli_literature_status, qiongli_search_plan, qiongli_literature_search, qiongli_literature_export_evidence, qiongli_config_status, qiongli_configure_provider, and qiongli_save_provider_config for Codex/Desktop flows; statuses include provider_connected, native_only, and strategy_only depending on provider and platform search availability. qiongli_collect_evidence is an external evidence adapter path and must not be used as the OpenAlex provider-config check. Skill-only installs can still use strategy fallback, and runtime checks keep a 180-second ceiling for external provider probes.

Documentation Map

• Guide: install, usage, upgrade, troubleshooting, and runtime choices.
• Quickstart: smallest install surface and first research route.
• Using Agent Skills: what to type in Codex, Claude Code, Antigravity, Hermes, and shell.
• Task Recipes: scenario-based paper routes.
• Reference: CLI behavior and skill catalog.
• Advanced: MCP providers, Zotero, subject packaging, and plugin-first distribution.
• Maintainer: release policy, naming policy, and contributor guidance.

Development

Common checks:

python3 -m unittest tests.test_self_update tests.test_cli tests.test_cli_setup_docs
python3 -m unittest tests.test_materialize_distribution_payloads tests.test_npm_package_contract
npm --prefix packages/npm-qiongli test
npm run docs:build
git diff --check

Maintainer contract anchors:

• The canonical contract lives with the workflow standards; packaged installs expose standards/research-workflow-contract.yaml and standards/mcp-agent-capability-map.yaml.
• Run python3 scripts/validate_research_standard.py --strict before release-facing changes.
• Subject package changes must pass staged materialization and npm package contract tests, including tests.test_materialize_distribution_payloads and tests.test_npm_package_contract.
• Agent routing details live in Agent-Skill Collaboration.
• The legacy shell installer remains at scripts/install_qiongli.sh; most users should prefer the install guide or qiongli install.

Routine releases go through:

./scripts/release_automation.sh publish --version <version> --from-tag <previous-tag>

Credit

Qiongli adapts useful workflow ideas from strict agent planning/review systems, Claude skill packaging, and academic review practices. Thanks to the linux.do community for practical AI tooling discussion and feedback.