Teach-first mentor mode for AI coding tools. Socratic questions before code, drills from your own source.
chiron (pronounced KAI-ron, hard K — the centaur who mentored Achilles, Hercules, Jason, and Asclepius) turns coding requests into deliberate practice. Instead of shipping code, it asks the questions a senior engineer would ask — then walks you through the decision, hint by hint, until you've written the answer yourself.
chiron never auto-activates. It only fires when you explicitly type one of its slash commands. This is by design: a plugin should not change your default coding-assistant behavior without your consent.
/plugin marketplace add xDido/chiron
/plugin install chiron@chiron
That's it — no clone required. Claude Code fetches .claude-plugin/marketplace.json from GitHub directly. Verify with /plugin — chiron@chiron should show as enabled.
chiron ships pre-built skills for 13 platforms. Clone the repo and copy the matching directory into your project:
git clone https://github.com/xDido/chiron.git| Platform | Copy this directory | Status |
|---|---|---|
| Cursor | .cursor/skills/ |
supported |
| Gemini CLI | .gemini/skills/ |
supported |
| Codex CLI | .codex/skills/ |
supported |
| OpenCode | .opencode/skills/ |
supported |
| GitHub Copilot Agents | .agents/skills/ |
supported |
| Pi | .pi/skills/ |
supported |
| Rovo Dev | .rovodev/skills/ |
supported |
| VS Code Copilot | .github/skills/ |
supported |
| Kiro | .kiro/skills/ |
community (no formal skills docs) |
| OpenAI | .openai/skills/ |
experimental |
| Trae | .trae/skills/ |
experimental (no official skills docs) |
| Trae CN | .trae-cn/skills/ |
experimental (no official skills docs) |
For per-platform frontmatter support, directory-fallback behavior, and the latest compatibility notes, see HARNESSES.md.
Faster install (skip the full clone): use scripts/install.js after cloning to copy a single platform directory:
node scripts/install.js --platform cursor --dest /path/to/your-projectOr do it by hand — example for Cursor:
cp -r chiron/.cursor/skills/ your-project/.cursor/skills/If you modify the source skills in source/skills/, rebuild all platform outputs:
bun scripts/build.jsThis generates skill files for all 13 platforms from the single source of truth in source/skills/.
Run /teach-chiron once per project. It scans your codebase and writes .chiron-context.md — a persistent reference all other commands read instead of re-scanning. Then use any of the eleven commands below.
| Command | Purpose |
|---|---|
/teach-chiron |
One-time project scan, writes .chiron-context.md |
/chiron |
Socratic mentor mode for one coding request |
/challenge |
Drills graded /10 from your own source code |
/hint |
Advance one rung on the L0–L4 hint ladder |
/level |
Set voice intensity (gentle / default / strict) |
/explain |
Compare 2–3 approaches with trade-offs |
/postmortem |
Session-end review across 5 axes |
/tour |
Read-first preamble for a topic |
/debug |
Hypothesis-driven debugging methodology |
/refactor |
Identify code smells, guide named refactorings |
/architect |
Architecture decision records with trade-offs |
Teach a new pattern:
/teach-chiron # one-time per project
/chiron implement a worker pool in Go # Socratic walkthrough
/hint # advance to next rung
/postmortem # session review
Drill on existing code:
/challenge path/to/worker_pool.go # 1–3 drills, graded /10
/hint # if stuck mid-drill
Decide before you build:
/tour Go channels # background reading
/explain REST vs gRPC for this service # quick comparison
/architect "event sourcing for orders?" # full ADR with quality attributes
/chiron implement the chosen approach # guided implementation
Improve existing code:
/refactor path/to/handler.go # name the smell, guide the change
/debug "connection refused after deploy" # observe → hypothesize → verify → fix
Tune chiron's voice:
/level strict # firm, terse, two attempts before L4
/level # show current + all options
Every command preserves three invariants: never refuses to ship when asked, never moralizes, never pollutes code with teaching content (lessons live in chat). Defers to CLAUDE.md / AGENTS.md when they conflict.
If you want chiron voice across every coding request in a project without typing /chiron each time, paste this into your project's CLAUDE.md:
For coding requests in this repo, follow the teach-first mentor behavior from the chiron plugin: ask Socratic clarifying questions before writing code, use the hint ladder before giving full solutions, and call out idioms worth remembering.
This is opt-in via your own configuration — chiron does not auto-activate under any circumstances.
chiron reads one configuration file: ~/.chiron/config.json. It's created automatically the first time you run /level <value>. Current schema (v0.13.0):
{
"schema_version": 1,
"voice_level": "default",
"drill": {
"max_lines_changed": 20,
"max_functions_touched": 1,
"time_minutes_min": 5,
"time_minutes_max": 15
},
"teaching": {
"depth": 5,
"theory_ratio": 3,
"idiom_strictness": 5
}
}Fields:
voice_level— one of"gentle","default","strict". Managed by/level. Affects voice tone, hint ladder progression, and refusal behavior.drill(new in v0.2.1) — drill sizing overrides for/challenge. Every field is optional; missing fields fall back to hardcoded defaults. Invalid values (negative, zero, non-integer, out of range) silently fall back without crashing.drill.max_lines_changed— max lines of change per drill (default 20, clamped [1, 100])drill.max_functions_touched— max functions touched per drill (default 1, clamped [1, 5])drill.time_minutes_min— estimated minimum time (default 5, clamped [1, 60])drill.time_minutes_max— estimated maximum time (default 15, clamped [1, 60])- If
time_minutes_min > time_minutes_max, both fields silently fall back to defaults.
Edit the file directly with any text editor, or use /level to manage voice_level. If the file is missing or corrupt, chiron silently falls back to default behavior — no errors.
teaching(new in v0.12.0) — teaching intensity overrides. Every field is optional; missing fields fall back to defaults. Read by/chiron,/challenge,/explain, and/tour.teaching.depth— how deep Socratic questioning goes (default 5, clamped [1, 10]). 1 = quick answers, 10 = full architectural discussion before code.teaching.theory_ratio— how much theory accompanies code (default 3, clamped [1, 10]). 1 = practical-only, 10 = theory-enriched with historical context.teaching.idiom_strictness— how pedantic about language conventions (default 5, clamped [1, 10]). 1 = any working approach is fine, 10 = must use canonical idiomatic form.
Future v0.2.x releases will add more fields (grading thresholds, hint tuning, etc.) without breaking the schema; existing entries stay valid.
Not to be confused with ~/.chiron/profile.json — that file is the append-only drill log written by /challenge. They're independent files with different schemas and lifecycles.
Generated by /teach-chiron. Contains a comprehensive snapshot of the project — structure, dependencies, architecture, patterns, config. All chiron skills read this instead of re-scanning the codebase.
- Auto-generated — don't edit manually
- Project-specific — lives in the project root, not global
- Add to
.gitignore— it's machine-generated and developer-specific - Delete to refresh — next
/teach-chironrun regenerates it
chiron stores only two files outside your project directory, both under ~/.chiron/:
| File | Written by | Contains | Transmitted? |
|---|---|---|---|
~/.chiron/config.json |
/level + manual edits |
voice_level, drill sizing, teaching intensity (see schema above). No identifiers, no user data. |
No. |
~/.chiron/profile.json |
/challenge Step 8 |
schema_version, and an append-only entries array of {ts, project, kind, tag, note, source}. tag is a <language>:<idiom> label (e.g. go:errgroup-with-context), note is ≤140 chars of drill outcome. No code, no secrets, no user identifier. |
No. |
Both files are local-only. No chiron skill calls the network, reads credentials, or exfiltrates file contents. Inspect either file directly to audit — they're plain JSON.
Every file under ~/.chiron/ carries a top-level schema_version integer. Breaking changes bump it; additive field additions do not. A single canonical writer owns each file — /level for config.json, /challenge Step 8 for profile.json — and every write passes through a versioned migration pipeline. Reads are permissive; writes refuse to downgrade.
| File | Current | Supported on read | Notes |
|---|---|---|---|
~/.chiron/config.json |
1 | 1 (and unversioned legacy — treated as 1) | Additive only so far. New fields like drill.* (v0.2.1) and teaching.* (v0.12.0) were added without a version bump. |
~/.chiron/profile.json |
2 | 1, 2 | v1 carried an unused install_id UUID. v2 drops it. /challenge Step 8 migrates v1 → v2 automatically on the next write. |
Migration: profile.json v1 → v2 (shipped v0.16.0).
Earlier builds wrote a UUID install_id to profile.json. /challenge Step 8 now detects any of these conditions as "legacy v1": install_id present, schema_version === 1, or schema_version missing. On the next drill write, /challenge strips install_id, sets schema_version: 2, preserves entries[] verbatim, and surfaces a one-line note ("profile.json migrated from schema_version 1 to 2 (install_id removed)"). You can also scrub manually: delete the install_id line, set schema_version: 2, or delete the whole file to start fresh.
Forward-compat safety. A file whose schema_version exceeds what the installed chiron understands is treated as belonging to a newer version — chiron refuses to write to it, to avoid downgrading a file produced by a newer release. You'll see a terse message pointing at the file; update chiron or hand-edit if you need to continue.
Corrupt files. /challenge Step 8 renames an unreadable profile.json to profile.json.broken.<timestamp> and starts a fresh log (your original data is preserved for manual recovery). /level never renames or deletes config.json — if it fails to parse, /level stops and asks you to fix or delete the file by hand, since config values are often hand-tuned.
Every release ships a SHA-256 manifest at .claude-plugin/INTEGRITY.json covering every shipped skill file and the plugin manifest. To verify a checkout matches what the maintainer committed:
bun run verify # or: node scripts/verify-integrity.jsA non-zero exit lists any file whose hash diverged from the manifest. CI runs the same check on every PR, so a drive-by edit to a SKILL.md without regenerating the manifest fails the build.
For higher assurance, verify the release tag signature before trusting the tree:
git tag -v v0.16.0If you're installing via /plugin marketplace add xDido/chiron, the trust anchor is GitHub's copy of the main branch — bun run verify still catches tampering after install.
chiron is opinionated. It asks hard questions before writing code. It refuses to give you the full answer until you've tried — even if you insist. If that's not what you want, just don't type /chiron. Use /challenge on its own for the drill mechanism without the conversational mentor, or skip chiron entirely and keep using Claude Code normally.
The plugin's job is not to make you feel smart. It's to make you think like a senior engineer, one small decision at a time.
Plugins that inject thousands of tokens into every prompt cost real money — and chiron is deliberate about keeping that cost low.
Most commands are small. /chiron, /hint, /explain, /level, /postmortem, and /tour are each ~1,000–2,500 words. They load once when you invoke the slash command and add negligible cost to a conversation.
/challenge loads language packs on demand. Rather than bundling all 9 language packs into one massive prompt, /challenge detects your file's language and loads only the relevant pack at runtime. A Go challenge loads the Go pack (~200 lines); a TypeScript challenge loads the TypeScript + JavaScript packs. The rest stay on disk.
| Command | Prompt size | Approx. tokens |
|---|---|---|
/chiron |
~2,500 words | ~3.3k |
/challenge (core) |
~340 lines | ~4.5k |
| + one language pack | ~200 lines | ~1.5k |
/explain |
~1,000 words | ~1.4k |
/hint, /level, /tour, /postmortem |
~1,000 words each | ~1.3–1.5k |
/debug |
~2,200 words | ~2.9k |
/refactor |
~2,100 words | ~2.8k |
/architect |
~2,300 words | ~3.0k |
For comparison, /challenge before v0.7.0 loaded all 9 packs on every invocation (~17.5k tokens). The on-demand architecture reduced that by 59–67%.
/teach-chiron scans once, all skills reuse. The first /teach-chiron invocation reads the full codebase and writes .chiron-context.md. Every subsequent skill invocation reads that one file instead of re-scanning. No redundant reads across sessions.
If your project's CLAUDE.md or AGENTS.md contains instructions that conflict with chiron's behavior (e.g., "don't use Socratic questioning, just write the code"), your instructions win. Every chiron skill file states this deferral explicitly at the top.
chiron ships with comprehensive language packs for nine languages. Run /challenge path/to/file.<ext> on any supported file:
| Language | Extensions | Pack |
|---|---|---|
| Go | .go |
docs/languages/go.md |
| Rust | .rs |
docs/languages/rust.md |
| Python | .py |
docs/languages/python.md |
| JavaScript | .js, .mjs, .cjs |
docs/languages/javascript.md |
| TypeScript | .ts, .tsx |
docs/languages/typescript.md |
| Java | .java |
docs/languages/java.md |
| C# | .cs |
docs/languages/csharp.md |
| Kotlin | .kt, .kts |
docs/languages/kotlin.md |
| Swift | .swift |
docs/languages/swift.md |
Each pack includes: stdlib anchors, 25–30 idioms, 20–25 common anti-patterns, mental-model deltas, and 12–17 challenge seeds. TypeScript files also match JavaScript seeds — both packs are consulted.
Want to add Zig, Ruby, Elixir, or something else? See docs/CONTRIBUTING-LANGUAGE-PACKS.md for the authoring guide and start from docs/languages/_template.md.
Beyond language idioms, /challenge also detects backend patterns from your imports and loads domain-specific concept packs alongside the language pack. This happens automatically — no extra flags needed.
| Pack | Domain | Seeds | Auto-detects |
|---|---|---|---|
database.md |
SQL/NoSQL patterns | 14 | database/sql, sqlalchemy, prisma, hibernate, ... |
api-design.md |
HTTP/REST/gRPC | 14 | net/http, express, fastapi, spring-web, ... |
reliability.md |
Retries, circuit breakers, timeouts | 12 | gobreaker, tenacity, resilience4j, Polly, ... |
observability.md |
Logging, metrics, tracing | 12 | zap, pino, slf4j, opentelemetry, ... |
security.md |
Auth, secrets, validation | 12 | crypto, jwt, bcrypt, spring-security, ... |
testing.md |
Integration & contract testing | 12 | testcontainers, supertest, wiremock, ... |
messaging.md |
Queues, events, pub/sub | 12 | kafka-go, amqplib, celery, spring-kafka, ... |
caching.md |
Cache patterns | 12 | go-redis, ioredis, caffeine, StackExchange.Redis, ... |
configuration.md |
Env vars, feature flags, config validation | 10 | viper, dotenv, pydantic_settings, IOptions, ... |
concurrency.md |
Race conditions, locks, thread safety | 12 | sync.Mutex, threading, java.util.concurrent, tokio::sync, ... |
realtime.md |
WebSockets, SSE, streaming | 10 | gorilla/websocket, socket.io, SignalR, tokio-tungstenite, ... |
storage.md |
File/object storage, uploads | 10 | boto3, @aws-sdk/client-s3, multer, Azure.Storage.Blobs, ... |
Up to 2 concept packs are loaded per invocation (on top of the language pack). If your file doesn't import any backend libraries, only the language pack is used.
chiron's development roadmap from empty repo to v0.1 MVP lives in ROADMAP.md. It tracks phase-by-phase progress (scaffolding → commands → language pack → verification → public release) and lists v0.2+ candidate features that are intentionally not in v0.1.
Shipped: /teach-chiron, /chiron, /hint, /challenge, /level, /explain, /postmortem, /tour, /debug, /refactor, /architect — eleven skills, nine language packs, twelve backend concept packs, seven reference files, and persistent project context.
On deck:
chiron-revieweragent — review your code the way a senior engineer would- Pre-edit hook for strict-mode guardrails
- Additional language packs (Ruby, Zig, Elixir — community-driven)
See ROADMAP.md for the full history and future bundles.
Chiron's design is grounded in pedagogical research and prompt engineering literature. Every core mechanism — the hint ladder, voice levels, drills, grading, session review, profile tracking — is backed by a specific finding from the references below. The full mapping of research to chiron mechanisms lives in source/skills/chiron/references/pedagogy.md.
- Ebbinghaus, H. (1885). Über das Gedächtnis: Untersuchungen zur experimentellen Psychologie. — The forgetting curve. Informs chiron's profile tracking and recency weighting.
- Vygotsky, L.S. (1978). Mind in Society: The Development of Higher Psychological Processes. Harvard University Press. — Zone of Proximal Development. The hint ladder targets ZPD boundaries: L0 probes them, L1–L3 operate within them, L4 steps outside them.
- Wood, D., Bruner, J.S., & Ross, G. (1976). The Role of Tutoring in Problem Solving. Journal of Child Psychology and Psychiatry, 17, 89–100. — Coined "scaffolding." Chiron's hint ladder is contingent tutoring in action — reduce help as the learner succeeds, offer more when they fail.
- Deci, E.L., & Ryan, R.M. (1985). Intrinsic Motivation and Self-Determination in Human Behavior. Plenum Press. — Self-Determination Theory. The never-refuse rule preserves learner autonomy, which drives intrinsic motivation.
- Sweller, J. (1988). Cognitive Load During Problem Solving: Effects on Learning. Cognitive Science, 12(2), 257–285. — Cognitive Load Theory. Chiron's progressive disclosure (one rung at a time) manages extraneous load and frees germane load for learning.
- Ericsson, K.A., Krampe, R.T., & Tesch-Römer, C. (1993). The Role of Deliberate Practice in the Acquisition of Expert Performance. Psychological Review, 100(3), 363–406. — Deliberate practice.
/challengedrills are targeted, feedback-equipped, edge-of-ability tasks — the four conditions for expertise development. - Chi, M.T.H., De Leeuw, N., Chiu, M., & LaVancher, C. (1994). Eliciting Self-Explanations Improves Understanding. Cognitive Science, 18(3), 439–477. — Self-explanation effect. L0 clarifying questions force learners to articulate their own thinking before receiving guidance.
- Kalyuga, S., Ayres, P., Chandler, P., & Sweller, J. (2003). The Expertise Reversal Effect. Educational Psychologist, 38(1), 23–31. — Instructional techniques that help novices harm experts. Chiron's voice levels (gentle/default/strict) and domain-vocabulary detection address this directly.
- Roediger, H.L., & Karpicke, J.D. (2006). The Power of Testing Memory: Basic Research and Implications for Educational Practice. Perspectives on Psychological Science, 1(3), 181–210. — Testing effect. Retrieval practice outperforms re-study by 50–80% for long-term retention. Drills are a retrieval practice.
- Cepeda, N.J., Pashler, H., Vul, E., Wixted, J.T., & Rohrer, D. (2006). Distributed Practice in Verbal Recall Tasks: A Review and Quantitative Synthesis. Psychological Bulletin, 132(3), 354–380. — Modern meta-analysis of spacing effect. Profile read-loop's recency weighting (30-day window, 50% weight for older entries) follows this research.
- Paul, R., & Elder, L. (2006). The Thinker's Guide to the Art of Socratic Questioning. Foundation for Critical Thinking. — Six types of Socratic questions.
/chiron's L0 questions draw from the clarification, assumptions, and implications categories most often. - Bjork, E.L., & Bjork, R.A. (2011). Making Things Hard on Yourself, But in a Good Way: Creating Desirable Difficulties to Enhance Learning. In Psychology and the Real World (pp. 56–64). Worth Publishers. — The hint ladder withholding answers is a desirable difficulty; never refusing when asked keeps it from becoming undesirable.
- Kapur, M. (2014). Productive Failure in Learning Math. Cognitive Science, 38(4), 627–658. — Struggling before receiving instruction yields deeper learning. L3's signature-with-blanks creates exactly this kind of productive failure.
- Wei, J., Wang, X., Schuurmans, D., Bosma, M., Ichter, B., Xia, F., Chi, E., Le, Q., & Zhou, D. (2022). Chain-of-Thought Prompting Elicits Reasoning in Large Language Models. arXiv:2201.11903. — The hint ladder's progressive reasoning steps are chain-of-thought prompting applied to teaching.
- Wang, X., Wei, J., Schuurmans, D., Le, Q., Chi, E., Narang, S., Chowdhery, A., & Zhou, D. (2022). Self-Consistency Improves Chain of Thought Reasoning in Language Models. arXiv:2203.11171. — Sampling multiple reasoning paths and taking consensus reduces noise.
/challenge's self-consistency grading runs the evaluation three times internally before delivering. - Diao, S., Wang, P., Lin, Y., Pan, R., Liu, X., & Zhang, T. (2023). Active Prompting with Chain-of-Thought for Large Language Models. arXiv:2302.12246. — Uncertainty-targeted clarification beats uniform questioning.
/chiron's ambiguity detection at L0 fires one clarification cycle when the user's answer is vague, surfacing 2–3 interpretations. - Shinn, N., Cassano, F., Labash, B., Gopinath, A., Narasimhan, K., & Yao, S. (2023). Reflexion: Language Agents with Verbal Reinforcement Learning. arXiv:2303.11366. — Persistent memory across episodes enables targeted improvement. Chiron's profile read-loop (
/challenge+/postmortem) is Reflexion adapted for deliberate practice — past failures inform future drill selection.
- taste-skill by Leonxlnx — frontend design-quality plugin whose techniques (anti-pattern enumeration, pre-flight checklists, named pattern arsenal, output completeness enforcement, control dials, self-verification loops, multi-level specification) were adapted for chiron's backend teaching context in v0.12.0.
- Prompt Engineering Guide by dair-ai — comprehensive reference on prompting techniques that informed v0.14.0's self-consistency grading, Active-Prompt ambiguity detection, and context engineering audit.
If you use chiron in research or writing, please cite:
@software{chiron2026,
author = {Haitham, Ahmed},
title = {Chiron: A Teach-First Mentor Plugin for AI Coding Tools},
year = {2026},
url = {https://github.com/xDido/chiron}
}MIT.
See CONTRIBUTING.md and CODE_OF_CONDUCT.md.