diff options
Diffstat (limited to 'docs/design/ai-vterm.org')
| -rw-r--r-- | docs/design/ai-vterm.org | 159 |
1 files changed, 0 insertions, 159 deletions
diff --git a/docs/design/ai-vterm.org b/docs/design/ai-vterm.org deleted file mode 100644 index 99526b632..000000000 --- a/docs/design/ai-vterm.org +++ /dev/null @@ -1,159 +0,0 @@ -#+TITLE: Design: ai-vterm — in-Emacs Claude launcher -#+AUTHOR: Craig Jennings -#+DATE: 2026-05-07 -#+OPTIONS: toc:nil num:nil - -* Status - -Draft. - -* Problem - -Claude Code currently launches outside Emacs via the =ai= shell script, which builds candidate projects from =~/.emacs.d=, =~/code/*=, =~/projects/*= (anything with =.ai/protocols.org=), opens each in a tmux window, and runs =claude "Read .ai/protocols.org and follow all instructions."= per project. The shell-out pulls focus to a terminal, and tmux's horizontal split is the wrong shape for a code-on-left, Claude-on-right reading layout. - -The in-Emacs alternative today is =vterm-toggle= at F12, which uses a horizontal bottom split via =display-buffer-at-bottom=. No project picker, no per-project session model, no vertical split. - -Building this in Emacs eliminates the context switch and gives the side-by-side layout that matches how the work is actually read. - -* Non-Goals - -- Replicating the =ai= script's git prep / auto-pull. Phase A.0 of the startup workflow already handles pulls at session start. -- A multi-project session switcher with its own UI. =consult-buffer= and the buffer list already navigate between =claude [...]= buffers. -- Replacing =vterm-toggle= at F12. The existing bottom-split flow stays for non-AI shells. -- Tab-bar or frame-per-project layouts. -- Auto-launching tmux inside the AI vterm. Claude under tmux adds a session-management layer for no benefit here. - -* Approaches Considered - -** Recommended: wrap =vterm= directly with per-project named buffers + a parallel display rule - -A new module =modules/ai-vterm.el= adds a command that picks a Claude-template project, opens (or reuses) a vterm buffer named =claude [<basename>]=, and lets a new =display-buffer-alist= entry route any buffer matching that prefix to a right-side window. Multiple projects produce multiple coexisting buffers, all sharing the same right-side slot. Switching among them is a buffer-switch, not a kill-and-recreate. - -Pros: -- Same package (=vterm=) as the existing config. -- Per-project buffers run simultaneously without conflict. -- Right-side placement is one =display-buffer-alist= entry. -- Existing windmove (Shift-arrows) handles code↔Claude focus toggling. =buffer-move= (C-M-arrows) handles side-swap. Neither needs new bindings. - -Cons: -- Re-implements toggle/show-hide logic that =vterm-toggle= would handle for free. Acceptable because =vterm-toggle= is built around one toggle-able buffer, and the per-project model is what's wanted. - -** Rejected: wrap =vterm-toggle= - -=vterm-toggle='s contract is one buffer toggled visible/hidden. Per-project buffers running simultaneously is outside that contract. Wrapping it would mean fighting the abstraction. - -** Rejected: project-per-tab via =tab-bar-mode= - -Each project gets its own tab. Matches the =ai= / tmux model cleanly, but adds tab-bar UI that isn't in current use. Bigger lifestyle change for a one-window task. - -** Rejected: frame-per-project - -Each Claude session opens in a new Emacs frame. Hyprland-native, clean isolation, but frame creation under Wayland has historical jank, and it breaks the easy windmove flow between code and Claude. - -** Rejected: window-configuration-per-project - -Save and restore named window configs (code buffers + Claude vterm together). Preserves the surrounding thinking environment, but window configs go stale when buffers die, and it adds a parallel mechanism to project.el. Overkill for v1. - -* Design - -** Architecture - -New module =modules/ai-vterm.el=. Required after =eshell-vterm-config= in =init.el= so =vterm= is loaded. - -Components: - -| Function | Kind | Responsibility | -|----------+------+----------------| -| =cj/--ai-vterm-candidates= | pure | Walks =~/.emacs.d=, =~/code/*=, =~/projects/*=; returns abs paths containing =.ai/protocols.org= | -| =cj/--ai-vterm-pick-project= | interactive helper | =completing-read= over candidates; returns picked path | -| =cj/--ai-vterm-buffer-name= | pure | =(format "claude [%s]" basename)= | -| =cj/--ai-vterm-show-or-create= | internal | Given dir + name: display existing buffer, or create vterm + send claude command | -| =cj/ai-vterm= | interactive entry | Composes picker + show-or-create | - -The =display-buffer-alist= entry is added at module load: - -#+begin_src emacs-lisp -(add-to-list 'display-buffer-alist - '("\\`claude \\[" - (display-buffer-in-side-window) - (side . right) - (window-width . 0.5) - (dedicated . t))) -#+end_src - -** Data Flow - -On =M-x cj/ai-vterm=: - -1. Pick a project via =completing-read=. Display in =~/relative= form. Return absolute path. -2. Compute buffer name: =claude [<basename-of-dir>]=. -3. Branch: - - *Buffer exists with live process* → =display-buffer= it. Side-window rule routes it to the right slot. - - *Buffer exists, dead process* → kill it (log last 200 chars to =*Messages*=), then fall through to create. - - *No buffer* → =let=-bind =default-directory= to picked dir and =vterm-buffer-name= to computed name; call =(vterm)=. After process is live, send =claude "Read .ai/protocols.org and follow all instructions."= via =vterm-send-string= + =vterm-send-return=. -4. =select-window= on the displayed window so point lands in Claude. =C-u= prefix shows without selecting. - -After this, all navigation is handled by existing global bindings: Shift-arrows (windmove) for focus, C-M-arrows (=buffer-move=) for directional side-swap. - -** Error Handling - -| Case | Response | -|------+----------| -| Picker cancelled (=quit=) | Silent no-op | -| No candidates found | =user-error= naming the search roots | -| Picked dir disappeared between scan and launch | =user-error= naming the path | -| Existing buffer with dead process | Kill + recreate; log last 200 chars | -| Side-window already showing a different =claude [...]= | =display-buffer= swaps which buffer occupies the slot; hidden one keeps running | -| =vterm= not installed | Module fails to load loudly (no graceful degradation) | - -** Per-project tmux sessions - -The launch command sent to a fresh AI-vterm shell is - -#+begin_example -tmux new-session -A -s <basename> -c <dir> '<claude-cmd>; exec bash' -#+end_example - -- =-A= reattaches to an existing session of the same name instead of creating a new one. So a second F9 on the same project after an Emacs crash brings the running Claude back without spawning a duplicate. -- =-s <basename>= names the session after the project's directory basename. =tmux ls= shows the active sessions by project name. -- =-c <dir>= sets the start directory for new sessions (ignored on attach). -- =exec bash= tails the shell command so the tmux window survives Claude exiting -- the session stays alive with a bare prompt for recovery, and reattach is unaffected. - -** Tmux Auto-Launch Suppression - -The existing =cj/vterm-launch-tmux= on =vterm-mode-hook= types =tmux\n= unconditionally for any vterm buffer. AI-vterm =let='s a dynamic =cj/--ai-vterm-suppress-tmux= flag around =(vterm)= so the hook skips its bare =tmux\n= and the project-named launch command (above) runs instead. - -** Testing - -Pure helpers tested against real inputs: - -- =cj/--ai-vterm-buffer-name= — Normal, Boundary (trailing slash, dot-prefix dirs, spaces in basenames), Error (degenerate paths). -- =cj/--ai-vterm-candidates= — temp directory tree built with =make-temp-file= + =make-directory=, fake =.ai/protocols.org= markers. Assert returned paths, ignored entries. - -Internal with mocked boundary: - -- =cj/--ai-vterm-show-or-create= — =cl-letf= on =vterm= to skip process spawn; assert buffer name, =default-directory=, claude argv via captured =vterm-send-string= calls. Two branches (exists vs creates) tested with mocked =process-live-p=. - -Display rule: - -- After =add-to-list=, =display-buffer= on a buffer named =claude [test]= lands in a window with =(window-parameter w 'window-side) = 'right=. - -Test files: - -- =tests/test-ai-vterm--candidates.el= -- =tests/test-ai-vterm--buffer-name.el= -- =tests/test-ai-vterm--show-or-create.el= -- =tests/test-ai-vterm--display-rule.el= - -Smoke test (=:slow= tag, excluded from default suite): launch against a fixture, verify live process. - -* Open Questions - -- [ ] Default split width — 50/50 vs 60/40 weighted to code. Starting with 50/50. -- [X] Keybinding — F9. Replaces the prior =cj/toggle-gptel= binding on F9; gptel moves to C-F9. - -* Next Steps - -- TDD implementation in this order: =buffer-name= → =candidates= → =show-or-create= → display rule → interactive entry. -- Wire into =init.el= after =eshell-vterm-config=. -- Pick a keybinding once the command is shipped. |