🎓 Gyoshu & Jogyo

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

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:

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

FilesExpand file tree

README.md

Latest commit

History