# xenodium/agent-shell architecture

> Architecture diagram of the GitHub repository xenodium/agent-shell, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/xenodium/agent-shell
- Repository: https://github.com/xenodium/agent-shell

## Overview

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`](https://github.com/xenodium/agent-shell/blob/main/agent-shell.el) (agent-shell), [`agent-shell-ui.el`](https://github.com/xenodium/agent-shell/blob/main/agent-shell-ui.el) (Shell UI), [`tests/agent-shell-tests.el`](https://github.com/xenodium/agent-shell/blob/main/tests/agent-shell-tests.el) (Protocol tests), [`agent-shell-project.el`](https://github.com/xenodium/agent-shell/blob/main/agent-shell-project.el) (Project scope)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["UI surfaces"]
  node_agent_shell_ui["Shell UI<br/>buffer-ui<br/>[agent-shell-ui.el]"]
  node_agent_shell_viewport["Viewport<br/>read-only ui"]
  node_agent_shell_diff["Diff view<br/>review ui"]
  node_agent_shell_completion["Completion<br/>input assist"]
  node_agent_shell_styles["Styles<br/>presentation"]
  node_agent_shell_status(("Status<br/>activity ui"))
  node_agent_shell_usage(("Usage<br/>context meter"))
end

subgraph group_core["Core orchestration"]
  node_agent_shell_core["agent-shell<br/>orchestrator<br/>[agent-shell.el]"]
  node_agent_shell_project["Project scope<br/>project state"]
  node_agent_shell_worktree["Worktree<br/>vcs scope"]
  node_agent_shell_configs["Agent configs<br/>config registry"]
end

subgraph group_adapters["Provider adapters"]
  node_agent_shell_adapters["Adapters"]
end

subgraph group_runtime["External runtime"]
  node_agent_shell_devcontainer["Devcontainer<br/>launch wrapper"]
  node_acp_protocol{{"ACP<br/>protocol layer"}}
  node_external_agents[("Agent CLIs<br/>external process")]
end

subgraph group_storage["Persistence"]
  node_agent_shell_storage[("Artifacts<br/>project storage")]
end

subgraph group_tests["Tests"]
  node_agent_shell_fakes["Replay harness<br/>test support"]
  node_agent_shell_tests["Protocol tests<br/>test suite"]
end

node_agent_shell_ui -->|"submit input"| node_agent_shell_core
node_agent_shell_viewport -->|"inspect/reply"| node_agent_shell_core
node_agent_shell_diff -->|"accept edits"| node_agent_shell_core
node_agent_shell_completion -->|"assist input"| node_agent_shell_core
node_agent_shell_styles -->|"format"| node_agent_shell_ui
node_agent_shell_status -->|"status cues"| node_agent_shell_ui
node_agent_shell_usage -->|"meter"| node_agent_shell_ui
node_agent_shell_core -->|"select config"| node_agent_shell_configs
node_agent_shell_configs -->|"bind provider"| node_agent_shell_adapters
node_agent_shell_adapters -->|"speak ACP"| node_acp_protocol
node_acp_protocol -->|"spawn/talk"| node_external_agents
node_agent_shell_devcontainer -->|"wrap launch"| node_external_agents
node_agent_shell_core -->|"scope session"| node_agent_shell_project
node_agent_shell_project -->|"track repo"| node_agent_shell_worktree
node_agent_shell_core -->|"persist artifacts"| node_agent_shell_storage
node_agent_shell_fakes -->|"replay"| node_acp_protocol
node_agent_shell_tests -->|"use fixtures"| node_agent_shell_fakes
node_agent_shell_tests -->|"provider coverage"| node_agent_shell_adapters
node_agent_shell_core -->|"route messages"| node_acp_protocol

click node_agent_shell_core "https://github.com/xenodium/agent-shell/blob/main/agent-shell.el"
click node_agent_shell_ui "https://github.com/xenodium/agent-shell/blob/main/agent-shell-ui.el"
click node_agent_shell_viewport "https://github.com/xenodium/agent-shell/blob/main/agent-shell-viewport.el"
click node_agent_shell_diff "https://github.com/xenodium/agent-shell/blob/main/agent-shell-diff.el"
click node_agent_shell_completion "https://github.com/xenodium/agent-shell/blob/main/agent-shell-completion.el"
click node_agent_shell_styles "https://github.com/xenodium/agent-shell/blob/main/agent-shell-styles.el"
click node_agent_shell_status "https://github.com/xenodium/agent-shell/blob/main/agent-shell-active-message.el"
click node_agent_shell_usage "https://github.com/xenodium/agent-shell/blob/main/agent-shell-usage.el"
click node_agent_shell_project "https://github.com/xenodium/agent-shell/blob/main/agent-shell-project.el"
click node_agent_shell_worktree "https://github.com/xenodium/agent-shell/blob/main/agent-shell-worktree.el"
click node_agent_shell_devcontainer "https://github.com/xenodium/agent-shell/blob/main/agent-shell-devcontainer.el"
click node_agent_shell_fakes "https://github.com/xenodium/agent-shell/blob/main/tests/agent-shell-fakes.el"
click node_agent_shell_tests "https://github.com/xenodium/agent-shell/blob/main/tests/agent-shell-tests.el"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_agent_shell_ui,node_agent_shell_viewport,node_agent_shell_diff,node_agent_shell_completion,node_agent_shell_styles,node_agent_shell_status,node_agent_shell_usage toneBlue
class node_agent_shell_core,node_agent_shell_project,node_agent_shell_worktree,node_agent_shell_configs toneAmber
class node_agent_shell_adapters toneMint
class node_agent_shell_devcontainer,node_acp_protocol,node_external_agents toneRose
class node_agent_shell_storage toneIndigo
class node_agent_shell_fakes,node_agent_shell_tests toneTeal
```

## Components

### UI surfaces

Buffers and interactive presentation layers inside Emacs

- [Shell UI](https://github.com/xenodium/agent-shell/blob/main/agent-shell-ui.el): buffer-ui · Primary conversational shell buffer and user interaction surface · `agent-shell-ui.el`
- [Viewport](https://github.com/xenodium/agent-shell/blob/main/agent-shell-viewport.el): read-only ui · Secondary inspection and reply surface for focused interactions · `agent-shell-viewport.el`
- [Diff view](https://github.com/xenodium/agent-shell/blob/main/agent-shell-diff.el): review ui · Change review surface for proposed file edits · `agent-shell-diff.el`
- [Completion](https://github.com/xenodium/agent-shell/blob/main/agent-shell-completion.el): input assist · Command and file completion helpers · `agent-shell-completion.el`
- [Styles](https://github.com/xenodium/agent-shell/blob/main/agent-shell-styles.el): presentation · Formatting and visual treatment for messages and sections · `agent-shell-styles.el`
- [Status](https://github.com/xenodium/agent-shell/blob/main/agent-shell-active-message.el): activity ui · Active message and heartbeat indicators · `agent-shell-active-message.el`
- [Usage](https://github.com/xenodium/agent-shell/blob/main/agent-shell-usage.el): context meter · Token and context usage indicators · `agent-shell-usage.el`

### Core orchestration

Session lifecycle, command routing, and shared state

- [agent-shell](https://github.com/xenodium/agent-shell/blob/main/agent-shell.el): orchestrator · Main entry point wiring sessions, buffers, submission, and interrupts · `agent-shell.el`
- [Project scope](https://github.com/xenodium/agent-shell/blob/main/agent-shell-project.el): project state · Project-aware session and artifact coordination · `agent-shell-project.el`
- [Worktree](https://github.com/xenodium/agent-shell/blob/main/agent-shell-worktree.el): vcs scope · Worktree-aware file and session placement · `agent-shell-worktree.el`
- **Agent configs**: config registry · Reusable agent definitions for command, auth, env, and defaults

### Provider adapters

Per-CLI configuration and auth/environment mapping

- **Adapters**: provider adapters · Provider-specific command and authentication glue for supported CLIs

### External runtime

ACP-speaking agent processes and optional containerized launch

- [Devcontainer](https://github.com/xenodium/agent-shell/blob/main/agent-shell-devcontainer.el): launch wrapper · Container-prefixed command launch and path boundary handling · `agent-shell-devcontainer.el`
- **ACP**: protocol layer · Agent Client Protocol boundary between Emacs and external agents
- **Agent CLIs**: external process · Underlying coding agents launched as subprocesses

### Persistence

Project-scoped artifacts and logs

- **Artifacts**: project storage · Per-project transcripts, screenshots, and other durable session artifacts

### Tests

Protocol replay and provider coverage

- [Replay harness](https://github.com/xenodium/agent-shell/blob/main/tests/agent-shell-fakes.el): test support · Captured traffic replay and fake session support · `tests/agent-shell-fakes.el`
- [Protocol tests](https://github.com/xenodium/agent-shell/blob/main/tests/agent-shell-tests.el): test suite · Provider and traffic-fixture regression coverage · `tests/agent-shell-tests.el`

## Connections

- 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
