🎓 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
| Agent | Role | Korean | What They Do |
|---|
| Gyoshu | 🎩 Professor | 교수 | Plans research, orchestrates workflow, manages sessions |
| Jogyo | 📚 Teaching Assistant | 조교 | Executes Python code, runs experiments, generates outputs |
| Baksa | 🔍 PhD Reviewer | 박사 | Adversarial verifier — challenges claims, calculates trust scores |
| Jogyo Paper Writer | ✍️ Grad Student | 조교 | Transforms raw findings into narrative research reports |
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:
| Tool | Purpose |
|---|
python_repl | Execute Python code with marker detection |
research_manager | Create/manage research sessions |
gyoshu_snapshot | Capture research state snapshots |
checkpoint_manager | Save/restore research checkpoints |
notebook_writer | Jupyter notebook operations |
notebook_search | Search across notebooks |
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.
📦 Development installation (for contributors)
Clone & link locally:
git clone https://github.com/Yeachan-Heo/My-Jogyo.git
cd My-Jogyo && bun install
Then in your opencode.json:
{
"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:
-
Point your LLM to the guide:
"Read AGENTS.md in the Gyoshu directory for full context on how to use the research tools."
-
Or paste this quick start prompt:
I've installed Gyoshu. Read AGENTS.md and help me run /gyoshu to analyze my data.
