How xenodium/agent-shell works
1. Repository purpose
- agent-shell is an Emacs Lisp package that turns Emacs into a chat/shell front end for LLM coding agents.
- It is not the agent runtime itself; it is a client layer that talks to external agent CLIs through ACP (Agent Client Protocol).
2. Core orchestration layer
- The main entry point is agent-shell.el.
- This is the central integration point that likely wires together shell creation, session reuse, prompt submission, interrupts, logging, and buffer management.
- The architecture is centered on Emacs buffers as the unit of interaction: one shell buffer per agent session, plus supporting viewport, diff, and log buffers.
3. Shell/runtime foundation
- The package is built on comint via the shell-maker dependency.
- That means agent processes are spawned as interactive subprocesses, and agent-shell acts as a higher-level shell UI on top of standard Emacs process/buffer primitives.
- The external agent executable is the real runtime boundary; agent-shell only configures and talks to it.
4. ACP protocol boundary
- The package depends on acp.el to speak Agent Client Protocol.
- Protocol traffic is a first-class concept here: the repo includes traffic fixtures and commands to inspect ACP logs.
- This creates a clear boundary between Emacs UI state and protocol messages exchanged with the agent CLI.
5. Provider-specific adapters
- Each supported agent has its own integration file, for example:
- agent-shell-anthropic.el
- agent-shell-openai.el
- agent-shell-google.el
- agent-shell-goose.el
- agent-shell-qwen.el
- agent-shell-auggie.el
- agent-shell-mistral.el
- plus others like cursor, kiro, droid, pi, github, opencode, mock-agent.
- These files are the adapter layer that maps a specific CLI’s command, auth, and environment into a common agent-shell configuration shape.
6. Configuration model
- A major architectural idea is “agent configs”: reusable definitions for command, environment, auth, model/session defaults, and capabilities.
- agent-shell-agent-configs and agent-shell-preferred-agent-config are the main switching points.
- This makes the package multi-provider by design: the UI is generic, while agent identity and launch parameters are pluggable.
7. Authentication and environment setup
- Auth is handled per provider, with explicit support for login, API key, OAuth token, and Vertex AI styles depending on the backend.
- Environment assembly is also first-class via agent-shell-make-environment-variables, including inheritance and .env loading.
- In architecture terms, credentials and process environment are injected at spawn time, not stored in the Emacs UI layer.
8. Session and interaction flow
- User input enters an agent-shell buffer, is queued/submitted, and then routed to the active agent session.
- The package supports session reuse, new sessions, session mode/model switching, and pending request handling.
- The interaction model is conversational but stateful: transcript history, permissions, tool use, and thought/process sections are all represented in the buffer.
9. UI surfaces
- agent-shell-ui.el and agent-shell-viewport.el suggest two primary presentation modes:
- a live shell/chat buffer
- a viewport/read-only inspection buffer for viewing or composing interactions
- agent-shell-completion.el handles command/file completion, while agent-shell-styles.el, agent-shell-active-message.el, and agent-shell-heartbeat.el likely provide visual affordances such as status indicators and message formatting.
- agent-shell-diff.el is a separate review surface for file changes before accepting edits.
10. Project/file integration
- The package can send files, regions, shell output, clipboard images, and screenshots into the agent session.
- agent-shell-project.el and agent-shell-worktree.el imply project-scoped behavior and possibly VCS/worktree awareness for locating the right session and storing artifacts.
- agent-shell-usage.el and related indicators reflect token/context usage as part of the UI.
11. Container/devcontainer boundary
- agent-shell-devcontainer.el supports running agents inside Docker/devcontainers by prefixing the launch command.
- This is a notable boundary because the process may run in one filesystem namespace while Emacs still mediates file access locally.
- The README explicitly calls out path resolution and the option to disable local text-file capabilities, so filesystem translation is part of the architecture.
12. Persistence and per-project storage
- Per-project artifacts are stored under .agent-shell/ by default, including transcripts and screenshots.
- This means the repo separates ephemeral Emacs buffers from durable project-scoped state.
- The storage path is customizable, so persistence is abstracted behind a path resolver rather than hardcoded to the repository tree.
13. Command and capability surface
- The command list shows the package exposes a broad operator API: start, submit, interrupt, navigate history, toggle UI, view traffic, open transcript, insert files, send screenshots, and manage diffs.
- agent-shell-viewport-* commands indicate the viewport can be used to inspect and reply to specific interactions independently of the main shell.
- agent-shell-fakes-load-session shows there is also a replay/debug path for protocol traffic.
14. Testing and replay
- Tests live under tests/, with dedicated provider tests and fixture traffic files.
- The .traffic fixtures indicate protocol-level regression coverage, not just UI unit tests.
- agent-shell-fakes.el suggests a test harness that replays captured ACP sessions, which is important for validating protocol behavior without invoking live agents.
15. Architectural summary for diagramming
- A good diagram would show:
- Emacs commands and buffers at the top
- a generic agent-shell orchestration/core in the middle
- provider adapters and ACP protocol handling beneath that
- external agent CLIs as separate processes
- optional supporting paths for MCP servers, devcontainers, screenshots/files, transcripts, and logging/traffic inspection
- The key boundary is between the Emacs-facing UI/state layer and the external agent process speaking ACP.
Main entry points: agent-shell.el agent-shell · agent-shell-ui.el Shell UI · agent-shell-tests.el Protocol tests · agent-shell-project.el Project scope
Components 18
UI surfaces
Buffers and interactive presentation layers inside Emacs
- Shell UI · Primary conversational shell buffer and user interaction surface
agent-shell-ui.el - Viewport · Secondary inspection and reply surface for focused interactions
agent-shell-viewport.el - Diff view · Change review surface for proposed file edits
agent-shell-diff.el - Completion · Command and file completion helpers
agent-shell-completion.el - Styles · Formatting and visual treatment for messages and sections
agent-shell-styles.el - Status · Active message and heartbeat indicators
agent-shell-active-message.el - Usage · Token and context usage indicators
agent-shell-usage.el
Core orchestration
Session lifecycle, command routing, and shared state
- agent-shell · Main entry point wiring sessions, buffers, submission, and interrupts
agent-shell.el - Project scope · Project-aware session and artifact coordination
agent-shell-project.el - Worktree · Worktree-aware file and session placement
agent-shell-worktree.el - Agent configs · Reusable agent definitions for command, auth, env, and defaults
Provider adapters
Per-CLI configuration and auth/environment mapping
- Adapters · Provider-specific command and authentication glue for supported CLIs
External runtime
ACP-speaking agent processes and optional containerized launch
- Devcontainer · Container-prefixed command launch and path boundary handling
agent-shell-devcontainer.el - ACP · Agent Client Protocol boundary between Emacs and external agents
- Agent CLIs · Underlying coding agents launched as subprocesses
Persistence
Project-scoped artifacts and logs
- Artifacts · Per-project transcripts, screenshots, and other durable session artifacts
Tests
Protocol replay and provider coverage
- Replay harness · Captured traffic replay and fake session support
tests/agent-shell-fakes.el - Protocol tests · Provider and traffic-fixture regression coverage
tests/agent-shell-tests.el
Connections 19
- Shell UI → agent-shell: submit input · User commands and message submission flow into orchestration
- Viewport → agent-shell: inspect/reply · Viewport interactions route back through the core session manager
- Diff view → agent-shell: accept edits · Review actions feed edit decisions into the session flow
- Completion → agent-shell: assist input · Completion helps author commands and file references
- Styles → Shell UI: format · Shared presentation rules shape shell rendering
- Status → Shell UI: status cues · Heartbeat and active-message affordances decorate the shell
- Usage → Shell UI: meter · Usage metrics are surfaced in the interactive UI
- agent-shell → Agent configs: select config · Core chooses the active agent configuration
- Agent configs → Adapters: bind provider · Configs are realized through provider-specific adapters
- Adapters → ACP: speak ACP · Adapters prepare the agent-side protocol connection
- ACP → Agent CLIs: spawn/talk · ACP traffic is exchanged with the external agent process
- Devcontainer → Agent CLIs: wrap launch · Containerized execution prefixes the agent command
- agent-shell → Project scope: scope session · Project context determines session placement and behavior
- Project scope → Worktree: track repo · Project state can be worktree-aware
- agent-shell → Artifacts: persist artifacts · Transcripts and screenshots are written as durable project artifacts
- Replay harness → ACP: replay · Captured ACP traffic is replayed in tests and debugging
- Protocol tests → Replay harness: use fixtures · Tests validate behavior through fake sessions and traffic logs
- Protocol tests → Adapters: provider coverage · Provider integrations are exercised by dedicated tests
- agent-shell → ACP: route messages · Core orchestration bridges Emacs state to protocol messages