This package builds upon the excellent work of:
- eat - Terminal emulator inside Emacs
- claudemacs - Claude AI integration for Emacs
We extend our deepest gratitude to the authors and contributors of these foundational packages.
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)
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.)
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.
Dependency for a terminal emulator, eat
What we want to do is to develop software services. As various tools and services emerge, I don’t want to spend time developing tools. Therefore, with the expectation that CLIs will be the main interface for programmers, I will fully commit to relying entirely on the terminal emulator, eat.
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.
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.
- Emacs 28.2 or later
- eat (0.9.4 or later)
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 (28.1+), compatibility with other environments has not been verified.
(straight-use-package
'(enkan-repl :host github :repo "phasetr/enkan-repl"))- Download
enkan-repl.el - Add to your Emacs configuration:
;; Add to load path
(add-to-list 'load-path "/path/to/enkan-repl")
;; Load the package
(require 'enkan-repl)- Create a dedicated project directory:
mkdir my-claude-project cd my-claude-project - Initialize Git repository:
git initThis ensures Claude sessions are isolated and changes are tracked safely.
- Open project file:
M-x enkan-repl-open-project-input-file - Start eat session:
M-x enkan-repl-start-eat - Write your thoughts in the input org-mode file
- Access functions easily: Use
M-x enkan-repl-cheat-sheetto browse and select functions - Send specific parts using
M-x enkan-repl-send-regionorM-x enkan-repl-send-rest-of-buffer
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.
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.
Important: Buffer naming format has changed from *enkan:/path* to *ws:01 enkan:/path*.
- All sessions are scoped to workspace
ws:01 - Session discovery only finds buffers in the current workspace
- Setup/teardown operations affect only the current workspace
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
enkan-repl-open-project-input-file- Create/open persistent input file for current directory
enkan-repl-send-region- Send selected text (the author most commonly used)enkan-repl-send-line- Send current line onlyenkan-repl-send-enter- Send enter keyenkan-repl-send-1/2/3- Send numbered choices for AI promptsenkan-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.
enkan-repl-start-eat- Start eat terminal emulator session in current directory. Simplified version for use within setup functions only. FORCE parameter ignored - always starts new session.enkan-repl-teardown- Terminate eat session(s) based on context. - Standard input file: terminate single eat session for current directory in current workspace - Center file: terminate all registered sessions in current workspaceenkan-repl-setup- Arrange windows for (the author’s) optimal workflow
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.enkan-repl-workspace-delete- Delete a workspace. Cannot delete the current workspace or the only workspace. Uses `hmenu’ if available to show workspace ID with its project.
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"))));; 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.
make checkThis runs the all test suite including linting, byte compilation, and documentation checks.
This project uses automated releases via semantic-release. New versions are automatically published to GitHub Releases and a CHANGELOG.md is generated based on Conventional Commits. You can find detailed release notes in the CHANGELOG.
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.
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.
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:
- Human → AI (Reasoning): We pose questions to thoughtful AI assistants like Claude
- AI → AI (Search): Claude consults specialized search AIs like Gemini for comprehensive information
- AI → Human Knowledge: These search engines access humanity’s accumulated wisdom
- 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
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.
This project is licensed under the MIT License - see the LICENSE file for details.