xenodium/agent-shell

Emacs Agent Shell

What it is – agent‑shell is an Emacs package that gives you a native REPL‑like buffer for talking to large‑language‑model (LLM) agents. It talks to the agents through the Agent Client Protocol (ACP), a standardised JSON‑over‑stdio interface used by many commercial coding assistants (Claude, Codex, Gemini, Goose, Grok Build, Cursor, Kimi Code, etc.).

How it works – The package builds on Emacs’ built‑in comint-shell (via the helper library shell-maker). When you start an agent‑shell buffer it spawns the appropriate external CLI (e.g. claude-agent-acp, codex-acp, gemini-cli, …) with the --acp flag. The CLI runs in ACP mode, reads JSON requests from stdin and writes JSON responses to stdout. agent-shell formats your prompts, sends them, and displays the assistant’s replies directly in the buffer, supporting multi‑line input, image paste, screenshot capture, and environment‑variable configuration.

Key features

• Multi‑agent support – any ACP‑compatible agent can be used; the README lists dozens (Anthropic Claude, OpenAI Codex, Google Gemini, Goose, Grok Build, Cursor, Kimi, CodeBuddy, Kiro, Qwen Code, Auggie, Mistral Vibe, Factory Droid, Pi, Oh‑My‑Pi, Opencode, etc.).
• Rich Emacs integration – works with vanilla Emacs, Doom Emacs, and can be extended by a growing ecosystem of add‑ons (sidebar, workspace, notifications, Org‑mode transcript, Docker sandbox, etc.).
• Authentication helpers – convenience functions for API‑key, OAuth token, or login‑based auth for each provider, plus utilities to load env‑vars from .env files or inherit the Emacs environment.
• Image & screenshot handling – clipboard image paste and screen capture are supported on macOS, Linux (Wayland/X11) and Windows via external tools.
• Package distribution – available on MELPA (agent-shell, acp.el, shell-maker) and installable with use-package or Doom’s package! macro.

Typical workflow

1. Install the external CLI for the desired agent (e.g. npm install -g @agentclientprotocol/claude-agent-acp).
2. Add agent-shell to your Emacs config and optionally configure authentication variables.
3. Run M-x agent-shell (or the provider‑specific command) to open a buffer.
4. Type a prompt, hit RET, and read the LLM’s response right inside Emacs. You can also paste images or screenshots which are sent to the agent if the backend supports them.

Why it matters – It brings the power of modern LLM coding assistants into the classic Emacs workflow, letting developers stay inside their editor while leveraging AI for code generation, review, debugging, or any other agent‑driven task.

---

The project is a genuine software tool for AI‑augmented development, not a mere curated list or tutorial.