Oh-my--paper
A Claude Code plugin that turns your terminal into an autonomous research lab — literature survey, experiment execution, paper writing, all in one pipeline.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/ligphidonk--oh-my-paper)HTML
<a href="/listings/ligphidonk--oh-my-paper"><img src="/api/listings/ligphidonk--oh-my-paper/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
Step 1: Add the marketplace
/plugin marketplace add LigphiDonk/Oh-my--paper
Step 2: Install the plugin
/plugin install omp@oh-my-paper
Step 3: Restart Claude Code
Required for hooks to activate.
Step 4: Initialize your project
/omp:setup
This scaffolds the `.pipeline/` directory and registers the `SessionStart` hook for your project.
Update
The most reliable way to get the latest version:
/plugin uninstall omp /plugin install omp@oh-my-paper /reload-plugins
Or overwrite the plugin cache directly (faster, no restart needed):
cp -r /path/to/oh-my-paper/plugins/oh-my-paper/. \ ~/.claude/plugins/cache/oh-my-paper/omp/1.0.0/ # Then in Claude Code: /reload-plugins
Install from Local Directory
git clone https://github.com/LigphiDonk/Oh-my--paper.git /tmp/oh-my-paper # In Claude Code: /plugin marketplace add /tmp/oh-my-paper /plugin install omp@oh-my-paper
---
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
.claude-plugin/marketplace.json · Manifest · 21 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- {
- "name": "oh-my-paper",
- "owner": {
- "name": "LigphiDonk"
- },
- "metadata": {
- "description": "AI-powered academic research harness for Claude Code. Orchestrate literature surveys, idea generation, experiments, and paper writing with Codex delegation.",
- "version": "1.0.0"
- },
- "plugins": [
- {
- "name": "omp",
- "description": "Research harness: delegate to Codex, track memory across sessions, drive the full survey→ideation→experiment→publication pipeline.",
- "version": "1.0.0",
- "author": {
- "name": "LigphiDonk"
- },
- "source": "./plugins/oh-my-paper"
- }
- ]
- }
README.md · README · 495 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- <p align="center">
- <img src="./src/assets/qrcode.jpg" alt="交流群二维码" width="180" />
- <br/>
- <em>扫码加入交流群</em>
- </p>
- <p align="center">
- <img src="./icons/icon.png" alt="Oh My Paper" width="120" height="120" />
- </p>
- <h1 align="center">Oh My Paper</h1>
- <p align="center">
- <strong>A research harness for Claude Code — turn your terminal into an autonomous research lab.</strong>
- </p>
- <p align="center">
- <a href="./README.zh.md">中文文档</a>
- </p>
- <p align="center">
- <img src="https://img.shields.io/badge/claude--code-plugin-blueviolet?style=flat-square" />
- <img src="https://img.shields.io/badge/agents-5-ff69b4?style=flat-square" />
- <img src="https://img.shields.io/badge/skills-34-green?style=flat-square" />
- <img src="https://img.shields.io/badge/commands-8-blue?style=flat-square" />
- <img src="https://img.shields.io/badge/license-MIT-orange?style=flat-square" />
- </p>
- ---
- ## TL;DR
- ```bash
- # In Claude Code:
- /plugin marketplace add LigphiDonk/Oh-my--paper
- /plugin install omp@oh-my-paper
- ```
- Restart Claude Code. Run `/omp:setup` inside your research project, then drive the full pipeline with `/omp:survey`, `/omp:experiment`, and `/omp:write`. No GUI, no window-switching — everything in the terminal.
- ---
- ## Table of Contents
- - [Why This Exists](#why-this-exists)
- - [Install](#install)
- - [Claude Code Slash Commands](#claude-code-slash-commands)
- - [The Agent Team](#the-agent-team)
- - [34 Research Skills](#34-research-skills)
- - [Hooks](#hooks)
- - [Research Pipeline](#research-pipeline)
- - [Project Scaffold](#project-scaffold)
- - [How Memory Works](#how-memory-works)
- - [Codex Delegation](#codex-delegation)
- - [Remote Experiments](#remote-experiments)
- - [For LLM Agents](#for-llm-agents)
- - [Philosophy](#philosophy)
- - [Contributing](#contributing)
- - [Uninstall](#uninstall)
- ---
- ## Why This Exists
- Claude Code is already a great coding agent. But **research isn't just coding** — it's literature survey, idea evaluation, experiment design, paper writing, reference checking, and a dozen other things that require domain-specific workflows.
- Oh My Paper makes Claude Code **research-aware** by adding:
- - **A structured 5-stage pipeline** — Survey → Ideation → Experiment → Publication → Promotion
- - **5 specialized agent roles** — each with isolated memory and clear responsibilities
- - **34 built-in research skills** — from paper search to figure generation
- - **Background hooks** — auto-inject project context at session start, prompt role selection, track task completion
- - **Codex delegation** — hand off parallel tasks to Codex in a separate terminal
- Install it and forget about it. Your sessions get smarter. Your research gets organized.
- ---
- ## Install
- ### Step 1: Add the marketplace
- ```bash
- /plugin marketplace add LigphiDonk/Oh-my--paper
- ```
- ### Step 2: Install the plugin
- ```bash
- /plugin install omp@oh-my-paper
- ```
- ### Step 3: Restart Claude Code
- Required for hooks to activate.
- ### Step 4: Initialize your project
- ```bash
- /omp:setup
- ```
- This scaffolds the `.pipeline/` directory and registers the `SessionStart` hook for your project.
- ### Update
- The most reliable way to get the latest version:
- ```bash
- /plugin uninstall omp
- /plugin install omp@oh-my-paper
- /reload-plugins
- ```
- Or overwrite the plugin cache directly (faster, no restart needed):
- ```bash
- cp -r /path/to/oh-my-paper/plugins/oh-my-paper/. \
- ~/.claude/plugins/cache/oh-my-paper/omp/1.0.0/
- # Then in Claude Code:
- /reload-plugins
- ```
- ### Install from Local Directory
- ```bash
- git clone https://github.com/LigphiDonk/Oh-my--paper.git /tmp/oh-my-paper
- # In Claude Code:
- /plugin marketplace add /tmp/oh-my-paper
- /plugin install omp@oh-my-paper
- ```
- ---
- ## Claude Code Slash Commands
- These slash commands are provided by the **Claude Code plugin**.
- The Codex plugin does **not** currently auto-register `/omp-*` commands in the Codex CLI.
- All commands are prefixed with `/omp:`.
- | Command | What It Does |
- |---------|-------------|
- | `/omp:setup` | Scaffold a new research project — creates `.pipeline/`, memory files, and registers the SessionStart hook |
- | `/omp:survey` | AI-assisted literature survey — search papers, build `literature_bank.md` |
- | `/omp:ideate` | Generate and evaluate research ideas based on survey findings |
- | `/omp:experiment` | Design experiments, write evaluation code, run on remote compute nodes |
- | `/omp:write` | Draft paper sections, generate figures and captions, manage LaTeX files |
- | `/omp:review` | Peer-review your paper or experiment results before submission |
- | `/omp:delegate` | Generate a Codex prompt for a coding/experiment task; wait for result and update project state |
- | `/omp:plan` | Review global progress, confirm next steps, update research plan |
- ### Quick Start
- ```bash
- /omp:setup # scaffold the project
- /omp:survey # start literature survey
- /omp:ideate # generate ideas from survey
- /omp:experiment # design & run experiments
- /omp:write # draft the paper
- /omp:review # final quality gate
- ```
- ---
- ## The Agent Team
- When you open Claude Code in an Oh My Paper project, the `SessionStart` hook fires and Claude immediately asks which role you want to take on. Each role has **isolated memory** — it only reads and writes the files it needs.
- | Role | Responsibility | Memory Scope |
- |------|---------------|-------------|
- | **Conductor** | Global planning, review outputs, dispatch tasks, auto-update `project_truth` after each subtask | `project_truth` · `orchestrator_state` · `tasks.json` · `review_log` · `agent_handoff` · `decision_log` |
- | **Literature Scout** | Search papers, organize literature bank | `project_truth` · `execution_context` · `literature_bank` · `decision_log` |
- | **Experiment Driver** | Design experiments, write code, run evaluations | `execution_context` · `experiment_ledger` · `research_brief.json` · `project_truth` |
- | **Paper Writer** | Draft sections, generate figures, audit references | `execution_context` · `result_summary` · `literature_bank` · `agent_handoff` |
- | **Reviewer** | Peer review, quality gate, consistency check | `execution_context` · `project_truth` · `result_summary` |
- ### How It Works
- ```
- Session opens
- → SessionStart hook fires
- → Claude asks: which role today?
- → Agent loads role-specific memory files
- → Works as that persona
- → On subtask complete: auto-updates tasks.json + project_truth
- → Next session picks up right where you left off
- ```
- **Key design decisions:**
- - **Memory isolation** — the Paper Writer can't see the Conductor's orchestrator state; the Literature Scout can't see experiment results. This prevents context pollution.
- - **Shared state** — `tasks.json` and `project_truth.md` are the common ground, updated by all roles after each subtask.
- - **No manual sync** — the Conductor auto-updates `tasks.json` (marks tasks `done`) and appends a progress entry to `project_truth.md` whenever a subtask completes, without waiting for you to ask.
- ---
- ## 34 Research Skills
- Skills are structured instruction sets that Claude loads on demand. Each skill is a markdown file covering a specific research task.
- <details>
- <summary><strong>Click to expand the full skill list</strong></summary>
- | Category | Skills |
- |----------|--------|
- | **Literature** | `paper-finder` · `paper-analyzer` · `paper-image-extractor` · `research-literature-trace` · `biorxiv-database` · `dataset-discovery` |
- | **Survey & Ideation** | `inno-deep-research` · `gemini-deep-research` · `inno-code-survey` · `inno-idea-generation` · `inno-idea-eval` · `research-idea-convergence` |
- | **Experiment** | `inno-experiment-dev` · `inno-experiment-analysis` · `research-experiment-driver` · `remote-experiment` |
- | **Writing** | `inno-paper-writing` · `ml-paper-writing` · `scientific-writing` · `inno-figure-gen` · `inno-reference-audit` · `research-paper-handoff` |
- | **Planning & Review** | `inno-pipeline-planner` · `research-pipeline-planner` · `inno-paper-reviewer` · `inno-prepare-resources` · `inno-rclone-to-overleaf` |
- | **Presentation** | `making-academic-presentations` · `inno-grant-proposal` |
- | **Agent Dispatch** | `claude-code-dispatch` · `codex-dispatch` |
- | **Domain-Specific** | `academic-researcher` · `bioinformatics-init-analysis` · `research-news` |
- </details>
- Skills are auto-recommended based on your current pipeline stage. Add project-local skills in the `skills/` directory.
- ---
- ## Hooks
- Oh My Paper registers three hooks that run in the background:
- | Hook | Trigger | What It Does |
- |------|---------|-------------|
- | **SessionStart** | Every time you open Claude Code in this project | Outputs project context to Claude — current stage, active task, last handoff — then prompts you to pick a role via `AskUserQuestion` |
- | **Stop** | When a task completes | Tracks task completion, updates `tasks.json` |
- | **PostToolUse (Write)** | After any file write | Detects pipeline stage transitions |
- **Important:** Hooks only activate after running `/omp:setup` in your project. Setup registers the `SessionStart` hook in `.claude/settings.json` and creates the `.pipeline/` directory that the hook checks.
- ---
- ## Research Pipeline
- A structured 5-stage workflow from idea to publication:
- ```
- ┌──────────┐ ┌──────────┐ ┌────────────┐ ┌─────────────┐ ┌───────────┐
- │ Survey │ → │ Ideation │ → │ Experiment │ → │ Publication │ → │ Promotion │
- └──────────┘ └──────────┘ └────────────┘ └─────────────┘ └───────────┘
- ```
- Each stage comes with:
- - **Auto-generated task trees** — what to do next
- - **Recommended skills** — which skills to load
- - **Context-aware prompts** — agents read `tasks.json` and `research_brief.json` and know what to do
- ---
- ## Project Scaffold
- `/omp:setup` creates this structure:
- ```
- my-research/
- ├── paper/ # LaTeX workspace
- │ ├── main.tex
- │ ├── sections/
- │ └── refs/
- ├── experiment/ # Experiment code & scripts
- ├── survey/ # Literature survey artifacts
- ├── ideation/ # Ideas, evaluations, plans
- ├── promotion/ # Slides, demos, outreach
- ├── skills/ # Project-local skills
- ├── .pipeline/
- │ ├── tasks/
- │ │ └── tasks.json # Task tree across all stages
- │ ├── docs/
- │ │ └── research_brief.json
- │ └── memory/ # Agent memory files
- ├── .claude/
- │ └── settings.json # SessionStart hook registration
- ├── CLAUDE.md
- └── AGENTS.md
- ```
- ---
- ## How Memory Works
- Each agent role reads and writes specific memory files. The Conductor is responsible for keeping shared state in sync.
- ```
- .pipeline/memory/
- ├── project_truth.md # Ground truth + progress log (appended after each subtask)
- ├── orchestrator_state.md # Conductor's planning state
- ├── execution_context.md # Current task context for executors
- ├── experiment_ledger.md # Experiment history & results
- ├── result_summary.md # Latest results for writing & review
- ├── review_log.md # Review feedback history
- ├── literature_bank.md # Organized paper notes
- ├── agent_handoff.md # Cross-agent handoff messages
- └── decision_log.md # Rejected directions & reasoning
- .pipeline/tasks/
- └── tasks.json # Shared task tree (all roles read/write this)
- ```
- Memory survives across sessions. The `SessionStart` hook reads these files and injects the relevant context — you pick up right where you left off.
- **Auto-sync rule:** The Conductor updates `tasks.json` and `project_truth.md` automatically after every subtask completes (delegate / experiment / survey / write / review). You never need to ask it to sync.
- ---
- ## Codex Delegation
- The Conductor can hand off coding and experiment tasks to Codex:
- ```bash
- /omp:delegate
- ```
- The flow:
- 1. Conductor reads project context and the current task
- 2. Presents task summary — you confirm
- 3. Generates a complete Codex prompt with context pre-injected
- 4. You copy it to a new terminal: `codex "..."`
- 5. Conductor polls for completion (`CODEX_DONE` signal in `agent_handoff.md`)
- 6. Reads result, asks you to accept/revise/reject
- 7. On accept: updates `tasks.json` and `project_truth.md` automatically
- ---
- ## Remote Experiments
- The `remote-experiment` skill + `/omp:experiment` support a full auto-experiment loop:
- ```
- Design plan → Implement code → rsync to server → Run on GPU → Parse metrics → Repeat
- ```
- - SSH/rsync-based remote compute via `compute-helper` CLI
- - Configurable success thresholds, max iterations, and failure limits
- - Results flow back into `experiment_ledger.md` for the Paper Writer
- ---
- ## For LLM Agents
- If you're an AI agent installing this plugin:
- ```bash
- # Step 1: Add marketplace
- /plugin marketplace add LigphiDonk/Oh-my--paper
- # Step 2: Install plugin
- /plugin install omp@oh-my-paper
- # Step 3: Verify installation
- /plugin
- # Should show: omp @ oh-my-paper, Status: Enabled
- # Step 4: User must restart Claude Code (you cannot do this)
- # Tell user: "Please restart Claude Code to activate hooks."
- # Step 5: Initialize project
- /omp:setup
- ```
- ---
- ## Philosophy
- > **Enhance, don't replace.** Claude Code is already smart — we add research structure, not overrides.
- - **Your context is for reasoning** — hooks inject only what's needed; memory files keep the rest on disk
- - **Domain-specific, not generic** — every skill, agent, and command is designed for academic research
- - **Invisible when not needed** — hooks run in the background; no noise if you're just coding
- - **Composable** — use one command, use all of them, or just let the hooks do their thing
- - **Memory over repetition** — agents remember project context so you don't re-explain every session
- ---
- ## Contributing
- PRs welcome. If you add a new skill, put it in `skills/` with proper YAML frontmatter and update `research-catalog.json`.
- Any change to cached content requires version bumps in **both**:
- - `plugins/oh-my-paper/.claude-plugin/plugin.json`
- - `.claude-plugin/marketplace.json`
- ---
- ## Codex Support
- Oh My Paper also ships a **Codex plugin** (`oh-my-paper-codex`) that shares the same research harness concepts, agents, and skills as the Claude Code plugin.
- ### Install on Codex
- **macOS / Linux**
- ```bash
- # 1. Clone the repo
- git clone https://github.com/LigphiDonk/Oh-my--paper.git /tmp/oh-my-paper
- cd /tmp/oh-my-paper
- # 2. One-command install
- ./scripts/install-codex-plugin.sh
- ```
- **Windows (PowerShell)**
- ```powershell
- # 1. Clone the repo
- git clone https://github.com/LigphiDonk/Oh-my--paper.git $env:TEMP\oh-my-paper
- Set-Location $env:TEMP\oh-my-paper
- # 2. One-command install
- powershell -ExecutionPolicy Bypass -File .\scripts\install-codex-plugin.ps1
- ```
- What the installer does:
- - Copies the plugin to `~/plugins/oh-my-paper-codex`
- - Creates or updates `~/.agents/plugins/marketplace.json`
- - Tries to call Codex directly so the plugin becomes installed and enabled immediately
- - Uses `node` under the hood, so make sure `node` is available on your `PATH`
- If `codex` is not available on your `PATH`, the script still registers the plugin and then tells you to finish the last step in Codex's Plugins page. If you search there, search for `Oh My Paper` or `oh-my-paper-codex`, not `omp`.
- ### Use in Codex CLI
- After installation, start Codex in your research project directory:
- ```bash
- cd /path/to/your/research-project
- codex
- ```
- Then use one of these two patterns:
- - Ask naturally, for example: `Use Oh My Paper to initialize this research project and scaffold .pipeline/`
- - Reuse the workflow prompt templates under `plugins/oh-my-paper-codex/prompts/` by copying or adapting them inside the Codex session
- Codex CLI does **not** currently auto-register the files in `plugins/oh-my-paper-codex/prompts/` as slash commands, so `/omp-setup` and similar commands will **not** appear in the CLI command palette.
- ### What's Included
- | Feature | Claude Code | Codex CLI |
- |:---|:---|:---|
- | Agent Roles (5) | `agents/*.md` | `agents/*.toml` |
- | Workflow entrypoints | `/omp:...` slash commands | Natural-language prompts + `prompts/*.md` templates |
- | SessionStart Hook | Native hook | `AGENTS.md` (auto-read) |
- | Skills (34) | ✅ shared | ✅ shared |
- | `.pipeline/` Memory | ✅ | ✅ |
- | Codex Delegation | `/omp:delegate` → new terminal | Native `/agent` subagent |
- ### Key Differences
- - **Hooks**: Codex doesn't have native hooks. The `SessionStart` equivalent is handled by `AGENTS.md` which Codex reads automatically. Stage transition detection is embedded in the agent instructions.
- - **CLI command model**: Claude Code exposes `/omp:...` slash commands. Codex CLI currently does not auto-register the plugin's `prompts/*.md` files as `/omp-*` slash commands, so you use natural-language prompts or copy/adapt the templates manually.
- - **Both can coexist**: The Codex plugin (`plugins/oh-my-paper-codex/`) is completely separate from the Claude Code plugin (`plugins/oh-my-paper/`). Installing one does not affect the other.
- - **Installer scripts**: Use `scripts/install-codex-plugin.sh` on macOS/Linux or `scripts/install-codex-plugin.ps1` on Windows. They merge the marketplace entry instead of overwriting your existing local plugins.
- - **Codex discovery**: Codex expects a valid `~/.agents/plugins/marketplace.json` entry plus a plugin directory under `~/plugins/<plugin-name>/`. Copying files only into `~/.codex/plugins/` is not enough for the plugin UI to discover it.
- - **Codex install state**: A marketplace entry only makes the plugin appear in the Plugins page. You must still install it there before it becomes enabled and usable.
- ---
- ## Uninstall
- **Claude Code:**
- ```bash
- /plugin uninstall omp@oh-my-paper
- ```
- **Codex on macOS / Linux:**
- ```bash
- ./scripts/uninstall-codex-plugin.sh
- ```
- **Codex on Windows (PowerShell):**
- ```powershell
- powershell -ExecutionPolicy Bypass -File .\scripts\uninstall-codex-plugin.ps1
- ```
- ---
- ## License
- MIT. See [LICENSE](./LICENSE).
- ---
- ## Acknowledgments
- Special thanks to the **[Linux.do](https://linux.do)** community for your support and feedback.
- ---
- <p align="center">
- <strong>Oh My Paper</strong> — Where Research Meets the Terminal.
- </p>
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.