AI Gakuen (AI学園)

Table of Contents

• What It Does
• Installation
• Quick Start
• Core Concepts
• Commands
• How Training Works
• Self-Improvement with Reflect
• Example Otaku
• File Structure
• Environment Variables
• Troubleshooting
• Contributing
• Development
• License
• Credits

What It Does

AI Gakuen analyzes your project specs, identifies required expertise domains, and generates specialized agents with:

• Compiled documentation - Distilled from official sources
• Proven patterns - Battle-tested solutions
• Common gotchas - Pitfalls others have hit
• Mental models - How experts think about the domain
• Project-specific context - Tailored to your codebase

Instead of Claude being a generalist, you get laser-focused specialists that deeply understand their domain.

Installation

Option 1: npm (Recommended)

npm install -g aigakuen

Option 2: From Source

git clone https://github.com/ntombisol/aigakuen
cd aigakuen
bun install
bun run build
npm link

Add the Claude Code Skill (Optional)

npx add-skill ntombisol/aigakuen

Requirements

• Node.js 18+ or Bun
• Anthropic API key - Set as ANTHROPIC_API_KEY environment variable
• Claude Code - The Otaku are designed to work with Claude Code's CLAUDE.md system

Quick Start

# 1. Initialize in your project
aigakuen init

# 2. Analyze your spec to get Otaku recommendations
aigakuen enroll ./docs/spec.md

# 3. Train recommended specialists
aigakuen train supabase-auth-otaku
aigakuen train react-hooks-otaku

# 4. Assign a task (auto-routes to best Otaku)
aigakuen assign "implement magic link authentication"

# 5. Use Claude Code normally - CLAUDE.md is now supercharged

Core Concepts

| Term | Japanese | Role | |------|----------|------| | Otaku | オタク | Obsessive expert in ONE narrow domain | | Toshokan | 図書館 | Compiled knowledge library | | Sensei | 先生 | You - provides specs, guides learning | | Iincho | 委員長 | Class President - routes tasks to specialists |

Commands

| Command | Description | |---------|-------------| | aigakuen init | Initialize .gakuen/ in project | | aigakuen enroll <spec> | Analyze spec, recommend Otaku | | aigakuen train <otaku> | Train Otaku with deep research | | aigakuen train-batch --all | Train all untrained Otaku in parallel | | aigakuen retrain <otaku> | Re-train an Otaku (clears existing knowledge) | | aigakuen study <otaku> | Activate an Otaku | | aigakuen assign <task> | Route task to best Otaku | | aigakuen switch <otaku> | Switch Otaku with handoff | | aigakuen handoff | Save session context | | aigakuen reflect | Self-evaluate and improve Otaku knowledge | | aigakuen roster | List all Otaku | | aigakuen homeroom | Status dashboard |

How Training Works

When you train an Otaku, AI Gakuen:

1. Fetches Documentation - Official docs via Context7 MCP
2. Mines GitHub Issues - Common problems and solutions
3. Analyzes Changelogs - Breaking changes, migration gotchas
4. Searches Community - Stack Overflow, blog posts, discussions
5. Synthesizes Knowledge - Patterns, gotchas, mental models via Claude

The result is a specialist who knows not just the API, but the pitfalls and best practices.

Training Modes

aigakuen train <otaku>           # Standard training
aigakuen train <otaku> --quick   # Faster, fewer sources
aigakuen train <otaku> --deep    # More thorough, takes longer

Self-Improvement with Reflect

After a development session, run:

aigakuen reflect

This analyzes your session to find knowledge gaps:

1. Reads session context - handoff notes, git commits
2. Identifies bugs that were fixed - "tried X, didn't work, fixed with Y"
3. Compares against Otaku knowledge - "Should they have known this?"
4. Generates new gotchas - adds to their training data

Example output:

Reflecting on session with: Furi-senpai
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Discovered Issues:
  ⚠️ Safari backface-visibility requires -webkit- prefix
     Cause: Safari doesn't support unprefixed property
     Fix: Add -webkit-backface-visibility: hidden

Knowledge Gaps:
  📚 Safari backface-visibility requires -webkit- prefix
     → This is within Furi-senpai's domain (CSS 3D transforms)
     + New Gotcha: "Safari Requires -webkit-backface-visibility"

Added 1 gotcha(s), 0 pattern(s)

The Otaku learns from real bugs, making them smarter over time.

Example Otaku

After analyzing a flashcard app spec, AI Gakuen might recommend:

• sm2-otaku - SM-2 spaced repetition algorithm specialist
• supabase-auth-otaku - Supabase Auth & RLS policies expert
• service-worker-otaku - PWA caching strategies specialist
• indexeddb-sync-otaku - Offline storage & sync expert

Each has deep, compiled knowledge in their narrow domain.

File Structure

.gakuen/
├── config.json           # Project config
├── handoff.md            # Session continuity
├── curriculum/           # Your specs
├── otaku/
│   ├── registry.json     # Otaku metadata
│   └── profiles/         # Individual profiles
├── toshokan/             # Knowledge libraries
│   └── <otaku-id>/
│       ├── core-knowledge.json
│       ├── patterns/
│       ├── gotchas/
│       └── ...
└── taskboard.json        # Task tracking

Environment Variables

ANTHROPIC_API_KEY=sk-ant-...   # Required - for Claude API calls
GITHUB_TOKEN=ghp_...            # Optional - improves GitHub research quality

Troubleshooting

"ANTHROPIC_API_KEY not set"

Make sure you've exported the environment variable:

export ANTHROPIC_API_KEY=sk-ant-your-key-here

Or add it to your .bashrc / .zshrc for persistence.

Training fails with "rate limit"

Training makes many API calls. If you hit rate limits:

1. Wait a few minutes and retry
2. Use --quick mode for faster training with fewer sources
3. Train Otaku one at a time instead of batch

"Context7 not available"

Context7 MCP is used for documentation fetching. If unavailable:

1. Training will fall back to web search
2. Results may be less comprehensive
3. Consider installing Context7 MCP for better results

Otaku knowledge seems outdated

Re-train the Otaku to fetch fresh documentation:

aigakuen retrain <otaku-id>

CLAUDE.md is too large

If your CLAUDE.md becomes unwieldy with many Otaku:

1. Only keep 1-3 Otaku active at a time
2. Use aigakuen switch to change specialists as needed
3. The roster table is compact; full knowledge only loads for active Otaku

Contributing

Contributions are welcome! Here's how to help:

Reporting Issues

• Use the GitHub Issues page
• Include your Node.js version, OS, and steps to reproduce

Submitting Changes

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Run tests (bun test)
5. Commit with a descriptive message
6. Push to your fork
7. Open a Pull Request

Development Setup

git clone https://github.com/ntombisol/aigakuen
cd aigakuen
bun install
bun run dev  # Run CLI in development mode

Code Style

• TypeScript with strict mode
• Prefer async/await over callbacks
• Use Zod for runtime validation
• Keep commands thin, logic in src/core/

Development

bun install          # Install dependencies
bun run dev          # Run in development mode
bun test             # Run tests
bun run build        # Build for distribution
bun run typecheck    # Type check without emitting

License

MIT - Tonbi Studio

Credits

• Inspired by Steve Yegge's Gas Town multi-agent architecture
• Built for Claude Code by Anthropic
• Documentation powered by Context7