CodeTutor: AI Pair Programmer for Emacs

CodeTutor is an Emacs package designed to function as an AI pair-programming tutor rather than an autocomplete engine. It integrates a local AI assistant into the Emacs editor to provide conceptual guidance, review code changes after saves, and offer architectural advice without ever modifying the user's source files.

Core Philosophy: Teaching Over Implementation

CodeTutor is built on the principle of guiding the user toward a solution rather than providing ready-to-paste code. The tool is designed to act like a senior or staff engineer, focusing on underlying concepts, risk, and architecture.

Implementation Boundaries

To maintain its role as a tutor, CodeTutor adheres to strict boundaries:

  • No Source Modification: The tool does not write into project files, produce patches, or generate full-file replacements.
  • Conceptual Guidance: It provides compact illustrative code samples and explains the concepts behind its feedback, but avoids handing over complete implementations for specific tasks.

Functional Capabilities

CodeTutor operates through four primary interaction loops: startup assessment, save review, manual prompts, and follow-up questions.

Save Review Loop

When codetutor-review-on-save is enabled, the package hooks into the Emacs save process. It captures the state of the file before the save, compares it to the saved buffer text to build a unified diff, and sends this diff along with project context to the AI backend. The resulting teaching response is then displayed in a right-side tutor panel.

Manual Prompts and Follow-ups

Users can interact with the tutor via the minibuffer using codetutor-ask. This request includes the current file, project context, and architecture memory. Users can then use codetutor-follow-up to ask clarifying questions about the previous answer, maintaining continuity across conversation turns.

Project Assessment and Next Steps

  • Startup Assessment: Running codetutor-open triggers a project assessment that identifies where to begin and what engineering judgments are necessary before writing code.
  • What Next: The codetutor-what-next command asks the tutor to recommend the single best next step based on the available project context.

Technical Architecture and Context Gathering

CodeTutor builds comprehensive prompts by aggregating data from several local sources to ensure the AI has sufficient context for its advice.

Context Sources

Source Purpose
PROJECT.md / project.md Product and project direction
spec/ directory Specifications and design notes
.codetutor/ARCHITECTURE.md Durable project memory
Current file text Active editing context
Tree-sitter/Imenu summary Syntax-level outline of the buffer
Project file index Helps the tutor identify other files to inspect
Diff since last save The specific changes being reviewed
Open project buffers Nearby work in the current session

Architecture Memory

CodeTutor implements a durable memory system. When the tutor identifies architecture observations, it wraps them in a codetutor-memory block. The package automatically extracts these observations and appends them to .codetutor/ARCHITECTURE.md, which is the only file the package is permitted to write to automatically.

Backend Integration and Safety

CodeTutor supports two local backends: codex and pi. Both are configured to ensure the AI cannot modify the user's filesystem.

Backend Configurations

  • Codex: Uses codex exec in a read-only sandbox with an approval policy set to never and ephemeral sessions.
  • pi: Uses non-interactive print mode with a restricted toolset limited to read, grep, find, and ls.

Safety Layers

Safety is enforced through two layers: prompt-level instructions that forbid file editing and backend-level command boundaries that restrict the AI to read-only modes.

Installation and Requirements

CodeTutor requires Emacs 28.1 or newer, with Emacs 29+ recommended for built-in tree-sitter support.

Configuration for Doom Emacs

For Doom Emacs users, the package can be added via packages.el using a local repository recipe and configured in config.el with the following commands:

  • codetutor-open
  • codetutor-what-next
  • codetutor-ask
  • codetutor-follow-up
  • codetutor-refresh-architecture-memory

Customization

Users can adjust context limits (e.g., codetutor-max-project-context-bytes) and the system prompt (codetutor-system-prompt) to tailor the tutor's behavior and the specific amount of data sent to the AI backend.

Sources