The Problem
Developers who spend most of their day inside Emacs lack a native, interactive console for prompting LLM agents that follow the Agent Client Protocol (ACP). Switching to a terminal or web UI breaks workflow and forces context switches, slowing coding, debugging, and code‑review cycles.
What This Does
agent-shell implements an Emacs major mode that opens a buffer acting as a chat terminal for any ACP‑compatible LLM backend (Claude, Gemini, OpenAI, etc.). Core logic lives in agent-shell.el, which defines the mode, keymap, and buffer lifecycle. Backend‑specific adapters are in files such as agent-shell-openai.el, agent-shell-anthropic.el, agent-shell-google.el, and agent-shell-mistral.el. UI helpers (agent-shell-ui.el, agent-shell-viewport.el) render messages, while agent-shell-heartbeat.el monitors the running agent process.
How To Use It
Setup
Install Emacs ≥ 27.1. Add the repository to your load-path (e.g., ~/.emacs.d/lisp/agent-shell). Ensure the external ACP binaries required for your chosen agents are on PATH (see the External dependencies section of README.org). Example for Claude Code:
npm install -g @zed-industries/claude-code-acp which claude-code-acp # must resolve
Configuration
Edit your init file to load the package and select a backend. The adapters expose customizable variables; for OpenAI the relevant file is agent-shell-openai.el and the variable is agent-shell-openai-key. Example:
(add-to-list 'load-path "~/.emacs.d/lisp/agent-shell") (require 'agent-shell)
(setq agent-shell-openai-key "sk-xxxxxxxxxxxxxxxx") (setq agent-shell-default-backend 'openai) ;; defined in agent-shell.el
Other agents follow the same pattern (agent-shell-anthropic.el uses agent-shell-anthropic-key, etc.). No additional config files are shipped.
Running It
Start a shell with the interactive command defined in agent-shell.el:
M-x agent-shell
A buffer named agent-shell appears. Type a prompt, press RET, and the selected ACP client will stream the response back into the buffer. The UI automatically folds long outputs (agent-shell-viewport.el) and updates the mode line with activity (agent-shell-heartbeat.el).
Real‑World Use
A developer working on a Python module can open agent-shell, issue:
Explain the time‑complexity of this function: def foo(lst): return [x2 for x in lst if x > 0]
The response is inserted directly into the buffer, ready for copy‑paste or further refinement, keeping the entire edit‑review loop inside Emacs.
Code Health & Issues
Med – Missing CI/CD – No workflow files under .github/workflows; automated testing is not gated. (.github/ISSUE_TEMPLATE exists but no CI.) Low – Limited Test Coverage – 9 test files exist (tests/agent-shell-.el) but they focus on the runner and fakes; core UI functions lack unit tests. Low – Dependency Documentation – README lists several external binaries, but version constraints or verification scripts are absent; users may encounter runtime errors if an ACP client changes its CLI. Low – License Present – LICENSE is supplied (MIT), satisfying legal reuse. Low – Emacs‑Lisp Conventions – Files use provide/require correctly; however, some adapters (agent-shell-openai.el) embed raw shell command strings without escaping, which could lead to injection if user input is not sanitized.
Overall the code follows idiomatic Emacs Lisp, with clear separation between protocol handling, UI rendering, and backend adapters.
The Bottom Line
agent-shell delivers a functional, Emacs‑native chat front‑end for any ACP‑compatible LLM, enabling developers to stay inside their primary editor. The implementation is clean and well‑documented, but the project lacks automated CI and comprehensive test coverage, so teams should validate critical workflows before production use. Suitable for solo developers or small teams that already use Emacs and are comfortable managing external ACP binaries.