Emacs Agent Shell

👉 Support this work via GitHub Sponsors by @xenodium (check out my blog)

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 Gemini 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.

Related projects

• acp.el: An ACP (Agent Client Protocol) implementation in Emacs lisp.
• agent-shell-manager: Tabulated view and management of agent-shell buffers.
• agent-shell-sidebar: A sidebar add-on for agent-shell.

Setup

External dependencies

Claude Code

For Anthropic’s Claude Code, follow Zed’s claude-code-acp instructions, typically something like:

npm install -g @zed-industries/claude-code-acp

Note: The -g flag is required to install the binary globally so it’s available in your PATH. After installation, verify it’s available by running which claude-code-acp in your terminal.

Codex

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

Gemini CLI

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

Goose

For Goose CLI, install goose and ensure the `goose` executable is in PATH.

Qwen Code

For Qwen Code, install with:

npm install -g @qwen-code/qwen-code@latest

See https://github.com/QwenLM/qwen-code for details.

Installation

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

You can install shell-maker 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"))

Doom Emacs

If you are using Doom Emacs and would like to use the package! macro:

(package! shell-maker)
(package! acp :recipe (:host github :repo "xenodium/acp.el"))
(package! agent-shell :recipe (:host github :repo "xenodium/agent-shell"))

Run doom sync and restart.

Include require before configuration:

(require 'acp)
(require 'agent-shell)
;; rest of config...

Configuration

Configure authentication for the agent providers you want to use.

Environment variables

Pass environment variables to the spawned agent process by customizing the `agent-shell-*-environment` variable with `agent-shell-make-environment-variables`. The helper accepts key/value pairs and exports them when the agent starts.

(setq agent-shell-anthropic-claude-environment
      (agent-shell-make-environment-variables
       "ANTHROPIC_API_KEY" (auth-source-pass-get "secret" "anthropic-api-key")
       "HTTPS_PROXY" "http://proxy.example.com:8080"))

Inheriting environment variables

By default, the agent process starts with a minimal environment. To inherit environment variables from the parent Emacs process, use the `:inherit-env t` parameter in `agent-shell-make-environment-variables`:

(setenv "ANTHROPIC_API_KEY" (auth-source-pass-get "secret" "anthropic-api-key"))

(setq agent-shell-anthropic-claude-environment
      (agent-shell-make-environment-variables :inherit-env t))

This ensures that environment variables like `PATH`, `HOME`, and others from your Emacs session are available to the agent process, while still allowing you to override or add specific variables.

Loading environment variables from files

You can load environment variables from .env files using the `:load-env` parameter. This supports both single and multiple files:

;; Load from a single .env file
(setq agent-shell-anthropic-claude-environment
      (agent-shell-make-environment-variables
       :load-env "~/.env"
       "CUSTOM_VAR" "custom_value"))

;; Load from multiple .env files
(setq agent-shell-anthropic-claude-environment
      (agent-shell-make-environment-variables
       :load-env '("~/.env" ".env.local")
       :inherit-env t))

The .env files should contain variables in the format `KEY=value`, with one variable per line. Comments (lines starting with `#`) and empty lines are ignored.

Anthropic Claude

For login-based authentication (default):

(setq agent-shell-anthropic-authentication
      (agent-shell-anthropic-make-authentication :login t))

For API key authentication:

;; With string
(setq agent-shell-anthropic-authentication
      (agent-shell-anthropic-make-authentication :api-key "your-anthropic-api-key-here"))

;; With function
(setq agent-shell-anthropic-authentication
      (agent-shell-anthropic-make-authentication
       :api-key (lambda () (auth-source-pass-get "secret" "anthropic-api-key"))))

For alternative Anthropic-compatible API endpoints, configure via environment variables:

(setq agent-shell-anthropic-claude-environment
      (agent-shell-make-environment-variables
       "ANTHROPIC_BASE_URL" "https://api.moonshot.cn/anthropic"
       "ANTHROPIC_MODEL" "kimi-k2-turbo-preview"
       "ANTHROPIC_SMALL_FAST_MODEL" "kimi-k2-turbo-preview"))

Google Gemini

For login-based authentication (default):

(setq agent-shell-google-authentication
      (agent-shell-google-make-authentication :login t))

For API key authentication:

;; With string
(setq agent-shell-google-authentication
      (agent-shell-google-make-authentication :api-key "your-google-api-key-here"))

;; With function
(setq agent-shell-google-authentication
      (agent-shell-google-make-authentication
       :api-key (lambda () (auth-source-pass-get "secret" "google-api-key"))))

For Vertex AI authentication:

(setq agent-shell-google-authentication
      (agent-shell-google-make-authentication :vertex-ai t))

OpenAI Codex

For login-based authentication (default):

(setq agent-shell-openai-authentication
      (agent-shell-openai-make-authentication :login t))

For API key authentication:

;; With string
(setq agent-shell-openai-authentication
      (agent-shell-openai-make-authentication :api-key "your-openai-api-key-here"))

;; With function
(setq agent-shell-openai-authentication
      (agent-shell-openai-make-authentication
       :api-key (lambda () (auth-source-pass-get "secret" "openai-api-key"))))

Goose

For OpenAI API key authentication:

;; With string
(setq agent-shell-goose-authentication
      (agent-shell-make-goose-authentication :openai-api-key "your-openai-api-key-here"))

;; With function
(setq agent-shell-goose-authentication
      (agent-shell-make-goose-authentication
       :openai-api-key (lambda () (auth-source-pass-get "secret" "openai-api-key"))))

Qwen Code

For OAuth login-based authentication:

(setq agent-shell-qwen-authentication
      (agent-shell-qwen-make-authentication :login t))

Customizing Available Agents

By default, agent-shell includes configurations for all supported agents (Claude Code, Gemini CLI, Codex, Goose, and Qwen Code). You can customize which agents are available through the agent-shell-agent-configs variable.

Usage

Quick Start

M-x agent-shell - Start or reuse any of the known agents.

You can select and start any of the known agent shells (see agent-shell-agent-configs) via the agent-shell interactive command and enables reusing existing shells when available. With a prefix argument (C-u M-x agent-shell), it forces starting a new shell session, thus instantiating multiple agent shells.

Specific Agent Commands

Start a specific agent shell session directly:

• M-x agent-shell-anthropic-start-claude-code - Start a Claude Code agent session
• M-x agent-shell-openai-start-codex - Start a Codex agent session
• M-x agent-shell-google-start-gemini - Start a Gemini agent session
• M-x agent-shell-goose-start-agent - Start a Goose agent session
• M-x agent-shell-qwen-start - Start a Qwen Code agent session

Running agents in Devcontainers / Docker containers (Experimental)

agent-shell provides rudimentary support for running agents and shell commands in containers.

Use agent-shell-container-command-runner to prefix the command that starts the agent, or a shell command that should be run so it is executed inside the container; for example:

(setq agent-shell-container-command-runner '("devcontainer" "exec" "--workspace-folder" "."))

Note that any :environment-variables you may have passed to acp-make-client will not apply to the agent process running inside the container. It’s expected to inject environment variables by means of your devcontainer configuration / Dockerfile.

Next, set an agent-shell-path-resolver-function that resolves container paths in the local working directory, and vice versa. Agent shell provides the agent-shell--resolve-devcontainer-path function for use with devcontainers specifically: it reads the workspaceFolder specified in .devcontainer/devcontainer.json, or uses the default value of /workspaces/<repository-name> otherwise.

(setq agent-shell-path-resolver-function #'agent-shell--resolve-devcontainer-path)

Note that this allows the agent to access files on your local file-system. While care has been taken to restrict access to files in the local working directory, it’s probably possible for a malicious agent to circumvent this restriction.

Optional: to prevent the agent running inside the container to access your local file-system altogether and to have it read/modify files inside the container directly, in addition to setting the resolver function, disable the “read/write text file” client capabilities:

(setq agent-shell-text-file-capabilities nil)

All of the above settings can be applied on a per-project basis using directory-local variables.

Keybindings

• C-c C-c - Interrupt current agent operation
• TAB and Shift-TAB - Navigate interactive elements

Contributing

Before Contributing

Before implementing new features, please file a feature request first to discuss the proposal. This helps ensure alignment with the project’s direction and prevents unnecessary work.

As the maintainer, I must be mindful of all features I accept since I inherit the code to maintain it. Some features may be better suited as separate packages (like agent-shell-sidebar).

I’ll gladly promote your package wherever possible.

Style (or personal preference TBH)

There are lots of ways to accomplish things in elisp. While the following are merely personal preferences, as maintainer, it really simplifies things for me to try to limit the number of ways to accomplish things.

Maps (use alists)

This project relies on alists for much of its functionality. Sure, we can also use plists, hashtables, etc.

Unless we have a strong argument to use something else, please stick with alists (and : keywords).

'((:species . "Cat")
  (:name . "Whiskers")
  (:age . 4)
  (:color . "Gray")
  (:favorite-toy . "Feather Wand"))

seq.el

Accessing and working with lists? Please prefer seq.el, unless we have a strong argument to use an alternative.

(setq animals
      (list
       '((:species . "Cat")
         (:name . "Whiskers")
         (:age . 4)
         (:color . "Gray"))
       '((:species . "Dog")
         (:name . "Buddy")
         (:age . 6)
         (:color . "Brown"))))

(seq-first animals)

map.el

Accessing and working with alists? Please prefer map.el unless we have a strong argument to use an alternative.

(setq animal (seq-first animals))
(map-elt animal :species)

cl-lib (limited to cl-defun)

While I’m a fan of cl-defun, please limit cl usage to cl-defun if possible. Nothing against cl-lib. I’m just limiting the surface and number of idioms I need to keep in my head to maintain the codebase. Often, seq.el and map.el can do the job just fine.

cl-defun, on the other hand, please do! I’m a fan of named parameters (yay for self-documenting), so use &key if possible.

(cl-defun describe (&key animal)
  "Describe an ANIMAL, which is an alist of properties like :species, :name, :age, :color."
  (message "This is a %d-year-old %s %s named %s."
           (map-elt animal :age 0)
           (map-elt animal :color "Unknown Color")
           (map-elt animal :species "Unknown Species")
           (map-elt animal :name "Unnamed")))

(describe :animal '((:species . "Cat")
                    (:name . "Whiskers")
                    (:age . 4)
                    (:color . "Gray")))

Code/feature consistency

Please try to look for a similar feature in the code base and replicate an existing pattern usage if possible.

Code Checks

Before submitting a PR, please run:

• M-x checkdoc - Ensures documentation consistency
• M-x byte-compile-file - Identifies compilation warnings

Tests

I’m aware, we’re a bit light on tests, but we started adding some tests. If adding a new feature, please try to add tests.

Tests live under the tests directory:

ls tests/*tests.el

Running tests

Opening any file under the tests directory will load the agent-shell-run-all-tests command.

Run tests with M-x agent-shell-run-all-tests.

Contributors

Made with contrib.rocks.