扫码加入交流群

A research harness for Claude Code — turn your terminal into an autonomous research lab.

中文文档

# 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.

• Why This Exists
• Install
• Claude Code Slash Commands
• The Agent Team
• 34 Research Skills
• Hooks
• Research Pipeline
• Project Scaffold
• How Memory Works
• Codex Delegation
• Remote Experiments
• For LLM Agents
• Philosophy
• Contributing
• Uninstall

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.

/plugin marketplace add LigphiDonk/Oh-my--paper

/plugin install omp@oh-my-paper

Required for hooks to activate.

/omp:setup

This scaffolds the .pipeline/ directory and registers the SessionStart hook for your project.

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

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

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:.

/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

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.

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.

Skills are structured instruction sets that Claude loads on demand. Each skill is a markdown file covering a specific research task.

Skills are auto-recommended based on your current pipeline stage. Add project-local skills in the skills/ directory.

Oh My Paper registers three hooks that run in the background:

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.

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

/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

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.

The Conductor can hand off coding and experiment tasks to Codex:

/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

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

If you're an AI agent installing this plugin:

# 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

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

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

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.

macOS / Linux

# 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)

# 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.

After installation, start Codex in your research project directory:

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.

• 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.

Claude Code:

/plugin uninstall omp@oh-my-paper

Codex on macOS / Linux:

./scripts/uninstall-codex-plugin.sh

Codex on Windows (PowerShell):

powershell -ExecutionPolicy Bypass -File .\scripts\uninstall-codex-plugin.ps1

MIT. See LICENSE.

Special thanks to the Linux.do community for your support and feedback.

Oh My Paper — Where Research Meets the Terminal.