Emacs Agent Shell

This project needs your funding

As you pay for those useful LLM tokens, consider sponsoring development and maintenance of this project.

agent-shell is in its infancy. It’s got rough edges and lots of features to implement still. With your help, I can make this effort more sustainable.

Thank you!

Alvaro

agent-shell

A native Emacs shell to interact with LLM agents powered by ACP (Agent Client Protocol).

With agent-shell, you can chat with the likes of Gemin CLI, Claude Code, or any other ACP-driven agent.

Note: This package is in the very early stages and is likely incomplete or may have some rough edges.

Setup

External dependencies

ACP adapter for Claude Code

For Anthropic’s Claude Code, install Zed’s claude-code-acp.

Gemini CLI

For Google’s Gemini CLI, be sure to get a recent release supporting the --experimental-acp flag.

Codex

For OpenAI’s Codex, install codex-acp and ensure the `codex-acp` executable is in PATH.

Installation

agent-shell is powered by built-in comint-shell, via shell-maker, available on MELPA.

You can shell-maker install via:

(use-package shell-maker
  :ensure t)

agent-shell also depends on acp.el, which isn’t yet on MELPA. You can install with:

(use-package acp
  :vc (:url "https://github.com/xenodium/acp.el"))

If you run into an error like use-package: Keyword :vc received unknown argument, ensure you’re using the built-in :vc syntax shown above. Earlier guides relied on the external vc-use-package extension, which accepted :fetcher=/:repo keywords, but Emacs 30+ expects ELPA-style specs such as :url.

Finally, install agent-shell with:

(use-package agent-shell
  :vc (:url "https://github.com/xenodium/agent-shell"))

Configuration

Set your API keys for the agent providers you want to use:

;; Anthropic Claude API key
(setq agent-shell-anthropic-key "your-anthropic-api-key-here")

;; Google Gemini API key
(setq agent-shell-google-key "your-google-api-key-here")

;; OpenAI Codex API key
(setq agent-shell-openai-key "your-openai-api-key-here")

You can also set these as functions that load and return the keys:

(setq agent-shell-anthropic-key
      (lambda () (auth-source-pass-get "secret" "anthropic-api-key")))

(setq agent-shell-google-key
      (lambda () (auth-source-pass-get "secret" "google-api-key")))

(setq agent-shell-openai-key
      (lambda () (auth-source-pass-get "secret" "openai-api-key")))

Usage

Start an agent shell session:

M-x agent-shell-start-claude-code-agent - Start a Claude Code agent session
M-x agent-shell-start-codex-agent - Start a Codex agent session
M-x agent-shell-start-gemini-agent - Start a Gemini agent session

Keybindings

C-c C-c - Interrupt current agent operation
TAB and Shift-TAB - To navigate items

kairin/agent-shell