Athleteaudio/codi-mentor

Codi

An AI Programming Mentor in a VS Code-style shell. Codi doesn't just catch your mistakes and teach you why — it helps you plan, architect, and build real projects, answering "what should I build next?" not only "what's wrong with this line?"

Codi is not an AI code generator and not just another IDE. It's a mentor: it asks thoughtful questions, explains reasoning before solutions, and never writes whole applications for you.

Architect Mode (Phase 2)

Opening or creating a project lands you on the Architect Dashboard, not an empty editor. Codi first runs a Project Creation Wizard (what are you building · describe it · who's it for · language · framework · deployment), then builds a living plan:

• Dynamic Architecture Map — a layered diagram (e.g. Main → IPC → Renderer → Services → Storage → AI) that lights up each layer as the matching folders/files appear in your project.
• Mission Board — a roadmap tailored to your project type whose milestones auto-check from detected structure (and you can override any of them).
• Recommended Next Task — the single most useful next step, with the reasoning.
• Learning Dashboard — engineering-skill confidence levels (Architecture, Async, Testing, Debugging, Security…), grown from what you actually do — not % complete.
• Project Review — "Review My Project" analyzes the whole codebase and reports strengths and opportunities across architecture, maintainability, naming, security, and technical debt — always explaining why.
• Architectural mentor — while you edit, Codi asks whether code belongs where it is ("this UI file is talking to a database directly — should that move to a service?").

The architect engine is modular: project blueprints live in src/architect/blueprints.js (add a type or tweak detection there); the compute engines (architecture, missions, nextTask, skills, review, mentorArchitect) are pure functions over a project scan.

---

Under the hood it's still a learning IDE: Codi catches your mistakes and teaches you why they happened instead of silently fixing them.

Built as a real desktop app: Electron + React + Monaco Editor + Node.js, with ESLint for JavaScript validation and JSON-backed mistake history.

Features

• Open Folder / New File / file-tree navigation
• Monaco editor with syntax highlighting and tabs
• Live JavaScript syntax + error checking (ESLint)
• Problems panel (file, issue, line, column)
• Output / Terminal / Git tabs
• Codi Coach — a proactive AI mentor, not a passive panel:
  • Speaks up on its own ("I noticed something on line 5…") when it sees an issue
  • Asks Socratic multiple-choice questions ("Is World a variable or a string?")
  • Beginner mode guides you directly (Explain / Show fix / Quiz)
  • Intermediate mode hides answers and drips a 3-step hint ladder — the fix stays hidden until you ask
  • A dashboard with today's lesson, goal, streak, and learning metrics
• Practice Mode — 10 guided exercises where you fix real broken code yourself
• Learning metrics — Understanding %, errors fixed today, hints used, fixes revealed, your most common mistake type, and a daily streak
• Mistake history that tracks repeated errors so you can see your patterns
• Dark, VS Code-inspired theme with a purple/blue accent

The mentor experience

Codi is designed to feel like a teacher sitting next to you, not an autocomplete.

• Proactive voice — when you open a file or pause typing, Codi re-analyzes it (ESLint) and, if it finds something, says so unprompted with a specific, Socratic nudge tied to the line.
• Interactive questions — some issues come with a multiple-choice question that makes you decide the intent before Codi explains the consequence of each choice.
• Two teaching modes — Beginner is direct and quick; Intermediate withholds the answer and offers Hint 1 (concept) → Hint 2 (where to look) → Hint 3 (the specific issue), revealing the actual fix only when you explicitly ask.
• Always-useful panel — before any error is selected, the Coach shows a welcome, the day's concept + goal, your streak, live learning metrics, a mistake summary, and a suggested next action.

The mentor logic lives in src/coach/ (mentorBrain.js for nudges/questions/hints, curriculum.js for the daily lesson). Metrics + streak persist via the existing history store (electron/services/historyService.js).

Project intent (build goal)

At the top of the Coach panel, Codi asks "What are you trying to build?" (with quick examples like A Discord bot or A crypto trading dashboard). The answer is:

• Saved per project folder — each folder remembers its own goal.
• Editable at any time — click the ✎ to change it.
• Included in every coach request — so explanations are framed around your project. A broken async function in a Discord bot is explained in terms of bot commands and event handling, not in the abstract.

Beyond "what's wrong with this line?", Codi also asks the more important question: "Does this line make sense for the program you're trying to build?"

The goal is stored in projectGoals (keyed by folder path) in the same mistake-history.json store, and passed through codi.explain(...) to the local Gemma 4 coach (electron/services/aiCoach.js).

Practice Mode

The dumbbell icon in the activity bar opens Practice Mode: 10 beginner-to- intermediate JavaScript exercises where Codi hands you broken code and you fix it.

• The sidebar lists all exercises with live status (todo / attempted / solved-clean / solved-with-hints / revealed) and a progress bar.
• Each exercise shows the concept, a prompt, and an editable Monaco editor.
• Check my fix runs real validation — ESLint for syntax/reference mistakes, hidden test cases for logic bugs (off-by-one, wrong operator, bad initial value…).
• Two progressive hints and a Reveal solution button — the answer is never shown up front.
• After you solve it (or reveal it), Codi shows the explanation of what you learned.
• Progress (solved, hints used, whether you revealed the answer, attempt count) is saved to the same mistake-history.json store as your mistake history.

Exercises live in src/practice/exercises.js; validation logic is in src/practice/practiceEngine.js. Add more exercises by appending to the array — no other changes needed.

Run it

cd codi
npm install
npm run dev

npm run dev starts the Vite dev server and launches the Electron window against it.

To run the production build:

npm run build
npm start

To package a distributable:

npm run dist

Connected Agents (Phase 1)

Codi can connect multiple coding agents and manually switch between them while preserving project handoff context (goal, plan, steps, files, git diff, errors).

Provider	Env var
Gemma 4	OLLAMA_BASE_URL (default http://127.0.0.1:11434)
Grok	XAI_API_KEY
Codex	OPENAI_API_KEY
Ollama	OLLAMA_BASE_URL (default http://127.0.0.1:11434)

Open the Agents icon in the activity bar (or click the agent name in the status bar) to list providers, switch, and test connections. API keys are never written to disk or logs.

See .env.example for placeholders. Smoke test:

npm run test:agents

Codi Coach: AI provider

Codi Coach works fully offline out of the box. The primary explanation engine is a local fine-tuned Gemma 4 model served through Ollama (electron/services/aiCoach.js). A built-in teaching knowledge base covers the common beginner mistakes when no model is available.

Point it at your local Ollama server and, optionally, a custom model:

set OLLAMA_BASE_URL=http://127.0.0.1:11434        # Windows (cmd)
$env:OLLAMA_BASE_URL="http://127.0.0.1:11434"     # PowerShell
set CODI_OLLAMA_MODEL=codi-mentor

The default model is codi-mentor — Codi's own fine-tuned Gemma 4 coach. The coach is prompted to teach, not to dump the answer — it never returns a whole corrected file.

Architecture

electron/
  main.js              Electron main process + IPC registration
  preload.js           Safe, typed window.codi bridge (contextIsolation on)
  services/
    fileService.js     Folder tree, read/write/create files
    lintService.js     Validation layer — register new languages here
    historyService.js  Mistake history (JSON, storage-agnostic API)
    aiCoach.js         Local Gemma 4 coach + offline teaching knowledge base
    gitService.js      Branch + status via the system git binary
    agentRegistry.js   Supported coding-agent catalog (Gemma 4/Grok/Codex/Ollama)
    agentSettings.js   Active provider + non-secret local overrides
    handoffContext.js  Shared project context preserved across agent switches
    agentService.js    list / getActive / setActive / testConnection API
src/
  monaco-setup.js      Monaco workers wired through Vite + Codi dark theme
  App.jsx              App state + layout
  components/          ActivityBar, Explorer, EditorArea, BottomPanel,
                       CoachPanel, StatusBar, HistorySidebar
  lib/                 language mapping, mini markdown renderer

Adding a language (Python / TypeScript / C++)

The validation layer is modular. In electron/services/lintService.js, add a validator function returning the same Problem[] shape and register it in the validators map:

const validators = {
  javascript: validateJavaScript,
  python: validatePython,   // <- add
};

Then add the extension in src/lib/language.js and (optionally) to VALIDATABLE. Nothing else in the UI needs to change.