gyoshu

"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

<!-- TODO: Add demo GIF showing /gyoshu-auto workflow --> <p align="center"> <em>🎬 Demo coming soon! Try the <a href="docs/user-guide.md">Quick Tutorial</a> to see Gyoshu in action.</em> </p>

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

<details> <summary>📦 Development installation (for contributors)</summary>

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"]
}

</details>

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

1. Or paste this quick start prompt:

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

Key commands your LLM should know:

Tip: AGENTS.md contains everything an LLM needs — agents, commands, markers, troubleshooting, and more.

🏃 Quick Start

# Start OpenCode
opencode

# 👋 Say hi to the Professor
/gyoshu

# 🎯 Start a new research project
/gyoshu analyze customer churn patterns in the telecom dataset

# 🤖 Or let it run autonomously (hands-off!)
/gyoshu-auto classify iris species using random forest

# 📊 Generate a report
/gyoshu report

# 🔄 Continue where you left off
/gyoshu continue

📚 Examples

Binance Futures Comprehensive EDA

Real-world example: Comprehensive exploratory data analysis of Binance USD-M futures data with multi-dimensional visualizations.

<p align="center"> <img src="examples/binance-futures-eda.png" alt="Binance Futures EDA Dashboard" width="800"> </p>

What it shows:

• •3D volume-price-time analysis
• •Correlation heatmaps with dendrograms
• •Rolling statistics and volatility surfaces
• •Cross-pair scatter density plots
• •Performance radar charts and candlestick analysis

Try It Yourself

# Binance futures analysis (API or local data)
/gyoshu-auto perform comprehensive EDA on binance futures data

# Titanic classification (classic ML workflow)
/gyoshu-auto analyze Titanic survival data and build classification model

# Iris clustering (no download needed - sklearn built-in)
/gyoshu-auto cluster iris dataset and visualize results

📖 Commands

The Professor's Commands (/gyoshu)

Research Modes

🔬 How Research Works

1. You Set a Goal

/gyoshu analyze wine quality factors and build a predictive model

2. The Professor Plans

Gyoshu creates a structured research plan with clear objectives and hypotheses.

3. The TA Executes

Jogyo runs Python code, using structured markers to organize output:

print("[OBJECTIVE] Predict wine quality from physicochemical properties")
print("[HYPOTHESIS] Alcohol content is the strongest predictor")

# ... analysis code ...

print(f"[METRIC:accuracy] {accuracy:.3f}")
print("[FINDING] Alcohol shows r=0.47 correlation with quality")
print("[CONCLUSION] Hypothesis supported - alcohol is key predictor")

4. Auto-Generated Notebook

Everything is captured in notebooks/wine-quality.ipynb with full reproducibility.

5. AI-Written Report

The Paper Writer agent transforms markers into a narrative report:

"Our analysis of 1,599 wine samples revealed that alcohol content emerges as the dominant predictor of quality ratings (r = 0.47). The final Random Forest model achieved 87% accuracy..."

📁 Project Structure

your-project/
├── notebooks/                    # 📓 Research notebooks
│   ├── wine-quality.ipynb
│   └── customer-churn.ipynb
├── reports/                      # 📝 Generated reports
│   └── wine-quality/
│       ├── report.md             # AI-written narrative report
│       ├── figures/              # Saved plots
│       └── models/               # Saved models
├── data/                         # 📊 Your datasets
└── .venv/                        # 🐍 Python environment

Runtime files (sockets, locks) go to OS temp directories—not your project! 🧹

What Gyoshu Creates

When you run research, Gyoshu creates these artifacts in your project:

your-project/
├── notebooks/
│   └── your-research.ipynb    ← Research notebook (source of truth)
├── reports/
│   └── your-research/
│       ├── figures/           ← Saved plots (.png, .svg)
│       ├── models/            ← Trained models (.pkl, .joblib)
│       └── report.md          ← Generated research report
└── (your existing files untouched!)

Note: Gyoshu never modifies your .venv/, data/, or other existing project files.

🎯 Output Markers

The TA uses structured markers to organize research output:

Core Markers

Statistical Evidence Markers (Required for Verified Findings)

ML Pipeline Markers

Quality Gate: Findings without [STAT:ci] and [STAT:effect_size] are marked as "Exploratory" in reports.

🔬 Research Quality

Gyoshu enforces senior data scientist level quality through automated quality gates. Every claim requires statistical evidence.

The Finding Gating Rule

⚠️ No `[FINDING]` is accepted without:

- [STAT:ci] — Confidence interval (within 10 lines before)

- [STAT:effect_size] — Effect magnitude (within 10 lines before)

Findings that fail these checks are downgraded to "Exploratory Observations" in reports.

Quality Standards

Trust Score Thresholds

Learn more: See AGENTS.md for complete marker reference and statistical requirements.

🐍 Python Environment

Gyoshu uses your project's .venv/ virtual environment:

Quick setup:

python3 -m venv .venv
.venv/bin/pip install pandas numpy scikit-learn matplotlib seaborn

Note: Gyoshu uses your project's virtual environment. It never modifies system Python.

🛠️ Requirements

• •Claude Code or OpenCode v0.1.0+
• •Python 3.10+
• •Node.js 18+ (for MCP server)
• •Optional: psutil (for memory tracking)

Supported Platforms

🔄 Updating

Gyoshu is distributed via npm. OpenCode automatically handles plugin updates.

Force update:

# Clear OpenCode's cache
rm -rf ~/.cache/opencode/node_modules/gyoshu

# Or reinstall with latest version
bunx gyoshu@latest install

Then restart OpenCode.

Verify: opencode then /gyoshu doctor

Uninstall:

bunx gyoshu uninstall

See CHANGELOG.md for what's new.

🎓 Why "Gyoshu" and "Jogyo"?

In Korean academia:

• •교수 (Gyoshu/Kyosu) = Professor — the one who guides, plans, and oversees
• •조교 (Jogyo) = Teaching Assistant — the one who executes, experiments, and does the heavy lifting

This reflects the architecture: Gyoshu is the orchestrator agent that plans and manages research flow, while Jogyo is the executor agent that actually runs Python code and produces results.

It's a partnership. The Professor has the vision. The TA makes it happen. Together, they publish papers. 📚

🤝 Optional Companion: Oh-My-OpenCode

Gyoshu works completely standalone. It has its own agent stack and requires no other OpenCode extensions (like oh-my-opencode).

For data-driven product development workflows, you can optionally combine Gyoshu with Oh-My-OpenCode:

Gyoshu's Own Agent Stack

Gyoshu includes everything it needs for research:

Optional Workflow (When Combined)

If you choose to use both tools together:

1. Research with Gyoshu:

`` /gyoshu-auto analyze user behavior and identify churn predictors `` → Produces insights: "Users who don't use feature X within 7 days have 3x churn rate"

1. Build with Oh-My-OpenCode:

`` /planner implement onboarding flow that guides users to feature X `` → Ships the feature that addresses the insight

Data informs decisions. Code ships solutions. 🚀

Note: You do NOT need Oh-My-OpenCode to use Gyoshu. Each tool works independently.

🔧 Troubleshooting

Still stuck? Run /gyoshu doctor to diagnose issues.

📄 License

MIT — Use it, fork it, teach with it!

<div align="center">

Made with 🎓 for researchers who'd rather think than type

Report Bug · Request Feature · Documentation

</div>