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

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.
   

Key commands your LLM should know:

Command	What It Does
/gyoshu	Start interactive research
/gyoshu-auto <goal>	Autonomous research (hands-off)
/gyoshu doctor	Check system health and diagnose issues

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.

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)

Command	What It Does
/gyoshu	Show status and what to do next
/gyoshu <goal>	Start interactive research
/gyoshu-auto <goal>	Autonomous mode (set it and forget it!)
/gyoshu plan <goal>	Just create a plan, don't execute
/gyoshu continue	Pick up where you left off
/gyoshu report	Generate research report
/gyoshu list	See all your research projects
/gyoshu search <query>	Find stuff across all notebooks
/gyoshu doctor	Check system health and diagnose issues

Research Modes

Mode	Best For	Command
🎓 Interactive	Learning, exploring, iterating	/gyoshu <goal>
🤖 Autonomous	Clear goals, hands-off execution	/gyoshu-auto <goal>
🔧 REPL	Quick exploration, debugging	/gyoshu repl <query>

---

🔬 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

Marker	Purpose	Example
[OBJECTIVE]	Research goal	[OBJECTIVE] Classify iris species
[HYPOTHESIS]	What you're testing	[HYPOTHESIS] H0: no difference; H1: petal length predicts species
[DATA]	Dataset info	[DATA] Loaded 150 samples
[FINDING]	Key discovery	[FINDING] Setosa is linearly separable (d=2.1, p<0.001)
[CONCLUSION]	Final verdict	[CONCLUSION] Hypothesis confirmed with large effect

Statistical Evidence Markers (Required for Verified Findings)

Marker	Purpose	Example
[STAT:ci]	Confidence interval	[STAT:ci] 95% CI [0.82, 0.94]
[STAT:effect_size]	Effect magnitude	[STAT:effect_size] Cohen's d = 0.75 (medium)
[STAT:p_value]	Statistical significance	[STAT:p_value] p = 0.003
[SO_WHAT]	Practical significance	[SO_WHAT] This means 15% cost reduction
[LIMITATION]	Threats to validity	[LIMITATION] Small sample size (n=50)

ML Pipeline Markers

Marker	Purpose	Example
[METRIC:baseline_*]	Dummy model benchmark	[METRIC:baseline_accuracy] 0.33
[METRIC:cv_*]	Cross-validation scores	[METRIC:cv_accuracy_mean] 0.95

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

Requirement	Penalty if Missing	Why It Matters
CI for findings	-30 trust	Point estimates without uncertainty are misleading
Effect size for findings	-30 trust	Statistical significance ≠ practical significance
Baseline for ML	-20 trust	Can't claim improvement without a reference point
Cross-validation for ML	-25 trust	Single train/test split can be lucky

Trust Score Thresholds

Score	Status	What Happens
≥ 80	✅ Verified	Finding accepted as key result
60-79	⚠️ Partial	Accepted with caveats
< 60	❌ Rejected	Marked as exploratory, requires rework

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

---

🐍 Python Environment

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

Priority	Type	How It's Detected
1️⃣	venv	.venv/bin/python exists

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

Platform	Status	Notes
Linux	✅ Primary	Tested on Ubuntu 22.04+
macOS	✅ Supported	Intel & Apple Silicon
Windows	⚠️ WSL2 Only	Native Windows not supported

---

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

Tool	Focus	Independent?
Gyoshu (this project)	📊 Research & Analysis	✅ Fully standalone
Oh-My-OpenCode	🏗️ Product Development	✅ Fully standalone

Gyoshu's Own Agent Stack

Gyoshu includes everything it needs for research:

Agent	Role	What They Do
@gyoshu	Professor	Plans research, orchestrates workflow
@jogyo	TA	Executes Python code, runs experiments
@baksa	PhD Reviewer	Challenges claims, verifies evidence
@jogyo-insight	Evidence Gatherer	Searches docs, finds examples
@jogyo-feedback	Learning Explorer	Reviews past sessions for patterns
@jogyo-paper-writer	Report Writer	Transforms findings into narrative reports

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"

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

Issue	Solution
"No .venv found"	Create a virtual environment: python3 -m venv .venv && .venv/bin/pip install pandas numpy
"Bridge failed to start"	Check Python version (need 3.10+): python3 --version. Check socket path permissions.
"Session locked"	Use /gyoshu unlock <sessionId> after verifying no process is running
OpenCode not in PATH	Install from opencode-ai/opencode

Still stuck? Run /gyoshu doctor to diagnose issues.

---

📄 License

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

---

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

Report Bug · Request Feature · Documentation