enkan-repl (円環-REPL)

This package builds upon the excellent work of:

• tmux - Terminal multiplexer (current default backend)
• eat - Terminal emulator inside Emacs (legacy / opt-in backend)
• claudemacs - Claude AI integration for Emacs

We extend our deepest gratitude to the authors and contributors of these foundational packages.

Quick note on the terminal backend (read this first)

As of the terminal-backend abstraction work, enkan-repl ships with tmux as the default backend. Heavy modern TUIs (e.g. Claude Code’s welcome screen, codex) overwhelmed eat’s pure-elisp output processing and could lock Emacs’s main loop. Delegating the terminal to an external tmux server keeps that work entirely outside Emacs and preserves session continuity across Emacs restarts.

eat remains fully supported as an opt-in backend; both share the same front-end API (enkan-repl-send-line, etc.). See #terminal-backend below for switching, configuration, and migration notes.

Vision - The Law of Cycles (円環の理) for the AI Era

enkan-repl embodies the concept of “円環の理” (enkan no kotowari / Law of Cycles) - the eternal cycle of questions and answers, learning and understanding.

The name draws from Japanese anime culture, especially the famous 魔法少女まどか☆マギカ, while carrying profound philosophical meaning:

• 円環 (enkan): The circle or torus, representing the eternal loop of REPL interactions; also fundamental objects in modern mathematics
• 理 (kotowari): The principle, the underlying truth we discover through dialogue

This package differs technically from traditional REPLs (Read-Eval-Print Loop). While conventional REPLs execute code and return results, enkan-repl sends text to AI assistants and receives generated responses. Yet this represents not a limitation, but a new dimension of interactive development.

Our dream is to revive the interactive development culture that LISP, Elisp, and Emacs have nurtured for decades, in a form befitting the AI era. Through the eternal cycle of sending thoughts and receiving AI responses, we access what feels like an Akashic Record - the accumulated knowledge of humanity, filtered through advanced AI understanding.

Send your thoughts with send-region, receive AI’s response, and deepen your thinking further. This cycle - this 円環 (enkan) - is the development experience that the new era’s REPL envisions. Here lies a completely new programming horizon woven by Emacs and AI.

(See Why “enkan”? and Future Directions for more details about the philosophy and roadmap)

Motivation

The development motivation stems from the current (2025/8) usability issues with Claude Code and Gemini CLI, particularly the difficulty of text input and the non-persistent nature of personal input history. While file-based input is somewhat possible, it’s extremely cumbersome to use.

In terminals, input and copy-paste operations are difficult, making revisions troublesome. Furthermore, when something comes to mind during AI work, you need to leave the terminal to take notes, creating an extremely unpleasant development experience.

Additionally, when security constraints are enforced to prevent dangerous command execution, you’re frequently prompted for permission approvals. Constantly switching to the terminal for these confirmations becomes highly tedious. Even when stopping runaway processes, you must navigate to the terminal and press Esc.

I constantly wished for the ability to easily take notes in text files and send only the necessary parts as commands to AI, keeping inspired thoughts noted for immediate use after AI work is complete. For text work, I naturally turned to Emacs. After trying several packages that didn’t quite fit, I decided to build my own on top of claudemacs. In reality, various CLIs appear daily, and their performance improves at their own pace. It would be inconvenient if we couldn’t use them interchangeably. Therefore, to cut individual dependencies, we decided to use Emacs’s terminal emulator, eat.

This package enables you to send numbered choices directly from your input file using functions like M-x enkan-repl-send-1/2/3. To stop runaway processes, use M-x enkan-repl-send-escape from your input file - no terminal navigation required. (Note: We provide no default keybindings, so you may prefer mapping these to keys like C-g or configure them according to your preferences.)

Design Philosophy

Org-mode Only Choice

This package exclusively uses Org-mode for input files, leveraging Emacs’s native compatibility and structured document capabilities. Rather than supporting multiple formats like Markdown, we focus on what works best within the Emacs ecosystem.

Terminal backend dependency

What we want to do is develop software services. As various tools and services emerge, we do not want to spend time developing terminal infrastructure. Therefore, with the expectation that CLIs will be the main interface for programmers, we delegate terminal work to a purpose-built backend chosen via the enkan-repl-terminal-backend defcustom:

• tmux (default) – external tmux server. Heavy TUIs and large output volumes are processed by tmux outside of Emacs, so they cannot stall Emacs’s main loop. Sessions also survive Emacs restart and can be attached from any other terminal application.
• eat (legacy / opt-in) – in-Emacs eat terminal emulator. Kept as a rollback path for users whose workflow does not involve heavy TUIs and who prefer a fully in-Emacs terminal.

See #terminal-backend for switch / configuration / migration details.

No Default Keybindings

We intentionally provide no default keybindings for several reasons:

• Org-mode itself already has a vast number of features and keybindings
• Serious Emacs users (especially those who don’t “cheat” with VSCode) may have their own customization patterns
• Avoiding conflicts with existing user workflows

Even if your Emacs configuration is heavily customized with no available keybindings, the interactive cheat-sheet (M-x enkan-repl-cheat-sheet) provides quick access to all functions with fuzzy search and filtering capabilities.

M-x Driven Workflow with Interactive Cheatsheet

As the author’s personal approach, we introduce a “partial keybinding abandonment + cheat-sheet strategy.” Since there’s little potential harm, we assigned some key-bindings, like numbers and Esc, as buffer-local variables. We also bound the central sending command send-region to a key, also as a buffer-local variable. For everything else, we abandoned keybinding configurations since they’re rarely used.

Instead, we added a cheat-sheet feature to quickly access only the commands you need. You can filter by keywords directly related to the operation you want to perform. For infrequently used operations, this overhead is perfectly acceptable. At least for me.

You could assign a keybinding to the cheat-sheet itself, but I can’t remember them. My memory/configuration approach doesn’t align well with this - I get confused thinking “is it ‘c’ for cheat-sheet? or ‘s’ for sheet? wait, did I use ‘open’ somewhere, so ‘o’?” even though ‘open’ isn’t even in the actual command name.

Furthermore, once you decide on settings, you want to reuse them to some extent. To make this easy, we made it possible to specify your own default configuration file. We also added enkan-repl-output-template to output your custom configuration file to a temporary buffer, making it as easy as possible to reconfigure multiple files.

The interactive cheat-sheet (M-x enkan-repl-cheat-sheet) makes this workflow even more practical by providing:

• Command Palette: Quick access to all functions with descriptions
• Fuzzy Search: Type partial names to find functions instantly
• Categorized Organization: Functions grouped by purpose (Text Sender, Session Controller, Utilities)
• No Memorization Required: Browse available functions without remembering exact names

During Claude development work, frequently used functions naturally appear at the top of completion lists, and the cheat-sheet ensures you never miss useful functionality.

Installation

Prerequisites

• Emacs 30.1 or later
• tmux for the default backend
• eat (0.9.4 or later) only when using the legacy eat backend

Note: This package has been developed and tested exclusively on macOS with GNU Emacs 30.1. While it should work on other platforms and Emacs versions (30.1+), compatibility with other environments has not been verified.

Using straight.el (Recommended)

(straight-use-package
  '(enkan-repl :host github :repo "phasetr/enkan-repl"))

Manual Installation

1. Download enkan-repl.el
2. Add to your Emacs configuration:

;; Add to load path
(add-to-list 'load-path "/path/to/enkan-repl")

;; Load the package
(require 'enkan-repl)

Quick Start

For New Projects (Recommended)

1. Create a dedicated project directory:

   mkdir my-claude-project
   cd my-claude-project
       

2. Initialize Git repository:

   git init
       

   This ensures Claude sessions are isolated and changes are tracked safely.

3. Open project file: M-x enkan-repl-open-project-input-file
4. Start terminal session: M-x enkan-repl-start-session
5. Write your thoughts in the input org-mode file
6. Access functions easily: Use M-x enkan-repl-cheat-sheet to browse and select functions
7. Send specific parts using M-x enkan-repl-send-region or M-x enkan-repl-send-rest-of-buffer

For Existing Projects

Important: claude automatically detects Git repositories or something and may start sessions in parent directories: see the usage section for claudemacs. Please refer to the respective manuals for other CLIs.

To ensure predictable behavior:

• Work within properly initialized Git repositories (git init)
• Or use dedicated project directories as shown above

The generated project file includes template functions and usage instructions.

Workspace Support

Overview

enkan-repl now includes workspace functionality for managing multiple projects concurrently. Currently operates with a single fixed workspace (ws:01), with multi-workspace support planned for future releases.

Breaking Changes

Important: Buffer naming format has changed from *enkan:/path* to *ws:01 enkan:/path*.

Workspace Behavior

• All sessions are scoped to workspace ws:01
• Session discovery only finds buffers in the current workspace
• Setup and deletion operations affect only the current workspace

Core Functions

Command Palette

• enkan-repl-cheat-sheet - Interactive command browser with fuzzy search
  • Browse all available functions with descriptions
  • Filter functions by typing partial names
  • Functions organized by category for easy discovery
  • No need to memorize function names

File Management

• enkan-repl-open-project-input-file - Create/open persistent input file for current directory

Text Sending

• enkan-repl-send-region - Send selected text (the author most commonly used)
• enkan-repl-send-line - Send current line only
• enkan-repl-send-enter - Send enter key
• enkan-repl-send-1/2/3 - Send numbered choices for AI prompts
• enkan-repl-send-4 - Send \=’4\=’ to enkan session buffer with optional PFX. - From enkan buffer: Send to current buffer - From other buffer without prefix: Interactive buffer selection - With numeric prefix: Send to buffer at index (1-based) Uses unified backend with smart buffer detection.
• enkan-repl-send-5 - Send \=’5\=’ to enkan session buffer with optional PFX. - From enkan buffer: Send to current buffer - From other buffer without prefix: Interactive buffer selection - With numeric prefix: Send to buffer at index (1-based) Uses unified backend with smart buffer detection.

Session Control

• enkan-repl-start-session - Start a terminal session in the current directory. This is the backend-neutral session starter. It works with both the eat and tmux terminal backends configured by `enkan-repl-terminal-backend’. FORCE is accepted for interactive compatibility and currently ignored; the command always starts a new session.
• enkan-repl-setup - Arrange windows for (the author’s) optimal workflow
• enkan-repl-workspace-delete - Delete a workspace and stop all associated terminal resources. This is the only interactive workspace deletion command. In `enkan-repl-workspace-list-mode’, delete the workspace at point; otherwise delete the current workspace. With prefix ARG, prompt for a workspace. Noninteractive string ARG deletes that workspace ID. All paths use `enkan-repl–delete-workspace-completely’.

Utilities

• enkan-repl-tmux-reattach - Reconnect Emacs state to live tmux sessions. FILE defaults to `enkan-repl-state-file’. Live tmux sessions whose names start with `enkan-repl-tmux-session-prefix’ define the workspaces to restore. When a matching persisted workspace exists, its saved state is reused. When no saved state exists for a live tmux session, a minimal workspace is imported from the tmux session’s windows so reattach works after Emacs state was lost. Imported tmux window names become the workspace aliases used by send commands, workspace-list path display, and project-directory selection. This command is intentionally manual; enkan-repl does not reattach on load.
• enkan-repl-recenter-bottom - Recenter all enkan terminal buffers at bottom.
• enkan-repl-toggle-global-mode - Toggle enkan-repl global mode on/off.
• enkan-repl-workspace-switch - Switch to another workspace. Uses `hmenu’ if available to show workspace ID with its project.

Configuration

Terminal Backend (tmux default, eat opt-in)

The terminal backend is selected at session-creation time via a single defcustom. Default is tmux:

;; Default (no need to set explicitly):
(setq enkan-repl-terminal-backend 'tmux)

;; Opt-in legacy (in-Emacs eat):
(setq enkan-repl-terminal-backend 'eat)

Existing sessions are not migrated when the value changes; only sessions created after the change use the new backend. Both backends share the same user-facing send / layout commands (enkan-repl-send-line, enkan-repl-setup-current-project-layout, etc.).

tmux backend specifics

• Workspace NN maps to tmux session enkan-NN (prefix is configurable via enkan-repl-tmux-session-prefix).
• Each project alias becomes a tmux window in that session. Multiple instances of the same project become alias, alias-2, alias-3, … with the corresponding *ws:NN enkan:/path/*<N> mirror buffers inside Emacs.
• A read-only mirror buffer can be updated via tmux capture-pane so the layout / send-line code can find sessions via the usual buffer-list mechanism. Mirror refresh is manual by default: displaying or recreating a mirror buffer does not capture pane content. Press g in a mirror buffer, or run M-x enkan-repl-tmux-refresh-current, to refresh it. Automatic timer refresh is opt-in via (setq enkan-repl-tmux-mirror-auto-refresh t) and then uses enkan-repl-tmux-mirror-interval seconds. Disable mirroring with (setq enkan-repl-tmux-mirror nil) if not desired.
• Mirror refresh keeps a bounded recent view by default: 320 captured lines, 240 displayed lines, 256 KiB of content, and 2048 characters per line before truncation. Large diff-like/noisy blocks are still compacted.
• Mirror buffers show refresh state in the header line (refreshing, hidden, fresh, unchanged, closed).
• Run M-x enkan-repl-tmux-refresh-workspace to recreate or force refresh all tmux mirror buffers for the currently selected workspace. This is useful when tmux windows exist but the Emacs-side mirrors are stale or missing.
• M-x enkan-repl-tmux-attach launches an external terminal app and attaches to the current workspace’s tmux session. The attach command is configurable via enkan-repl-tmux-attach-command (a format string with %s for the session name, or a function).
• M-x enkan-repl-tmux-kill-session kills a single enkan-* session; M-x enkan-repl-tmux-kill-all-enkan confirms then kills all of them.
• Persistent state is stored at enkan-repl-state-file (~/.emacs.d/enkan-repl-state.eld by default). enkan-repl does not automatically reconnect Emacs to live tmux sessions on startup. Run M-x enkan-repl-tmux-reattach when you want to manually reconnect. Live enkan-* tmux sessions define the workspaces to restore. When saved state exists for a live workspace it is reused; when it does not, enkan-repl imports a minimal workspace from the tmux windows so the session can be used again. Imported tmux window names become workspace aliases, so enkan-repl-send-line, enkan-repl-workspace-list, and enkan-repl-open-project-directory can resolve every live window even when the Emacs state file was missing. Reattach ensures mirror buffers exist, but it avoids force-refreshing every restored workspace; use M-x enkan-repl-tmux-refresh-workspace when you explicitly want to refresh the current workspace’s mirror contents.

eat backend specifics

eat behavior is unchanged from before the abstraction work. All existing eat-specific commands and buffer naming remain intact. Use this backend if you want to keep the terminal entirely inside Emacs.

Migration history (why tmux became the default)

The latest claude CLI welcome screen sends thousands of cursor / color escape sequences which eat--t-write processes one character at a time in pure elisp. Combined with frequent display geometry changes (narrow window splits, expanding minibuffer), this consistently locked Emacs’s main loop – verified via SIGUSR2 backtrace from a frozen session showing all CPU samples in timer-event-handler -> eat--process-output-queue -> eat-term-process-output -> eat--t-write.

Switching to tmux moves the terminal emulation entirely out of Emacs; Emacs only periodically reads the rendered pane content into a read-only mirror. Heavy TUI repaint storms no longer touch the Emacs main loop, and tmux sessions survive Emacs crashes.

The abstraction layer (enkan-repl-terminal.el) keeps the eat path fully working as a rollback option for environments where the tmux default is not desired.

Center File and Multi-Project Management

The center file enables management of multiple projects simultaneously:

;; Set center file path (enables multi-project functionality)
(setq enkan-repl-center-file "~/my-projects/center.org")

;; Define project directories with aliases
(setq enkan-repl-target-directories
      '(("pt" . ("pt-tools" . "/path/to/pt-tools/"))
        ("er" . ("enkan-repl" . "/path/to/enkan-repl/"))
        ("eat" . ("emacs-eat" . "/path/to/emacs-eat/"))))

;; Configuration list for frequently used simultaneous project startup
(setq enkan-repl-projects
      '(("web-dev" . ("er" "pt" "cc"))
        ("data-analysis" . ("pt" "jupyter" "postgres"))))

Template Customization

;; Use default template
(setq enkan-repl-template-file nil)

;; Use custom template file
(setq enkan-repl-template-file "~/my-claude-template.org")

;; Use project-specific template
(setq enkan-repl-template-file (expand-file-name "claude-template.org" user-emacs-directory))

To create a custom template, use M-x enkan-repl-output-template to export the default template to a buffer for editing.

Development

Running Tests

make check

This runs the all test suite including linting, byte compilation, and documentation checks.

Releases

This project uses automated releases via semantic-release. New versions are automatically published to GitHub Releases based on Conventional Commits. You can find detailed release notes on the GitHub Releases page.

Note: The `semantic-release` toolchain is used for development/release automation only. The Elisp package itself has no Node.js runtime dependencies and can be installed normally via MELPA.

Contributing

We welcome various issues and pull requests. However, please understand that due to leukemia recurrence in June 2024 and ongoing treatment, response times may be affected.

Ironically, it was precisely this situation that motivated the development of this package - to continue enjoying programming even under these circumstances. The desire to maintain productive development workflows during challenging times drove the creation of enkan-repl.

While I have extensively used OSS over the years, I never imagined I would find myself on the OSS development side under these circumstances. I have received almost no pull requests for repositories published on GitHub, please bear with me as responses may take longer than usual while I learn the process.

Note: I wanted to automate version updates like semver as much as possible, so I had Claude Code (and Gemini) automate it, and it recommended using Node.js mechanisms, which I have adopted. I’m not sure if this is the right approach, but I’ll run with it for now.

Why “enkan” (円環, circle/torus)?

The journey to this name reflects our philosophy:

• Initially cer (ClaudEmacs-Repl), it evolved as we recognized the tool transcends any single AI
• “enkan” represents the eternal cycle of knowledge exchange through multiple layers:
  1. Human → AI (Reasoning): We pose questions to thoughtful AI assistants like Claude
  2. AI → AI (Search): Claude consults specialized search AIs like Gemini for comprehensive information
  3. AI → Human Knowledge: These search engines access humanity’s accumulated wisdom
  4. Knowledge → Human: The insights return to us, transformed and synthesized
• This multi-layered cycle forms the true 円環 (circle) of modern knowledge work
• It captures the mathematical beauty of circles or tori and the philosophical depth of eternal recurrence
• Short (5 letters), internationally pronounceable, yet distinctly rooted in Eastern philosophy

Future Directions

This package is currently built on Claude Code due to the overwhelmingly superior experience it provides within my current usage scope. However, if superior services emerge that surpass Claude Code through future technological and service developments, I intend to migrate to those alternatives. We are actually switching to relying on terminal emulators, anticipating the rise of CLI services for programmers.

The “enkan” philosophy already embraces multiple AI collaboration: We leverage Claude’s exceptional reasoning capabilities while compensating for its limited search abilities by instructing it to “consult Gemini with gemini -p for research.” This Human-Claude-Gemini-Knowledge chain exemplifies the multi-AI collaboration that defines our approach.

Ideally, I would like to enable seamless switching between or combining multiple services, making the entire AI ecosystem work as one harmonious 円環 (circle).

Parts that are tightly coupled to Claude Code represent critical weaknesses. Therefore, please be aware that breaking changes, including package name changes, may be introduced. Indeed, the recent rename from claudemacs-repl to enkan-repl is part of this philosophy - recognizing that the tool’s essence transcends any single AI service.

This package also serves as my personal research tool for exploring challenges on the path to achieving that goal.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

• 🐛 Issue Tracker
• 💬 Discussions