# agent-shell: an ACP client inside an Emacs buffer > xenodium/agent-shell turns Emacs into a front end for ACP-driven coding agents such as Claude Agent, Codex and Gemini CLI. It is a protocol client, not a model, and it asks you to pay for the maintenance. **xenodium/agent-shell** — A native Emacs buffer to interact with LLM agents powered by ACP - Repository: https://github.com/xenodium/agent-shell - Website: https://xenodium.com - Stars: 1,914 · Forks: 241 - Language: Emacs Lisp - License: GPL-3.0 - Published: 2026-09-10 · Updated: 2026-09-10 · Language: en - Canonical page: https://hysenlabs.com/projects/xenodium-agent-shell ## What agent-shell actually is, and who it is for The README describes agent-shell as "a native Emacs shell to interact with LLM agents powered by ACP (Agent Client Protocol)". That sentence contains the whole design. The package does not contain a model, a tokenizer or a prompt strategy. It contains a client for a protocol, and the intelligence arrives from a separate process you install and pay for. The list of supported agents in the README is long: Claude Agent, Codex, Gemini CLI, Goose, Grok Build, Cursor, Kimi Code CLI, CodeBuddy, Kiro CLI, Qwen Code, Auggie, Mistral Vibe, Factory Droid, Pi, Oh My Pi, Opencode and Antigravity. The repository layout backs this up. There are per-agent files such as agent-shell-anthropic.el, agent-shell-openai.el, agent-shell-google.el, agent-shell-xai.el, agent-shell-cursor.el, agent-shell-goose.el, agent-shell-qwen.el, agent-shell-mistral.el, agent-shell-opencode.el, agent-shell-kimi.el, agent-shell-kiro.el, agent-shell-codebuddy.el, agent-shell-auggie.el, agent-shell-droid.el, agent-shell-pi.el, agent-shell-omp.el, agent-shell-cline.el and agent-shell-antigravity.el. The audience is narrow and specific. You already use Emacs as your main environment. You already have an agent CLI installed and authenticated. You would rather see the agent's turns in a buffer you can move through with normal Emacs navigation than in a terminal pane. If any of those three is false, the package has little to offer you. ## The ACP layer, and why agent-shell depends on acp.el The README states plainly that agent-shell "relies on acp.el to communicate with agents via ACP". That is the mechanism. acp.el is a separate package by the same author, and it owns the protocol conversation. agent-shell owns the Emacs side: buffers, faces, completion, diffs, prompts, permissions. This split explains the repository layout better than any feature list. agent-shell-chat-mode.el defines the major mode for a conversation buffer. agent-shell-ui.el and agent-shell-faces.el handle presentation. agent-shell-diff.el handles proposed edits. agent-shell-completion.el and agent-shell-prompt-queue.el handle input. agent-shell-config.el and agent-shell-experimental.el hold configuration and unfinished work. agent-shell-mock-agent.el exists so the UI can be exercised without a real agent behind it, which is a sensible thing to ship in a protocol client. The practical consequence is that a protocol change lands in acp.el, not here, and the two packages version separately. It also means the boundary between "the agent is behaving oddly" and "agent-shell is rendering oddly" is not always obvious from the buffer. The mock agent is the tool for separating the two. ## Installing agent-shell from MELPA and opening a first session The README carries a MELPA badge, so the package is distributed through MELPA. The README does not spell out an installation procedure beyond that badge, and it gives no configuration snippet, no command name and no keybinding. Anything beyond the badge would be invention, so this section stays with what the repository actually shows. The badge links to https://melpa.org/#/agent-shell, which is where the package page lives and where the install path starts. From there you use Emacs' own package manager against the MELPA archive, and the package name is agent-shell, matching the repository and the badge. What the README does make clear is the prerequisite: you need at least one supported agent CLI installed and authenticated on the same machine, because the Emacs side only speaks ACP to a process that already exists. The related search term "Doom Emacs agent-shell" suggests people are configuring it under Doom, but the README gives no Doom recipe and no use-package block, so treat that as community practice rather than documented setup. For configuration details, the repository is the source. agent-shell-config.el is the file that holds configuration, and the README's news list points to blog posts at xenodium.com for feature explanations rather than repeating them inline. ## The ecosystem around agent-shell is unusually large The README lists more than twenty related projects, and that list is the most informative part of the document. agent-shell-sidebar adds a sidebar. agent-shell-manager adds a tabulated view of sessions. agent-shell-workspace gives each session a tab-bar workspace. agent-shell-hq and agent-shell-dashboard organise many sessions by project. agent-shell-bookmark, agent-shell-links.el and agent-shell-desktop.el add bookmarks, Org links and desktop save mode. Others push in different directions. agent-circus runs agents in sandboxed Docker containers. agent-shell-tramp adds Tramp integration. agent-shell-to-go exposes sessions over Slack. ob-agent-shell makes agent-shell a Babel backend. agent-shell-org-transcript writes sessions to Org with org-roam integration. agent-shell-notifications and agent-shell-knockknock handle alerting. Read this as a signal about the core package, not as a feature list. So much of the ecosystem is about managing multiple sessions, resuming them and being told when they finish, which tells you the base package is a single-buffer conversation view and that heavy users quickly grow past one buffer. If your workflow is one agent, one buffer, you need none of it. ## Where agent-shell is the wrong choice The dependency on an external agent process is the main limitation, and it is structural rather than a bug. agent-shell cannot answer anything on its own. If the agent CLI is not installed, not authenticated, or not reachable, the buffer has nothing to talk to. The README's own claim that you can "interact with any ACP-driven agent" is a statement about the protocol, not about coverage: an agent that does not speak ACP is out of scope regardless of how good it is. The second limitation is the funding model, stated at the top of the README under the heading "This project needs your funding". The author asks users to sponsor development and maintenance, framing sponsorship as what makes the effort sustainable. That is an honest arrangement, but it means the project's continuity rests on individual sponsorship rather than on a company with a commercial interest in the client. The last push to the repository was on 2026-09-08, so the project is current, but the README gives no roadmap commitments and no support guarantees. The third is documentation depth. The README functions as an index: badges, a sponsor appeal, an agent list, video links, a news list and a long related-projects list. Configuration keys, permission prompts and the exact behaviour of the per-agent files are not described there. The news posts are where feature explanations live, and the repository files are where the actual behaviour lives. A reader who wants a single document that explains configuration will not find it in the README. ## agent-shell compared with gptel and with an agent's own IDE integration Two comparisons are worth making, and the search data shows people making both. gptel is an Emacs package for talking to LLM APIs directly. The difference is architectural. agent-shell talks to a local agent process over ACP; the agent owns tools, file access and multi-step work. gptel talks to a model endpoint; the Emacs package owns the request and you own the orchestration. If you want a chat interface to a model inside Emacs, the direct API route is the shorter path. If you want an agent that edits files and runs commands under a permission model, the protocol route is the one that gives you that. The other comparison is against an agent's own IDE integration, such as the Claude Code editor plugins. Those ship a purpose-built interface with the vendor's own assumptions about layout and workflow. agent-shell gives you the agent inside Emacs, which means your keybindings, your Org files, your diff tooling and your window management apply. The trade is that you are relying on a third-party client to track a protocol the vendor controls, and the per-agent files in this repository are the evidence of that ongoing work. ## Licence, maintenance and what an upgrade costs you agent-shell is GPL-3.0. That matters if you redistribute it or build on it: derivative work carries the same licence. It does not restrict using the package in your own Emacs configuration. This is a description of the licence identifier in the repository, not legal advice. The maintenance picture is straightforward. The repository is not archived, and the last push was on 2026-09-08, which is recent. There are no retrieved releases, so the MELPA package is the practical distribution channel and upgrades arrive through the package manager rather than through tagged releases you pin. The README's news list runs from 0.5 through 0.63, which tells you the version line has moved a great deal and that behaviour has changed repeatedly across it. Upgrade cost is therefore real but bounded. Because the protocol layer sits in acp.el and the agent-specific behaviour sits in per-agent files, an upstream agent change can require a new agent-shell version before your agent works again. Budget for the possibility that an agent update and a client update have to land together. The mock agent is the cheapest way to confirm the Emacs side still works when an agent is the suspect. ## Conclusion agent-shell is for Emacs users who already pay for an ACP-capable agent and want the conversation inside their editor rather than a terminal tab, and who accept that the package is funded by sponsorship rather than by a vendor. It is the wrong tool if you want a self-contained assistant with no external process, or if you refuse to install a separate agent CLI first. Before adopting, verify that your chosen agent actually speaks ACP, check which of the per-agent files in the repository matches it, and read the permission handling in agent-shell-config.el, because that is the layer that decides what the agent may do without asking. ## FAQ ### What is agent-shell? It is a native Emacs shell for interacting with LLM agents that speak the Agent Client Protocol, described in the README as "a native Emacs shell to interact with LLM agents powered by ACP". It provides the Emacs buffer and UI while a separate agent process provides the model and tools. ### Can agent-shell be used with Claude Code? The README lists Claude Agent among the ACP-driven agents it supports, and the repository contains agent-shell-anthropic.el. The agent itself must be installed and running as an ACP process on your machine; agent-shell is the client, not the agent. ### Does Emacs support ACP through agent-shell? Yes, via the package acp.el, which the README says agent-shell relies on to communicate with agents over ACP. agent-shell builds the Emacs interface on top of that protocol layer. ### How does agent-shell compare with gptel? agent-shell talks to a local agent process over ACP, so the agent owns tools and multi-step work. gptel-style direct API clients talk to a model endpoint and leave orchestration in Emacs. The README does not discuss gptel, so this is a comparison of architectures rather than a documented feature difference. ### How does agent-shell compare with ECA? The README does not mention ECA, so no difference in approach can be stated from the project's own documentation. What the README does establish is that agent-shell is an ACP client and depends on acp.el for the protocol conversation. ### What is the role of an agent in programming? The README does not answer this. It only states that agent-shell interacts with LLM agents powered by ACP, and lists agents such as Claude Agent, Codex and Gemini CLI as the ones it can drive. ## Sources - [Issues](https://github.com/xenodium/agent-shell/issues) - [License: GPL-3.0](https://github.com/xenodium/agent-shell/blob/main/LICENSE) - [Project website](https://xenodium.com) - [README](https://github.com/xenodium/agent-shell/blob/main/README.md) - [xenodium/agent-shell on GitHub](https://github.com/xenodium/agent-shell) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/xenodium-agent-shell