# CodeTutor

> An Emacs package that acts as an AI pair-programming tutor, reviewing your code on save and answering questions using a local AI backend — without writing to your project files.

CodeTutor is an Emacs Lisp package created by Jake Windle (jaketothepast on GitHub) that brings a local AI tutoring experience directly into Emacs. It opens a right-side panel, watches file saves, gathers project context, and routes prompts to a local AI backend configured to respond like a senior or staff engineer pair-programming tutor. The project was created in June 2026 and is in early development.

## What It Is

CodeTutor is an Emacs plugin in the AI coding assistant category, but with a deliberate teaching constraint: it helps you understand and write code, but it does not write into your project files. The core design philosophy is that the tutor should explain concepts, guide you toward solutions, and recommend next steps — not hand you a complete ready-to-paste implementation. This makes it distinct from autocomplete-style tools that generate code directly in the editor.

## How the Teaching Loop Works

CodeTutor has four core interaction loops:

- **Startup assessment** — on `codetutor-open`, it detects the project root, gathers context, and tells you where to begin and what engineering judgment matters before writing code.
- **Save review** — when `codetutor-review-on-save` is enabled, it diffs the file before and after each save, sends the diff plus project context to the backend, and displays a teaching response focused on concept, risk, architecture, tests, and one next move.
- **Manual prompt** — `codetutor-ask` prompts from the minibuffer with current file, tree-sitter or imenu outline, project context, architecture memory, and recent conversation turns.
- **Follow-up** — `codetutor-follow-up` continues the conversation using recent private turns, so you can ask for smaller examples or test shapes without losing context.

## Context Architecture

CodeTutor assembles prompts from several local sources on every request: `PROJECT.md`, a `spec/` directory, a durable `.codetutor/ARCHITECTURE.md` memory file, the current file text, a tree-sitter or imenu outline, a project file index, and recent conversation turns. On save reviews it also includes open project buffers. Context sizes are configurable with byte-level caps to avoid overwhelming the backend. The only file CodeTutor writes automatically is `.codetutor/ARCHITECTURE.md`, where it appends durable architecture observations extracted from tutor responses.

## Backend Support and Safety Boundaries

CodeTutor supports two local backends:

- **Codex** — invoked non-interactively via `codex exec` with a read-only sandbox, `--ask-for-approval never`, and `--output-last-message` so the panel shows only the final answer.
- **pi** — invoked in non-interactive print mode with only `read`, `grep`, `find`, and `ls` tools enabled.

Both backends are constrained at the command level to read-only operations, reinforcing the prompt-level instruction not to edit files or produce patches.

## Setup Path

CodeTutor requires Emacs 28.1 or newer. Emacs 29+ with built-in tree-sitter support is recommended but optional — the package degrades gracefully to `imenu` when tree-sitter is unavailable. Installation is manual: clone the repository, add it to `load-path`, and `require` it. Doom Emacs users can use a `:local-repo` recipe in `packages.el`. One local backend (`codex` or `pi`) must be installed separately.

## Current Status

The repository was created on June 8, 2026, and the README explicitly describes this as "an early local package." It has no OSI-approved license specified. The project targets stock Emacs and Doom Emacs workflows and is designed for developers who want a teaching-oriented AI companion rather than an autonomous code-generation tool.

## Features
- Right-side tutor panel in Emacs
- Automatic save review with unified diff
- Manual minibuffer prompts with project context
- Follow-up questions with conversation history
- Tree-sitter and imenu outline support
- Durable architecture memory in .codetutor/ARCHITECTURE.md
- Local AI backend support (codex and pi)
- Read-only backend sandboxing
- Configurable context byte limits
- Customizable system prompt
- Project file index inclusion
- Open buffer context on save reviews
- codetutor-what-next for best next step recommendation

## Integrations
Emacs, Doom Emacs, codex, pi, tree-sitter, imenu

## Platforms
WINDOWS, MACOS, LINUX

## Pricing
Free

## Links
- Website: https://github.com/jaketothepast/codetutor
- Documentation: https://github.com/jaketothepast/codetutor#readme
- Repository: https://github.com/jaketothepast/codetutor
- EveryDev.ai: https://www.everydev.ai/tools/codetutor