Copaper - Your Paper Assistant¶

For the full reference manual, see Full Reference Manual.

Before You Use CoPaper¶

Tool Scope¶

CoPaper is an assistant. It can help organize materials, manage state, and call writing or review tools, but it does not replace the author's judgment, experiments, or responsibility for the final paper.

Academic Integrity¶

Experimental data, figures, metrics, case studies, and conclusions must come from real experiments or verifiable sources. Do not use CoPaper to plagiarize, fabricate data, invent citations, or overstate contributions.

Step-by-Step Generation¶

Current models still struggle with whole-paper generation. Work section by section, subsection by subsection, or paragraph by paragraph. Large one-shot generations are more likely to miss constraints, mix contexts, or produce uneven prose.

Human Verification¶

Anything generated by CoPaper or a language model may contain hallucinations, inaccurate wording, or unverified inferences. Before submission or public use, manually check facts, data, citations, experimental setup, conclusions, and originality.

CoPaper OpenCode Plugin Usage¶

Install From Local Packages¶

From the repository root, enter the plugin package, install dependencies, and build it:

cd packages/opencode-plugin
bun install
bun run build

Then install the local plugin into a target CoPaper project:

bun run dev:install <target-project>

<target-project> is the project directory where the plugin should be enabled. After installation, restart OpenCode and run these commands inside the target project:

/copaper-doctor
/copaper

Install From npm¶

If you want to use the published package, run this from the target project root:

bunx -p @copaper/opencode copaper-opencode init

Bun needs -p because the package name is @copaper/opencode, while the binary name is copaper-opencode.

Plugin Capability Overview¶

OpenCode Tools¶

The plugin currently provides 23 copaper_* tools. They fall into a few practical groups: read-only inspection, initialization, import extraction, related-work operations, status recording, and workflow management.

Tool	Purpose
`copaper_dashboard`	Shows project readiness, core file status, and init preview; read-only.
`copaper_init_apply`	Initializes core project files after explicit user confirmation.
`copaper_artifact_status`	Checks readiness for `storyline.md`, `paper.md`, related work, checkers, and other artifacts; read-only.
`copaper_artifact_record`	Records artifact readiness into state and the event log after confirmation.
`copaper_paper_structure_status`	Scans `paper.md` structure completion, Level 5 writing targets, and structural issues; read-only.
`copaper_storyline_structure_status`	Scans `storyline.md` section completion, TODO coverage, and the next target; read-only.
`copaper_pdf_extract`	Extracts text from a user-specified in-project PDF; read-only.
`copaper_ppt_extract`	Extracts slide text and optional notes from a user-specified in-project PPTX; read-only.
`copaper_checker_status`	Summarizes checker status, severity counts, stale signals, and precheck evidence; read-only.
`copaper_checker_record`	Records a checker run summary after confirmation.
`copaper_relatedwork_status`	Checks related-work catalog, BibTeX, PDFs, summaries, and cross-index status; read-only.
`copaper_relatedwork_keywords`	Extracts search keywords from the storyline or a chosen source and writes `relatedwork/queries.txt`.
`copaper_relatedwork_search`	Searches related work through Semantic Scholar / arXiv and writes the search cache.
`copaper_relatedwork_import`	Imports the search cache into `relatedwork/literature.json`.
`copaper_relatedwork_sync_bib`	Synchronizes `relatedwork/paper_list.bib` from the literature catalog.
`copaper_relatedwork_download`	Downloads related-work PDFs into the relatedwork PDF directory.
`copaper_relatedwork_summarize`	Uses the CLI/LLM bridge to generate PDF summaries.
`copaper_relatedwork_register_summary`	Registers an existing summary file in the literature catalog.
`copaper_relatedwork_build_index`	Builds `.agents/cross_index.json` from related-work summaries.
`copaper_relatedwork_clean`	Cleans stale related-work entries, orphan PDFs, or orphan summaries.
`copaper_workflow_status`	Shows current phase, phase table, and next-step recommendation; read-only.
`copaper_workflow_log`	Queries recent workflow events, optionally filtered by phase or operator; read-only.
`copaper_workflow_set_phase`	Updates workflow phase status after confirmation and appends an event record.

CoPaper Subagents¶

The plugin injects 6 built-in subagents into OpenCode. Their jobs are intentionally separate: coordination, storyline work, paper writing, review, state recording, and literature work.

Subagent	Purpose
`@copaper-coordinator`	Read-only coordinator; checks project status, clarifies scope, and recommends the next role or next step.
`@copaper-storyline`	Maintains the research storyline in `storyline.md`; edits storyline only after confirmation.
`@copaper-writer`	Drafts or revises `paper.md` under CoPaper structure rules; does not edit storyline or state files.
`@copaper-reviewer`	Read-only reviewer; explains checker results, severity, and likely review risks without editing the paper.
`@copaper-recorder`	Records artifact readiness or checker summaries as state facts; does not edit paper content.
`@copaper-literature`	Drives the related-work workflow through search, import, download, summary, and cross-index tools.

Project Skills¶

The project currently includes 28 skills under .agents/skills/. Think of them as operating notes for agents: which files to read, what they may edit, and when they must stop for confirmation.

Skill	Purpose
`storyline-helper`	Interactively builds and improves `storyline.md`; polishes user-provided research content without inventing the storyline.
`socratic-discussion`	Uses Socratic questioning to examine insights, claims, methods, and evidence across the 7 checker dimensions.
`writing-orchestrator`	Scans `paper.md` completion, recommends writing order, and routes to fine, strict, or fast writing modes.
`markdown-helper`	Helps write and improve `paper.md` content under the CoPaper structure.
`state-machine-markdown-helper`	Writes paragraph by paragraph with a strict state machine and context isolation to reduce hallucination.
`mad-writer`	Runs an automatic write-check-fix loop, optionally using related work and placeholder data.
`markdown-review`	Reviews markdown paper content and produces structured improvement guidance.
`review-revise`	Conducts multi-round checker-driven revision, confirming each issue before edits.
`problem-checker`	Checks whether the problem is clear and whether importance/practicality are well supported.
`novelty-checker`	Checks whether the core insight is novel and differentiated from prior work.
`technical-depth-checker`	Checks whether the design has enough technical depth, non-trivial challenges, and concrete solutions.
`logic-checker`	Checks claim-evidence alignment, contradictions, and argument gaps.
`clarity-checker`	Checks term definitions, description clarity, references, and readability.
`evaluation-protocol-checker`	Checks RQs, experiment design, design-decision validation, and threats to validity.
`data-checker`	Checks for placeholder/bogus data and verifies reproducibility scripts for tables and figures.
`submission-precheck`	Runs pre-submission checks for format, citations, figures, word count, completeness, data authenticity, and quality.
`experiment-analyzer`	Analyzes experiment code, results, or protocols and maps them to research questions.
`bogus-data-helper`	Creates clearly marked synthetic placeholder tables, figures, and metrics that must be replaced with real results.
`relatedwork-finder`	Finds, imports, and downloads related work based on `storyline.md` or `paper.md`.
`relatedwork-summarizer`	Runs the relatedwork CLI to summarize PDFs, build the cross-index, and produce a coverage report.
`pdf2paper`	Maps an existing PDF draft into the `paper.md` framework without inventing new content.
`ppt2storyline`	Extracts slide content from PPT/PPTX files and maps it into `storyline.md`.
`latex2markdown`	Migrates LaTeX paper content into the CoPaper `paper.md` structure.
`markdown2latex`	Converts `paper.md` into high-quality LaTeX, with optional conference template adaptation.
`latex-final-writer`	After `paper.md` is complete, creates `writing_plan.md`, initializes the `tex/` structure, and writes the final LaTeX draft from a conference or journal template.
`humanizer`	Removes AI-writing traces and makes prose sound more natural while preserving meaning and tone.
`human-comment-helper`	Helps advisors or instructors turn human feedback into structured comments while distinguishing AI examples from real feedback.
`copaper-manage`	Guides agents in using OpenCode plugin tools for initialization, workflow, event log, readiness, and phase management.

Phase Management Entry Point¶

In OpenCode, the direct entry point for phase management is the copaper-manage skill. It first reads the current phase through copaper_workflow_status, then calls copaper_workflow_set_phase after explicit user confirmation. That tool writes .agents/state.json and appends .agents/events.jsonl. Other skills also use the same tool at the end of their own workflows, such as storyline-helper for storyline, experiment-analyzer for experiments, and writing-orchestrator for writing.

End-to-End Usage Guide¶

Choose an Operating Mode¶

CoPaper has two entry points. The CLI is better for scripts, batch operations, relatedwork pipelines, and Git-backed phase management. The OpenCode plugin is better for day-to-day writing inside the IDE through /copaper, subagents, and confirmation-based tools. In practice, the two work best together.

Step 0: Prepare the Environment¶

The target project needs Python, Git, Bun, and OpenCode. The Python side provides the copaper CLI. The Bun side installs @copaper/opencode. OpenCode provides slash commands, tools, and subagents. Related-work search, keyword extraction, and summarization also require .env configuration in the target project. Do not commit secrets.

# Install the Python CLI from the CoPaper repository
pip install -e .[dev]

# Install the OpenCode plugin in the target project
bunx -p @copaper/opencode copaper-opencode init

For local development, use bun run dev:install <target-project> as described above. After installation, restart OpenCode and run /copaper-doctor and /copaper inside the target project.

Git-Assisted Management¶

Git is not a standalone writing step. It is an optional management layer across the workflow. Inside a Git repository, use copaper commit for phase-scoped commits, diff to compare phase commits, and rollback to soft-reset to the last commit for a phase while resetting that phase status. report can run outside a Git repository. commit, rollback, and diff must run inside one.

copaper --root <target-project> commit --phase storyline -m "Complete storyline draft"
copaper --root <target-project> diff storyline literature
copaper --root <target-project> rollback storyline

Rollback changes the worktree state, so make sure important edits are saved first.

Readiness and Phase Management¶

Readiness and phase updates are not standalone writing steps either. They are state-management actions used throughout the workflow. Update CoPaper state through the CLI or plugin tools. Do not hand-edit .agents/state.json. When an artifact becomes usable, inspect evidence first, then explicitly confirm readiness recording. When a phase is complete, skipped, or rolled back, confirm the phase update.

/copaper
Please check artifact readiness.
Confirm recording paper.md as partial with medium confidence because the Introduction is done but Evaluation is not written yet.
Confirm marking the writing phase as in_progress.

CLI equivalents:

copaper --root <target-project> set-phase writing --status in_progress
copaper --root <target-project> log --last 10
copaper --root <target-project> report --output report.md

In OpenCode, trigger copaper-manage or simply say that a phase should be marked as a certain status. The agent should restate phase, status, and reason, then wait for confirmation before calling copaper_workflow_set_phase. This is safer than editing the state file directly.

Step 1: Initialize the Paper Project¶

Start by creating the CoPaper core artifacts. The CLI copies storyline.md, paper.md, writingrules.md, AGENTS.md, and .agents/skills/. The plugin initialization flow first shows a preview and writes core files only after explicit confirmation.

copaper --root <target-project> init --name "<project-name>" --domain "<research-domain>"
copaper --root <target-project> status

In OpenCode, open /copaper to view the dashboard. If the dashboard says the project is not ready, follow the prompt and confirm initialization. If files already exist, decide whether to keep, migrate, or use a different directory before writing anything.

You can also initialize a project from existing materials instead of starting from blank templates. ppt2storyline can convert a meeting PPT/PPTX into storyline.md. pdf2paper can map an existing PDF draft into paper.md. latex2markdown can migrate an existing LaTeX paper into the markdown framework. Import should remain faithful to the source material: map and lightly polish, but do not invent new claims.

Extract this PPTX into storyline.md, but do not add claims that are not present in the slides.
Import this PDF draft into paper.md while preserving the original claim boundaries.
Migrate this LaTeX paper into the CoPaper paper.md structure.

If the import produces storyline.md, you can skip blank storyline drafting in Step 2, inspect and confirm the storyline, then continue with Step 3 for related work. If the import produces a complete or nearly complete paper.md, you can fill any necessary storyline or related-work evidence, then jump to Step 7 for review, revision, and checker recording.

Step 2: Fill the Research Storyline¶

Complete storyline.md first. It is the primary constraint for later literature search, discussion, experiments, and writing. Use @copaper-storyline or trigger storyline-helper, then provide your problem, importance, insight, design idea, and evaluation plan section by section. The agent may polish and organize your content, but it should not invent research substance.

@copaper-storyline Help me fill the problem statement section in storyline.md.

Afterward, check the structure status and record progress only after confirmation:

/copaper
Please check storyline structure completion.
Confirm marking the storyline phase as complete because the first storyline draft is done.

The literature phase converts storyline.md or paper.md into search keywords, searches papers, imports metadata, syncs BibTeX, downloads PDFs, generates per-paper summaries, and builds .agents/cross_index.json. In the plugin, hand this to @copaper-literature. In the CLI, run the 7-step pipeline:

copaper --root <target-project> relatedwork keywords --count 6
copaper --root <target-project> relatedwork search --queries-file relatedwork/queries.txt --limit 5
copaper --root <target-project> relatedwork import --input relatedwork/search_cache.json
copaper --root <target-project> relatedwork sync-bib
copaper --root <target-project> relatedwork download
copaper --root <target-project> relatedwork summarize --concurrency 4
copaper --root <target-project> relatedwork build-index
copaper --root <target-project> relatedwork status

Keyword extraction and summarization require an OpenAI-compatible LLM. Search uses Semantic Scholar / arXiv. Start with a small limit for a smoke test, confirm .env, network access, and the copaper bridge, then scale up.

Step 4: Discuss and Tighten the Argument¶

The discussion phase uses socratic-discussion to stress-test the problem, novelty, technical depth, logic chain, clarity, evaluation protocol, and data evidence. This phase is not paper drafting; it is a way to expose likely reviewer concerns early and revise the storyline or experiment plan.

Run a Socratic discussion focused on novelty and technical depth.

If the discussion exposes storyline gaps, return to storyline-helper. If it exposes missing experiments or evidence, move to experiment analysis. If it only exposes wording issues, leave them for writing and review.

Step 5: Prepare Experiments or Record a Skip¶

The experiments phase can use experiment-analyzer to understand experiment code, analyze results, or review the protocol. For theoretical or design-only papers, you can explicitly skip the phase and record the reason. Do not treat placeholder data as real results. If placeholder content is needed, use bogus-data-helper and mark it as synthetic.

Analyze the results in experiments/ and map them to the paper's RQs.

When skipping experiments, use the full phase name:

copaper --root <target-project> skip experiments --reason "<reason>"

Step 6: Write paper.md¶

The writing phase centers on paper.md. Start with writing-orchestrator to scan completion and recommend order. Then choose a writing mode: markdown-helper for careful section-by-section drafting, state-machine-markdown-helper for strict paragraph-by-paragraph writing, or mad-writer for faster generation and iteration. In the plugin, use @copaper-writer; it should edit only paper.md.

@copaper-writer Based on storyline.md and the cross-index, write the first Level 5 section of the Introduction.

Follow the CoPaper structure. Levels 1-5 are structural headings only. Body text must appear under Level 6 headings. Level 6 titles must be at most 50 characters, and paragraph bodies must be at most 500 characters. When citing literature, inspect .agents/cross_index.json first, then read only the targeted relatedwork/papers/*.md summaries.

Step 7: Review, Revise, and Record Checkers¶

After writing a section, run review. @copaper-reviewer and the checker skills identify issues. review-revise processes them in Critical, Major, then Minor order, with confirmation before each edit. If checker results should be persisted, route the record action to @copaper-recorder after restating checker, status, counts, summary, evidence, and reason.

@copaper-reviewer Check the current paper.md for problem, novelty, and logic risks.

Before submission, run submission-precheck. It checks format, citations, figures, word count, completeness, data authenticity, and overall quality, then generates a precheck report.

Step 8: Generate the Final LaTeX Draft¶

The import entry point for existing materials is in Step 1 during initialization. After the paper is complete and has passed the necessary review, the final step is to use latex-final-writer to generate the LaTeX final draft. This skill uses the completed paper.md, storyline.md, related-work summaries, experiment materials, and the user-provided conference or journal template to create or update writing_plan.md, initialize the tex/ structure, and write the submission-ready LaTeX draft section by section.

Because current model and project capabilities are still limited, generate and revise the paper section by section, subsection by subsection, or paragraph by paragraph. Do not ask the system to generate the whole paper at once. When too much content is handled in one pass, the model is more likely to miss constraints, confuse context, or produce unstable quality.

I have completed paper.md. Use latex-final-writer with the tex/ template to generate the final LaTeX draft.

The final draft must not invent experiments, numbers, citations, or claims. After generation, compile the LaTeX and manually verify citations, figures, formulas, page limits, anonymity requirements, overfull boxes, and undefined references.

Recommended End-to-End Path¶

The recommended complete path is: install plugin and CLI, initialize the project or import existing materials, complete or confirm storyline.md, run relatedwork, run Socratic discussion, prepare experiments or record a skip reason, write or import paper.md, review and revise section by section, run submission precheck, then use latex-final-writer to generate the final LaTeX draft. After importing slides into the storyline, continue from Step 3. After importing an existing paper into paper.md, continue from Step 7. Every phase can be re-entered. If a later step exposes an earlier gap, return to the corresponding skill and fix it.

Initialize -> Storyline -> Literature -> Discussion -> Experiments/Skip -> Writing -> Review/Revise -> Precheck -> Final LaTeX Draft

Common Notes¶

--root is a global CLI option and must appear before the subcommand. Phase names must be storyline, literature, discussion, experiments, writing, or latex_review. Read-only plugin tools do not write files. Write-capable tools usually require the agent to restate parameters and wait for explicit confirmation. Store secrets in .env and do not commit them. Do not directly edit .agents/state.json or .agents/events.jsonl unless you are debugging the implementation.