code-guide.el

Agent-authored, hierarchical code-reading guides for Emacs.

An AI agent inspects a repository and writes a .codeguide.json file: a tree of nodes, each pointing at a source location and explaining why it matters. Emacs renders that guide as a read-only tree. You read the narrative in the guide buffer and jump or preview into the code.

This is not an xref or tag browser. It is a persistent reading itinerary through a codebase.

Install

Requires Emacs 29.1 or later. No other dependencies.

(use-package code-guide
  :load-path "path/to/code-guide"
  :commands (code-guide-open code-guide-open-project-guide
             code-guide-install-skills))

Install the bundled agent skill as a symlink from Emacs:

M-x code-guide-install-skills

Or install it from the shell:

make install-skills

This links skills/code-guide-author to ~/.agents/skills/code-guide-author. It refuses to replace a real file or directory. Set AGENT_SKILLS_DIR to use a different agent skills directory.

Use

1. Let an agent write a guide. The package does not generate one itself. skills/code-guide-author/SKILL.md teaches an agent how. examples/authentication.codeguide.json shows the shape. code-guide.schema.json is the JSON schema.
2. Run M-x code-guide-open and pick the file, or run M-x code-guide-open-project-guide to find one under .code-guides/, .codeguide.json, or docs/code-guides/.

Guide placement uses code-guide-guide-display-buffer-action. It accepts a complete display-buffer action and defaults to nil, which preserves the standard pop-to-buffer behavior. For example, show guides at the bottom:

(setq code-guide-guide-display-buffer-action
      '((display-buffer-at-bottom)
        (window-height . 0.25)))

This setting does not change code-guide-display-buffer-action, which controls source visits and previews.

Protect visible assistant or conversation buffers from source previews and visits with Emacs regular expressions:

(setq code-guide-protected-buffer-name-patterns
      '("\\`\\*claude-code" "\\`\\*ghostel"))

For rules that need buffer state, set code-guide-protected-buffer-predicate to a function of one buffer. A non-nil result protects it:

(setq code-guide-protected-buffer-predicate
      (lambda (buffer)
        (with-current-buffer buffer
          (derived-mode-p 'comint-mode))))

The name patterns and predicate use OR semantics. Both settings default to nil and changes apply to the next visit. Invalid regular expressions and predicate errors are reported before display changes a window.

Protected windows and the guide window are not source destinations. Code Guide tries the configured source action, a new split, and then a new frame. If no safe destination exists, it reports an error without replacing a protected buffer. A custom display rule that selects a protected window is rejected.

Remote guides use the same commands and keys. Select a standard TRAMP guide directly:

/ssh:user@host:/path/to/repo/.codeguide.json

To discover guides in a remote project, first visit any file in that project, then run M-x code-guide-open-project-guide. Relative guide roots and source paths stay on the selected remote connection.

TRAMP ships with Emacs. TRAMP-RPC is optional and uses the same workflow with an /rpc:user@host:/path filename. It requires its own supported Emacs and TRAMP versions, msgpack package, remote host, and deployed server. A missing RPC prerequisite or connection error is reported as-is; code-guide never switches the path to standard TRAMP or a local file.

Run M-x imenu in a guide buffer to search every node by its hierarchy path. Folded and narrative nodes remain selectable. Duplicate sibling titles include one-based occurrence numbers. If Consult is already installed, M-x consult-imenu uses the same entries without Code Guide configuration.

Keys in the guide buffer:

Key	Command
RET	visit the node’s location
o	visit in another window
SPC	preview, keep the guide selected
n / p	next / previous node
] / [	next / previous sibling
u / d	parent / first child
TAB	fold or unfold the subtree
S-TAB	fold all
U	unfold all
g	reload the guide from disk
v	validate every location
q	quit

Reload keeps the node at point and the fold state when the ids survive. Validation writes a navigable *Code Guide Validation* buffer.

A location is file plus line. When the node also carries an anchor string, the package searches code-guide-anchor-search-range lines around the recorded line and uses the nearest match, so a guide survives line drift.

Guide format

{
  "version": 1,
  "title": "How request authentication works",
  "description": "Follow one request from socket read to authorization.",
  "root": ".",
  "nodes": [
    {
      "id": "route-auth",
      "title": "Authentication gate",
      "comment": "Credentials are checked before dispatch.",
      "location": {
        "file": "src/auth.c",
        "line": 210,
        "column": 1,
        "symbol": "authenticate_request",
        "anchor": "int authenticate_request("
      },
      "children": []
    }
  ]
}

root is relative to the guide file. file is relative to root. A node without location is narrative only.

Develop

make compile
make test

docs/HANDOFF.md is the original design document.

License

GPL-3.0-or-later. See LICENSE.