Learning-first Coding Agent

An agentic CLI tutor that doesn't finish your project for you — it teaches you to understand, explain, implement, and review at every step. Unlike Claude Code (which optimizes for delivery speed), this agent's success metric is what you can do after leaving it.

Architecture inspired by the Claude Code source tree: agent loop / tool system / sectioned system prompt / permission gating — with one twist: the write-code tools are mechanically gated by learner comprehension, not user approval.

---

Four Teaching Mechanisms

Mechanism	Behavior
Socratic Gate	Before writing any code, the tutor asks you to state your own approach. Can't explain it? It gives hints — not code.
Explanation Checkpoint	After every meaningful code change, the tutor pauses and asks you to explain it. A separate evaluator model grades pass / partial / fail; fail → rephrased question, not the answer.
Blank Challenge	The tutor writes a scaffold with // TODO(tutor:<id>) for you to implement. Until you close the challenge, the tutor is mechanically forbidden from editing that file.
Session Retrospective	On exit, the session generates a review: concepts covered, weak points, knowledge cards — persisted to .tutor/ and tracked across sessions.

Core design: teaching flow is driven by the system prompt (natural LLM guidance), but invariants are enforced by code (pedagogy enforcer). If the model tries to skip a teaching step and write code directly, the tool call returns BLOCKED by tutor protocol and tells it which teaching tool to call first.

---

Install & Run

Requires Node.js ≥ 20.

npm install
npm run build

# Configure (OpenAI-compatible endpoint — Kimi, DeepSeek, local models all work)
cp .env.example .env   # then fill in your key

# Start on a learning project
node dist/index.js /path/to/your/project

# Or dev mode (no build needed)
npm run dev -- /path/to/your/project

Environment Variables

TUTOR_* takes priority; OPENAI_* are fallbacks.

Variable	Default	Description
TUTOR_API_KEY	—	Required.
TUTOR_BASE_URL	https://api.openai.com/v1	Any OpenAI-compatible endpoint
TUTOR_MODEL	gpt-4o	Main model (writing, teaching)
TUTOR_EVAL_MODEL	same as model	Cheaper model for evaluation & retrospective
TUTOR_MODE	normal	strict / normal / relaxed

Config can also be placed in the target project's .tutor/config.json or ~/.tutor/config.json.

Kimi example:

TUTOR_BASE_URL=https://api.moonshot.cn/v1
TUTOR_API_KEY=your-key
TUTOR_MODEL=moonshot-v1-32k

DeepSeek example:

TUTOR_BASE_URL=https://api.deepseek.com
TUTOR_API_KEY=your-key
TUTOR_MODEL=deepseek-chat

---

REPL Commands

/help     Show help
/review   Generate a learning retrospective mid-session (session continues)
/profile  View your learner profile
/mode strict|normal|relaxed   Teaching intensity
/skip     Skip a checkpoint question (strict mode refuses; logged to profile)
/exit     End session and generate retrospective

Intensity levels:

• strict — checkpoint on every edit, unskippable
• normal — checkpoint on meaningful edits (>3 lines changed)
• relaxed — checkpoint every 3 edits

---

Full Teaching Flow Walkthrough

1. Point the tutor at a practice project and ask: "Help me add a groupBy utility function."
2. Socratic gate fires — it asks how you plan to approach it. Say "I don't know" and it gives a hint, not code.
3. Give a reasonable approach. Evaluator passes. Tutor starts writing.
4. Explanation checkpoint fires — it stops after one change and asks what the code does. Answer wrong once; watch it rephrase and ask again.
5. It may scaffold a blank challenge (// TODO) for you to implement; say "done" when finished and it reviews your code.
6. /exit to generate a retrospective; check .tutor/cards/ for knowledge cards. Next session on the same project, the tutor remembers your weak points.

---

Project Structure

src/
  agent/      Core loop (loop.ts), LLM client, message types
  tools/      File/command tools + teaching/ (5 teaching tools)
  teaching/   State machine · enforcer · evaluator · retrospective
  prompts/    Sectioned system prompt (tutor persona + protocol + project context)
  profile/    Learner profile and knowledge card persistence
  ui/         Readline REPL and terminal rendering
  config/     Config loading (env > project > global)

Learning data is stored in the target project's .tutor/:

• profile.json — learner profile
• cards/ — knowledge cards
• sessions/ — session logs

---

Development

npm test          # vitest unit tests (52 tests: loop, enforcer matrix, reducer, tools, profile)
npx tsc --noEmit  # type check
npm run build     # compile to dist/