CodeTutor is an Emacs package for learning while you code. It opens a right-side tutor panel, watches file saves, gathers project context, and asks a local AI assistant to respond like a senior/staff engineer pair-programming tutor.

The important boundary: CodeTutor helps you write the code. It does not write into your project files for you.

It can:

• review what changed after a save
• explain the concept behind feedback
• show compact illustrative code samples
• recommend the best next step
• answer minibuffer prompts
• answer follow-up questions using recent conversation turns
• keep durable architecture notes in .codetutor/ARCHITECTURE.md

It should not:

• edit your source files
• produce patches
• produce full-file replacements
• hand you a complete ready-to-paste implementation for the exact task

This is an early local package. It is designed for stock Emacs and Doom Emacs, with local codex and pi backends.

• Emacs 28.1 or newer
• Optional but recommended: Emacs 29+ with built-in tree-sitter support
• One local backend:
  • codex
  • pi

CodeTutor degrades gracefully when tree-sitter is not available by using imenu where possible.

(add-to-list 'load-path "/Users/jacobwindle/Projects/codetutor")
(require 'codetutor)

(setq codetutor-backend 'auto)
(codetutor-mode 1)

Add the local package:

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

Configure it:

;; ~/.config/doom/config.el
(use-package! codetutor
  :commands (codetutor-open
             codetutor-what-next
             codetutor-ask
             codetutor-follow-up
             codetutor-refresh-architecture-memory)
  :init
  (setq codetutor-backend 'auto
        codetutor-open-on-enable nil
        codetutor-start-session-on-open t
        codetutor-review-on-save t)
  :config
  (codetutor-mode 1))

Then run:

~/.config/emacs/bin/doom sync

Restart Emacs after syncing.

CodeTutor has four core loops: startup assessment, save review, manual prompt, and follow-up.

When you run M-x codetutor-open, CodeTutor:

1. Detects the project root.
2. Opens a right-side panel.
3. Gathers project context.
4. Starts a read-only backend request.
5. Replaces the panel with Status: thinking.
6. Replaces that status with the final tutor answer.

The startup answer should tell you where to begin, what to learn first, and what engineering judgment matters before writing code.

When codetutor-mode and codetutor-review-on-save are enabled, CodeTutor hooks into Emacs saves:

1. before-save-hook reads the current on-disk file.
2. The save happens normally.
3. after-save-hook compares the previous on-disk contents with the saved buffer text.
4. CodeTutor builds a unified diff.
5. CodeTutor sends the diff plus project context to the backend.
6. The side panel shows Status: thinking.
7. The side panel is replaced with the final teaching response.

Save reviews are proportional to the diff. The tutor should focus on concept, risk, architecture, tests, and one next move.

M-x codetutor-ask prompts from the minibuffer. It includes:

• the current file
• tree-sitter or imenu outline
• project context
• architecture memory
• project file index
• recent conversation turns

The backend may inspect/search other project files through read-only tools when supported.

M-x codetutor-follow-up asks a question about the previous answer. It does not display the prompt in the side panel.

Follow-ups include recent private conversation turns, so you can ask things like:

Can you show me a smaller example?

or:

What would the test shape look like?

The follow-up still includes current file and project context, so the tutor can connect the prior answer to where you are now.

M-x codetutor-what-next asks the tutor to inspect available context and recommend one best next step.

This is useful when you are between implementation slices and want a senior engineer's judgment on what to do next.

The tutor is asked to include durable architecture observations in a fenced block:

```codetutor-memory
- Boundary: The editor integration owns context gathering; the backend owns tutoring.
```

CodeTutor extracts those lines and appends new ones to:

.codetutor/ARCHITECTURE.md

That memory file is the only project file CodeTutor writes automatically.

CodeTutor builds a prompt from several local sources.

Open-buffer context is capped so a large Emacs session does not overwhelm the backend.

The Codex backend uses codex exec non-interactively. It is configured with:

• read-only sandbox
• approval policy never
• ephemeral session
• no terminal color
• optional web search
• --output-last-message so the panel displays only the final answer

The command is built roughly like this:

codex \
  --sandbox read-only \
  --ask-for-approval never \
  --search \
  exec \
  -C "$PROJECT_ROOT" \
  --skip-git-repo-check \
  --color never \
  --ephemeral \
  --output-last-message "$TEMP_FILE" \
  -

The pi backend uses non-interactive print mode with only read-only tools:

pi --print --tools read,grep,find,ls

It can inspect files, but should not write or edit them.

The side panel is intentionally not a chat transcript.

For every request, CodeTutor:

1. Clears the panel.
2. Shows Status: thinking.
3. Runs the backend.
4. Extracts the final answer.
5. Clears the panel again.
6. Shows only the answer.

The panel should not show:

• your prompt text
• generated prompt metadata
• full project context
• file contents sent as context
• backend progress output
• CLI transcripts

The tutor is asked to wrap visible answers in:

<codetutor-answer>
...
</codetutor-answer>

CodeTutor extracts that block when present and strips architecture memory blocks from the visible panel output.

The built-in prompt tells the tutor to:

• teach underlying concepts
• guide the user toward the solution
• ask useful questions
• give one concrete next move
• include compact code samples when they clarify the idea
• explain how to adapt examples instead of handing over final code
• avoid patches, full-file replacements, and complete ready-to-paste implementations

Good CodeTutor output should feel like a senior engineer pairing with you, not like an autocomplete engine.

Common settings:

(setq codetutor-backend 'auto)        ;; 'auto, 'codex, or 'pi
(setq codetutor-model nil)            ;; nil uses backend default
(setq codetutor-window-width 84)
(setq codetutor-review-on-save t)
(setq codetutor-enable-web-search t)
(setq codetutor-include-open-buffers-on-save t)

Context limits:

(setq codetutor-max-project-context-bytes 80000)
(setq codetutor-max-current-file-bytes 50000)
(setq codetutor-max-diff-bytes 60000)
(setq codetutor-max-open-buffers 12)
(setq codetutor-max-open-buffer-bytes 20000)
(setq codetutor-max-open-buffer-context-bytes 80000)
(setq codetutor-max-conversation-turns 8)
(setq codetutor-max-conversation-bytes 30000)

Prompt customization:

(setq codetutor-system-prompt
      "You are my read-only staff engineer tutor...")

CodeTutor has two layers of protection:

1. Prompt-level boundaries tell the tutor not to edit files or produce patches.
2. Backend command boundaries use read-only modes/tools where available.

For Codex, the package uses a read-only sandbox. For pi, it only enables read/search/list tools.

The only automatic write CodeTutor performs itself is .codetutor/ARCHITECTURE.md.

Run the backend directly:

codex doctor
codex exec --help
pi --help

Confirm the command-line flags in your installed version match what CodeTutor uses.

CodeTutor prefers Codex's --output-last-message file and extracts <codetutor-answer> blocks when present. If a backend still echoes context, use the Codex backend or adjust codetutor-system-prompt to reinforce the output contract.

Lower these limits:

(setq codetutor-max-diff-bytes 30000)
(setq codetutor-max-open-buffers 6)
(setq codetutor-max-open-buffer-context-bytes 40000)

(setq codetutor-review-on-save nil)

You can still use codetutor-ask, codetutor-follow-up, and codetutor-what-next.

Run tests:

emacs --batch -L . -l test/codetutor-test.el -f ert-run-tests-batch-and-exit

Byte compile:

emacs --batch -L . -f batch-byte-compile codetutor.el

Remove generated bytecode before committing:

rm -f codetutor.elc

codetutor.el                 Package implementation
codetutor-pkg.el             Package metadata
PROJECT.md                   Project direction consumed by CodeTutor
spec/initial-behavior.md     Initial behavior spec
test/codetutor-test.el       ERT regression tests
README.md                    User and developer guide