A Technical Guide to CodeTutor for Emacs

Practical Summary and Core Philosophy

CodeTutor is an Emacs package designed to act as a senior or staff engineer pair-programming tutor. It operates by watching file saves, gathering project context, and querying a local or remote AI assistant to provide feedback. The fundamental boundary of the tool is that it is strictly read-only regarding your project files; it does not write code, produce patches, or generate full-file replacements. Instead, it focuses on explaining concepts, identifying risks, suggesting architectural improvements, and recommending the next best steps for your development process. It is intended for programmers who want to improve their coding skills through guided interaction rather than automated code generation.

Prerequisites and Installation

To use CodeTutor, you must be running Emacs 28.1 or newer. While not strictly required, Emacs 29+ with built-in tree-sitter support is highly recommended for better project context gathering. You must also select a backend to power the AI assistant. The available options include codex (a local, read-only sandbox), pi (local, read-only tools), or the remote Fireworks AI backend. For Doom Emacs users, installation involves adding the package to your packages.el file and configuring it in config.el as shown below:

;; ~/.config/doom/packages.el
(package! codetutor
  :recipe (:local-repo "~/Projects/codetutor"))

After configuring, you must run ~/.config/emacs/bin/doom sync and restart Emacs to complete the installation process.

Understanding the Core Workflow

CodeTutor functions through four primary interaction loops: startup assessment, save review, manual prompting, and follow-up questions. When you run M-x codetutor-open, the tool detects your project root, gathers context, and provides an initial assessment of where to begin and what engineering judgment is required. When codetutor-review-on-save is enabled, the tool automatically generates a unified diff after each save, sending it to the backend to receive feedback on the specific changes made. This allows for iterative learning as you progress through your implementation, ensuring that the tutor's advice remains relevant to your current work.

Advanced Features: Specs and Scratch Buffers

Beyond simple reviews, CodeTutor supports a spec development mode via M-x codetutor-new-spec. This creates a spec/<slug>.md file and opens a workbench where the tutor interviews you about your feature goals, requirements, and risks. This mode is teach-only, meaning the tutor critiques your design and identifies gaps rather than writing the spec for you. Additionally, the codetutor-scratch command provides an ephemeral buffer for thinking out loud. Both spec documents and the scratch buffer are pinned to every request, ensuring the tutor always has access to your current design thinking and working notes.

Agentic Tools and Inline Tips

When using the Fireworks AI backend, CodeTutor can utilize agentic tools to explore your codebase. Instead of receiving a single pre-packed prompt, the model can pull context as needed using tools like read_file, list_directory, and search_project. A unique feature is codetutor-inline-tips, which allows the tutor to place teaching annotations directly on specific lines of your code buffer. These tips are rendered as virtual lines and are display-only, meaning they never modify your source files. They are designed to highlight concepts, risks, and tradeoffs, and they automatically clear when you edit the buffer to prevent stale information.

Architecture Memory and Context Management

CodeTutor maintains durable project knowledge through .codetutor/ARCHITECTURE.md. The tutor is instructed to include observations in a specific fenced block, which the package then extracts and appends to this file. This is the only file the tool is permitted to write to automatically. To ensure the backend is not overwhelmed, the tool caps the amount of context sent, including limits on open buffers and conversation history. You can customize these limits and other behaviors by adjusting variables such as codetutor-max-project-context-bytes or codetutor-max-conversation-turns, allowing you to tune the tool to your specific project size and hardware capabilities.

Limitations and Safety Boundaries

It is critical to understand that CodeTutor is not an autocomplete engine or a code generator. It is explicitly designed to avoid producing patches or ready-to-paste implementations. The tool operates under strict safety boundaries, both in its prompt instructions and its technical implementation. For instance, when using agentic tools, the backend is sandboxed to the project root, and any attempt to access files outside this directory is refused. Because the tool is intended for learning, it prioritizes explaining the "why" behind engineering decisions. Users should expect a collaborative, senior-engineer-style pairing experience rather than a tool that performs the work on their behalf.

Choosing When to Use CodeTutor

CodeTutor is best suited for developers who are actively seeking to improve their engineering judgment, architectural design skills, and testing strategies. It is particularly effective when you are between implementation slices and need a senior perspective on the "best next step." By providing a structured way to document requirements through specs and maintain architecture memory, it helps keep projects organized. If you are looking for a tool to simply write code for you, CodeTutor will not meet your needs. However, if you want a persistent, context-aware tutor that helps you think through complex problems, it is a powerful addition to your Emacs environment. For more information, visit https://github.com/jaketothepast/codetutor.