gyoshu

🎓 Gyoshu & Jogyo

English | 中文 | 한국어 | 日本語

"Every great professor needs a great teaching assistant."

Gyoshu (교수, Professor) orchestrates. Jogyo (조교, Teaching Assistant) executes.

Together, they form an end-to-end research automation system for OpenCode that turns your research goals into reproducible Jupyter notebooks—complete with hypotheses, experiments, findings, and publication-ready reports.

🎭 The Cast

Think of it like a research lab:

• The Professor (Gyoshu) sets the research direction and reviews progress
• The TA (Jogyo) does the actual experiments and analysis
• The PhD Reviewer (Baksa) plays devil's advocate, questioning every claim
• When it's time to publish, a Grad Student writes up the findings beautifully

✨ Features

🎬 Demo coming soon! Try the Quick Tutorial to see Gyoshu in action.

• 🔬 Hypothesis-Driven Research — Structure your work with [OBJECTIVE], [HYPOTHESIS], [FINDING] markers
• 🐍 Persistent Python REPL — Variables survive across sessions, just like a real Jupyter kernel
• 📓 Auto-Generated Notebooks — Every experiment is captured as a reproducible .ipynb
• 🤖 Autonomous Mode — Set a goal, walk away, come back to results
• 🔍 Adversarial Verification — PhD reviewer challenges every claim before acceptance
• 🎯 Two-Gate Completion — SUCCESS requires both evidence quality (Trust Gate) AND goal achievement (Goal Gate)
• 📝 AI-Powered Reports — Turn messy outputs into polished research narratives
• 🔄 Session Management — Continue, replay, or branch your research anytime

🚀 Installation

Option 1: Claude Code (MCP Server)

Gyoshu works with Claude Code via the Model Context Protocol (MCP). Install in one command:

# Clone and build the MCP server
git clone https://github.com/Yeachan-Heo/My-Jogyo.git
cd My-Jogyo/src/mcp
npm install && npm run build

# Register with Claude Code
claude mcp add gyoshu-mcp "$(pwd)/build/index.cjs"

Verify installation:

claude mcp list
# Should show: gyoshu-mcp: ✓ Connected

Available MCP Tools:

Note: The MCP server exposes 12 research tools. See src/mcp/ for details.

Option 2: OpenCode Plugin

Add Gyoshu to your opencode.json:

{
  "plugin": ["gyoshu"]
}

That's it! OpenCode will auto-install Gyoshu from npm on next startup.

Option 3: CLI Installer

# Using bunx (no global install needed)
bunx gyoshu install

# Or install globally first
npm install -g gyoshu
gyoshu install

The CLI automatically adds Gyoshu to your opencode.json.

git clone https://github.com/Yeachan-Heo/My-Jogyo.git
cd My-Jogyo && bun install

{
  "plugin": ["file:///path/to/My-Jogyo"]
}

Verify installation:

# Check status via CLI
bunx gyoshu check

# Or in OpenCode
opencode
/gyoshu doctor

🤖 Installation for LLMs

Using Claude Code, OpenCode, or another AI coding assistant? This section is for you.

For Claude Code: Install the MCP server (Option 1 above). The tools are automatically available.

For OpenCode: Run bunx gyoshu install or add "gyoshu" to your plugin array. Then give your LLM the context it needs:

1. Point your LLM to the guide:

   "Read AGENTS.md in the Gyoshu directory for full context on how to use the research tools."

2. Or paste this quick start prompt:

   I've installed Gyoshu. Read AGENTS.md and help me run /gyoshu to analyze my data.