The Problem

Developers who spend most of their day inside Emacs still need a convenient way to query LLM agents (Claude, Gemini, Cursor, etc.) without leaving the editor. Switching to a browser or separate terminal incurs context‑switch cost and makes it harder to incorporate AI‑generated suggestions into the current buffer.

What This Does

agent-shell implements a native Emacs buffer that speaks the Agent Client Protocol (ACP) to any compliant LLM back‑end. The core entry point is the interactive command defined in agent-shell.el, which creates a *agent-shell* buffer and loads supporting modules:

  • agent-shell-ui.el – UI widgets, prompt handling, and buffer management.
  • agent-shell-completion.el – integrates Emacs completion frameworks with the agent’s suggestions.
  • agent-shell-*.el (e.g., agent-shell-openai.el, agent-shell-anthropic.el) – thin wrappers that translate generic ACP calls into the command‑line invocations required for each provider.

The repository also ships a set of test suites under tests/ that exercise the runner (agent-shell-runner-tests.el) and the provider‑specific adapters.

How It Is Wired

Entry point – M-x agent-shell (function agent-shell in agent-shell.el).

  1. agent-shell creates the buffer and calls agent-shell--start-session.
  2. agent-shell--start-session selects a provider module (e.g., agent-shell-openai.el) based on user configuration stored in Emacs variables (see agent-shell-project.el).
  3. The provider module builds an ACP request and spawns the external binary (Claude‑code, Gemini‑cli, etc.) via call-process/start-process. The binary’s stdout/stderr are captured by agent-shell-runner.el (not listed but implied by the tests).
  4. Responses flow back to agent-shell--handle-response in agent-shell.el, which updates the buffer, triggers completion (agent-shell-completion.el), and optionally refreshes the UI (agent-shell-ui.el).
  5. UI hooks (agent-shell-heartbeat.el, agent-shell-viewport.el) keep the buffer responsive and scroll to the latest output.

Effect surface – The only external side‑effects are process invocations of the provider binaries and writes to the current Emacs buffer. No file system writes or network calls are performed directly by the Lisp code; network traffic is handled by the external ACP clients.

Coupling – agent-shell.el is the hub; each provider file (agent-shell-*.el) is a leaf that only supplies the command string and basic argument handling. Changing a provider only requires editing its dedicated file; the rest of the system remains untouched. No circular dependencies are present in the current graph.

How To Use It

# Clone the repo
git clone https://github.com/moses-y/agent-shell
cd agent-shell

# Add to Emacs load‑path (e.g., in init.el)
(add-to-list 'load-path "/path/to/agent-shell")
(require 'agent-shell)   ; registers the command

# Install external ACP binaries as documented in README.org
# Example for Claude Code:
npm install -g @zed-industries/claude-code-acp
# Verify: which claude-code-acp

# Start a session inside Emacs
M-x agent-shell

Configuration variables (e.g., agent-shell-default-provider) are defined in agent-shell-project.el. Adjust them in your init file to point at the desired binary.

Real‑World Use

A Python developer working on a Django view can open *agent-shell*, type a prompt like “Generate a DRF serializer for this model”, and paste the returned code directly into the current buffer. The workflow stays entirely within Emacs, preserving undo history and syntax highlighting.

Code Health & Issues

  • Medium – No CI pipeline – .github/ contains issue and PR templates but no workflow files; tests must be run manually.
  • Low – No Dockerfile – No containerised build environment is provided.
  • Low – No lockfile – No package manager lockfile (e.g., package-lock.json) is present, making reproducible external binary installs reliant on user discretion.
  • Positive – Tests exist – 9 test files under tests/ validate core runner logic and traffic fixtures.
  • Positive – License – LICENSE is present, allowing reuse.

No secrets were detected in the repository.

The Bottom Line

agent-shell delivers a functional Emacs‑native interface to any ACP‑compatible LLM, with a clean separation between core UI logic and provider adapters. The codebase is small, well‑tested, but lacks automated CI and container support, so integration teams should add a CI workflow before committing changes. Ideal for Emacs‑centric developers who need quick AI assistance without leaving their editor.