Opencode Mentor

From Coding Agent to Coding Mentor: My OpenCode Mentor Configuration

Download it here: opencode-mentor

Most AI coding setups optimize for throughput. They help you write more code, faster. That is useful, but it has a tradeoff: if the assistant always jumps straight to the answer, the human can lose the chance to build judgment.

This OpenCode configuration explores a different direction. Instead of treating AI as a replacement pair programmer, it turns OpenCode into a mentor system. The goal is not just to finish tasks. The goal is to help the developer understand why a solution works, recognize better tradeoffs, practice weak concepts, and gradually need less help over time.

I call this setup MAI: Mentor AI Infrastructure.

Why This Exists#

The default mental model for coding agents is simple: describe the work, let the agent edit files, run tests, and ship the change. That can be powerful, especially for experienced engineers who already know how to evaluate the result.

But for learners, that same workflow can become a shortcut around the most valuable part of programming: thinking through the problem.

MAI is built around a different premise. The assistant should improve the user’s programming judgment, not just produce output. It should explain, question, review, challenge, and create practice loops. It should help the user become the kind of engineer who can eventually work without the assistant.

That is why the main identity in this configuration is not a generic coding agent. It is Rob, an AI mentor integrated into OpenCode.

What This Configuration Does#

Rob is configured as a mentor-first assistant. The system prompt in AGENTS.md makes the boundary explicit: Rob is a coding mentor, not a code generator.

That changes the behavior in a few important ways:

  • Explanations are preferred over complete answers.
  • Hints, pseudocode, and checklists are preferred over code dumps.
  • Reviews focus on reasoning, design, correctness, and maintainability.
  • Exercises are used to strengthen weak concepts.
  • Session reflections are stored so future interactions can build on prior learning.
  • The assistant is expected to guide the user toward understanding, not simply complete the work for them.

This does not mean the system ignores practical engineering. It still reads files, reviews code, reasons about architecture, runs allowed commands, and uses tools. The difference is the purpose behind those actions. The work is framed as teaching.

Who This Is For#

This kind of setup is useful for developers who want to learn through practice rather than outsource all thinking to an assistant.

It is especially suited for:

  • Developers building confidence through guided repetition.
  • Self-directed learners who want feedback while they work.
  • People who want an AI pair that teaches instead of replacing thought.
  • Maintainers experimenting with agentic tutoring workflows.
  • Engineers who want review and architecture guidance without automatic rewrites.

If your only goal is maximum automation, this configuration will feel intentionally restrained. If your goal is long-term skill growth, that restraint is the point.

How It Works#

The architecture is simple at the top level:

OpenCode config -> Mentor Orchestrator -> specialist agents -> skills/tools -> learner state

opencode.json sets the default agent to mentor-orchestrator. That orchestrator acts as the front door. It classifies the user’s intent, retrieves learner state, and routes the interaction to the right specialist agent.

The specialist agents handle different teaching modes:

  • The mentor explains concepts and gives scaffolded guidance.
  • The reviewer critiques code and design without rewriting everything.
  • The architect handles system-level reasoning and tradeoffs.
  • The drill instructor generates targeted practice.

Behind those agents are skills and tools. Skills provide loadable context for specific domains or workflows. Tutor tools manage learner profiles, concept lookup, curriculum progression, exercise generation, grading, and session reflection.

The result is a loop: understand the learner, route to the right teaching mode, respond, reflect, and update state for next time.

Core Components#

The configuration is split across a few important files and directories.

AGENTS.md defines the global identity and operating philosophy. This is where Rob is named, where the mentor-first boundary is declared, and where project-wide behavior such as voice responses, preferred stacks, and issue tracking expectations are documented.

opencode.json wires the runtime together. It sets mentor-orchestrator as the default agent, disables sharing, enables snapshots, configures permissions, enables the Context7 MCP server, and loads plugins for tutor behavior, environment protection, and safety filtering.

agents/ contains the specialist prompts. The key files are mentor-orchestrator.md, mentor.md, reviewer.md, architect.md, drill-instructor.md, and pair-programmer.md.

skills/ contains reusable context modules. These let the assistant load targeted instructions only when they are relevant, instead of stuffing every behavior into one giant prompt.

tools/tutor* provides the learning-specific tool surface. These tools support learner profiles, concept queries, curriculum decisions, exercise generation, grading, and session reflection.

plugins/ contains runtime hooks. In this configuration, plugins are intended to support tutor behavior, protect environment files, and filter unsafe operations.

.opencode/mentor/ is the intended home for runtime mentor state, such as learner data and session continuity.

Beads is used as the preferred issue tracker for follow-up work, bugs, and cleanup tasks.

The Agent Team#

The most important agent is the mentor orchestrator. It is the primary agent, which means user requests enter through it by default. Its job is not to teach directly. Its job is to manage the learning flow.

The orchestrator is designed to retrieve learner state, classify intent, choose a specialist, delegate the interaction, and then persist reflection afterward. That makes it more like a teaching coordinator than a tutor.

The mentor agent handles beginner-friendly explanations, debugging guidance, syntax clarification, and conceptual coaching. It is explicitly told not to provide full implementations. Its job is to help the learner form the missing mental model.

The reviewer agent is for submitted code or solution attempts. It focuses on correctness, design, maintainability, performance, and security. It does not rewrite the user’s work. Instead, it explains what is wrong, why it matters, and what kind of refinement would improve the solution.

The architect agent supports higher-level design questions. It is useful when the user is thinking about structure, boundaries, tradeoffs, or system design.

The drill instructor creates practice loops. It identifies a skill, generates a focused exercise, withholds the solution, evaluates the user’s attempt, and adjusts difficulty based on performance.

There is also a pair programmer agent in the repository. That is a useful reminder of the system’s design tension. Pair programming agents usually optimize for helping produce code. MAI is moving in the opposite direction: toward mentoring, practice, and independent reasoning. Keeping or removing that role is a configuration decision worth making deliberately.

Skills And Tools#

Skills are one of the most useful parts of this setup. They act like context packs that can be loaded only when needed. Instead of forcing every agent to carry every instruction all the time, skills keep guidance modular.

For example, this configuration includes skills for backend patterns, coding standards, security review, test-driven workflows, frontend patterns, graph-based codebase analysis, OpenCode customization, and verification loops.

The tutor tools are what make the mentor system feel less stateless. They provide operations such as:

  • Retrieve a learner profile.
  • Update learner state.
  • Query related concepts and prerequisites.
  • Choose the next curriculum step.
  • Generate scaffolded exercises.
  • Grade exercise attempts.
  • Persist a short session reflection.

There are also utility tools for practical workflow support: speak for voice responses, JSON validation, current date/time lookup, math operations, and Context7 documentation retrieval.

Taken together, these tools move the assistant away from isolated chat responses and toward an adaptive teaching loop.

Safety And Boundaries#

Mentor behavior depends on trust. This configuration includes several boundaries to make the assistant less likely to do surprising or destructive things.

Sharing is disabled in opencode.json, and snapshots are enabled. Bash permissions are conservative: most commands require approval, while specific safe commands can be allowed. Environment protection and safety filter plugins are included to protect sensitive files and reduce destructive command risk.

The strongest boundary, though, is pedagogical rather than technical. The system repeatedly states that the agents are not supposed to be a code generators. The assistants should avoid full code dumps, avoid doing all of the user’s thinking, and prefer guided learning.

That boundary matters because safety is not only about preventing bad commands. It is also about preventing bad habits. If the assistant always finishes the work, the user may finish the task without learning the skill and atrophy existing skills.

How To Adapt This For Yourself#

The easiest way to adapt this configuration is to start with the identity and teaching philosophy.

Rename Rob if you want a different mentor identity. Then adjust AGENTS.md so the assistant’s tone, boundaries, and learning goals match your preferences.

Next, review your preferred languages and package managers. This setup favors Go and Python, with Svelte and TypeScript as secondary options. Your own configuration should reflect the stack you actually use.

Then tune the agent prompts. The mentor, reviewer, architect, and drill instructor should each have a clear job. If two agents overlap too much, routing becomes fuzzy. If an agent can edit or write when it should only teach, the system may drift back toward automation.

After that, customize skills. Add skills for your frameworks, architecture patterns, review standards, or learning goals. Remove stale skills that no longer match your workflow.

Finally, review learner state and plugin behavior. Decide how learner IDs should work, where state should live, what data should be remembered, and which safety rules should be enforced.

Known Rough Edges#

This configuration is an active experiment, not a polished product. There are some known inconsistencies worth fixing.

Some documentation is stale or Claude-oriented.

The pair programmer role is another unresolved design choice. It may be useful in some contexts, but it conflicts with the strict mentor-first posture if left too permissive.

Roadmap#

  • [/] Make the system more consistent, more stateful, and more adaptive.

  • The first priority is naming and routing cleanup. Every referenced agent and tool should exist, and stale names should be removed. Broken delegation is especially harmful in a mentor system because it interrupts the learning loop.

  • The second priority is a stable learner ID strategy. Learner memory only works if the same learner maps to the same profile across sessions.

  • After that, the system needs a compact mentor memory summary. The assistant should not have to load a large history every time. A small current teaching state could include the learner’s goal, weak concepts, recent blockers, last session summary, active exercise, and recommended next move.

  • Preference-aware routing is another useful upgrade. If the system already knows the learner prefers quizzes, code exercises, or explanations, it should use that signal.

  • The exercise lifecycle also needs more structure. A strong version would support active exercises, submissions, retries, pause/resume behavior, completion states, and abandonment states.

  • Longer term, the system could add richer progress analytics, broader safety protections, branching curriculum paths, spaced review, and diagnostics for maintainers who want to understand why a certain tutoring decision was made.

Getting Started#

To use a configuration like this, you need OpenCode, the config files, the agent prompts, the skills, the tutor tools, and any plugins you choose to enable. This particular setup also assumes Bun and TypeScript tooling for parts of the plugin/tool ecosystem, Beads for issue tracking, and optional Context7 MCP access for documentation lookup.

The most important setup step is not technical. It is deciding what role you want the assistant to play.

If you want an agent that silently completes work, this is the wrong configuration. If you want an assistant that helps you reason, practice, review, and improve, the mentor model is much more interesting.

The future of AI coding tools should not only be about writing more code. It should also be about helping developers think better.

Blog

What I Learned While Learning to Code by Vibe Coding

Vibe Coding is Worse than Drugs