sub-checker 0.1.0

Pre-submission manuscript checker powered by Claude agents

sub-checker

繁體中文 | English

Pre-submission manuscript checker powered by Claude agents with a Plan-Execute-Verify harness. Each check is performed by a specialized AI agent, then validated by deterministic checks and a reviewer agent to eliminate false positives.

What it checks

Agent	What it does
typo_grammar	Spelling, grammar, awkward phrasing (skips reference list)
figure_table	Figure/table references exist, numbering is sequential, files present
citation_exist	In-text citations match the reference list (deterministic pre-scan + agent)
citation_format	Reference list follows target journal's citation style (APA, Vancouver, AMA, etc.)
journal_guidelines	Word count, required sections, abstract format, required statements (COI, ethics, data availability)
logic	Contradictions, unsupported claims, methods-results mismatches
citation_claim	Multi-source verification (PubMed + Semantic Scholar + Crossref), then verifies claims against abstracts

Install

pip install sub-checker

Setup

You need an Anthropic API key:

export ANTHROPIC_API_KEY=sk-ant-...

Or create a .env file in your working directory:

ANTHROPIC_API_KEY=sk-ant-...

Usage

CLI

# Full check with target journal
sub-check paper.docx -j "The Lancet"

# Chinese report output
sub-check paper.docx -j "Nature Medicine" --lang zh-TW

# Only run specific checkers (cheaper & faster)
sub-check paper.docx --only figure,citation

# Skip expensive checkers
sub-check paper.docx --skip claim,logic

# Output as styled HTML report (includes COT viewer + confidence scores)
sub-check paper.docx -o html --output-file report.html

# Output as JSON (for programmatic use)
sub-check paper.docx -o json --output-file report.json

# Dry run (just parse, no agents)
sub-check paper.docx --dry-run

Web GUI

# Start backend
uvicorn sub_checker.api:app --reload

# Start frontend (in another terminal)
cd frontend && npm run dev

Open http://localhost:5173 — upload a .docx, pick a journal, run, and view the report with confidence badges and filtered false positives.

CLI options

sub-check [OPTIONS] MANUSCRIPT_PATH

Arguments:
  MANUSCRIPT_PATH    Path to .docx file or directory containing one

Options:
  -j, --journal      Target journal name (e.g. "The Lancet")
  -o, --output       terminal | json | markdown | html (default: terminal)
  --output-file      Write report to file
  --lang             Report language: en (default) or zh-TW
  --only             Comma-separated: typo,logic,figure,citation,format,guidelines,claim
  --skip             Comma-separated checkers to skip
  -v, --verbose      Show agent tool calls in real-time
  --dry-run          Only parse .docx, don't run agents
  --init             Generate default .sub-checker.yaml

Pipeline (5 phases)

Phase 1-3  │  7 checker agents (parallel within each phase)
Phase 4    │  Deterministic post-validation (date math, citation cross-check)
Phase 5    │  Reviewer agent validates all findings → confidence scores

• Pre-execution: deterministic citation pre-scan + multi-source reference verification
• Post-validation: false positives filtered, remaining findings get confidence scores (0-100%)
• See harness-architecture.md for full technical details

HTML report features

• Dark-themed styled report with severity badges
• Confidence scores — each finding shows reviewer-assigned confidence (%)
• False positive filtering — deterministic + reviewer agent removes incorrect findings
• Chain of Thought viewer — expand to see every API call, tool use, and reasoning step
• Model display — shows which Claude model generated the report
• i18n support (English / Traditional Chinese)

Cost estimate

Uses Claude Opus 4.8 by default. Approximate cost per manuscript (~4000 words):

Scope	Agents	Time	Cost
Quick check	--only figure,citation	~4 min	~$3
Standard	--skip claim	~8 min	~$7
Full check	all 7 agents + harness	~12 min	~$12–16

You can change the model in .sub-checker.yaml (e.g. use claude-sonnet-4-6 for cheaper runs).

Logging

All logs are stored in ~/.sub-checker/:

• logs/sub-checker.log — application log (auto-rotated, 10MB x 5)
• logs/sub-checker.error.log — errors only
• cot/ — agent chain-of-thought JSON logs (every tool call, every response)

Set cot_dir: "disabled" in .sub-checker.yaml to turn off COT file logging (entries still appear in HTML reports).

Architecture

• 5-phase pipeline: Plan-Execute-Verify harness (ADR-0010)
• 7 agents + reviewer agent, each with system prompt + curated tools + agentic loop (ADR-0002)
• Parser provides raw data; agents judge document structure (ADR-0009)
• Multi-source citation verification: PubMed + Semantic Scholar + Crossref (ADR-0005)
• FastAPI + React + TypeScript GUI (ADR-0006)
• Benchmark comparison | Harness architecture

License

MIT