agent-shell: an Emacs buffer that speaks ACP to Claude, Codex and Gemini agents
A native Emacs buffer to interact with LLM agents powered by ACP
At a glance
- What is it?
- agent-shell is a GPL-3.0 Emacs package that puts an ACP client inside a native buffer, so the same UI drives any agent that implements the Agent Client Protocol. The design bet is protocol neutrality; the cost is that the agent process itself stays outside Emacs.
- Who is it for?
- Adopt agent-shell if you already live in Emacs, want one buffer UI across several agent CLIs, and are willing to install a Node-based ACP adapter for whichever agent you use. Do not adopt it if you need a terminal multiplexer, a browser UI, or an environment where you cannot install the underlying agent binaries.
- Can I use it commercially?
- Yes, with conditions. GPL-3.0 is a copyleft licence: if you distribute software that includes it, you must release that software's source code under the same licence. Running it internally without distributing it does not trigger that obligation.
- Is it still maintained?
- Yes. The repository last received commits 1 day ago.
- What is it written in?
- Mainly Emacs Lisp, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The problem is not the model, it is the terminal you talk to it from
Most coding agents ship as command line programs. Claude Agent, Codex, Gemini CLI, Goose, OpenCode and the rest each bring their own REPL, their own keybindings, their own idea of what a session looks like. If you work inside Emacs, every one of those is a context switch: a terminal emulator, a different scrollback, no access to your buffers, your project files or your Org notes. agent-shell is aimed at that gap. The README describes it as "a native Emacs shell to interact with LLM agents powered by ACP", and the audience is narrow and specific: Emacs users who already run at least one of these agents and would rather not leave the editor to do it. It is not a general chat client, and it is not trying to be one.
ACP is the actual product boundary
The mechanism worth understanding is the Agent Client Protocol. agent-shell does not implement a provider-specific integration for Anthropic or OpenAI. It relies on acp.el, a separate package by the same author, to speak ACP to whatever agent process is running. The README is explicit: "agent-shell relies on acp.el to communicate with agents via ACP". That means the data flow is roughly: Emacs buffer sends a prompt, acp.el encodes it as ACP messages, the agent process (Claude Agent, Codex, Gemini CLI, Goose and the others listed) receives them over its stdio or socket transport, and responses come back into the same buffer. The practical consequence is that adding a new agent is the agent vendor's job, not the package's. The README lists seventeen agents, from Claude Agent and Codex through to Mistral Vibe, Factory Droid and Antigravity. That list is long because the protocol is the integration point, not because the author wrote seventeen clients.
What the third-party package list tells you about the core
The README devotes a large section to related projects, and that section is more informative than it first looks. There are add-ons for sidebars, bookmarks, tab-bar workspaces, a tabulated session manager, desktop notifications, a mode-line attention tracker, Org-mode transcripts, an Org Babel backend, Tramp integration, LaTeX math rendering, a floating HUD, and even a "pet" that broadcasts session state. A package does not accumulate that many satellites unless the core leaves obvious room around it. agent-shell appears to handle the buffer, the session and the ACP plumbing, and deliberately stops there. Session discovery, notification routing, remote execution over Tramp, and transcript export are all delegated. That is a reasonable split, but it also means a fresh install is thinner than the README's length suggests. You will likely want at least one of these add-ons before the workflow feels complete.
Installation runs through MELPA, but the agent does not come with it
The README carries a MELPA badge, which points at the standard Emacs package route: add MELPA to package-archives, then M-x package-install RET agent-shell. The package itself is Emacs Lisp, so there is no build step and no compiled daemon. What it does not ship is the agent. To talk to Claude Agent you install Anthropic's Claude Agent; to talk to Codex you install the codex-acp adapter from the agentclientprotocol organisation; Gemini CLI, Goose and the others each come from their own repositories and installation instructions. agent-shell is the client half. This is the single most common source of confusion with ACP-based tooling, and the README's related-projects section makes the split clear by linking acp.el separately. There are no releases retrieved in the material supplied, so version pinning has to come from MELPA or from the repository directly.
The failure mode is the process, not the buffer
Because the agent runs as a separate process, anything that breaks that process breaks the shell. If the agent binary is not on PATH, if its ACP adapter is missing, or if the agent exits mid-session, the Emacs buffer has nothing to render. The README does not document a reconnect or supervision story, and the third-party list includes a desktop-save integration that "saves and resumes shells by folder, config, and session id", which suggests session continuity is handled outside the core rather than inside it. There is also a licence and trust dimension: you are running a third-party agent binary, often one that reads your project files and may execute commands. agent-shell does not sandbox it. The related-projects list includes agent-circus, which runs AI coding agents in sandboxed Docker containers, and its existence is a fair signal that sandboxing is not agent-shell's concern.
Where agent-shell is the wrong tool
If you do not use Emacs, nothing here applies to you. If you want a terminal multiplexer workflow with tmux panes and shell history, the agents' own CLIs already do that and adding Emacs in the middle is pure overhead. If you want a browser interface or a hosted chat UI, this is not it. And if you need a single agent working deeply inside one editor's extension API, with editor-native diff views and inline suggestions, agent-shell's buffer model is a different shape: it is a shell, not an IDE integration. The README's own framing, "a native Emacs shell", sets that expectation honestly.
The alternative is not another Emacs package, it is the agent CLI itself
The direct comparison is running Claude Agent, Codex or Gemini CLI in a terminal buffer such as vterm, eat or ansi-term. That approach needs no ACP adapter, no acp.el, and no package updates when the agent changes. It also gives you whatever the agent's own TUI provides, including features the ACP surface may not expose. The difference in approach is where the protocol lives. With a terminal buffer, the agent owns the rendering and Emacs is a dumb pipe. With agent-shell, Emacs owns the rendering and the agent is a protocol peer. That buys structured events, which is what makes the sidebar, notification and transcript add-ons possible at all. It costs you a dependency on the agent's ACP implementation staying in sync. If a vendor ships a new feature only in its TUI, agent-shell will not see it until the ACP adapter exposes it.
Licence and maintenance
agent-shell is GPL-3.0. For personal Emacs configuration that is unremarkable. If you plan to redistribute a modified version, bundle it into a product, or combine it with code under incompatible terms, the GPL-3.0 obligations apply to the combined work, and that is a question for a lawyer rather than a review. On maintenance: the repository is not archived, the last push recorded in the material is 2026-09-08, and the README links a sequence of versioned update posts (0.5, 0.17, 0.25, 0.47, 0.55, 0.63), which indicates steady release activity rather than a one-off dump. The funding section at the top of the README is unusually direct about this: the author asks users to sponsor development because the project depends on ongoing work. Treat that as a signal about sustainability, not as a guarantee. The upgrade path is MELPA plus acp.el plus the agent adapter, and any one of those three moving can require attention.
Editorial conclusion
Adopt agent-shell if you already live in Emacs, want one buffer UI across several agent CLIs, and are willing to install a Node-based ACP adapter for whichever agent you use. Do not adopt it if you need a terminal multiplexer, a browser UI, or an environment where you cannot install the underlying agent binaries. Before committing, verify that the specific agent you care about ships an ACP adapter, that your Emacs version loads acp.el cleanly, and that you are comfortable with GPL-3.0 terms for any distribution you plan.
Community notes