Native Emacs transcript UI for AI agents over the Agent Client Protocol (ACP). UI design inspired by codex-ide.
agent-ide brings any ACP-compatible coding agent directly into Emacs. It renders agent messages, tool calls, diffs, and permission prompts in a rich, read-only transcript buffer — with a fully editable prompt at the bottom. Think of it as Emacs's answer to agent chat panels, but natively integrated: keyboard-driven, theme-aware, and hackable in Emacs Lisp.
- Emacs ≥ 29.1
- acp.el ≥ 0.11.1 — ACP client library
(straight-use-package
'(agent-ide :type git :host github :repo "guidao/agent-ide"))
;; Optional: load it immediately
(require 'agent-ide)Clone this repository somewhere on your load-path:
git clone https://github.com/YOUR_USER/agent-ide.git ~/.emacs.d/agent-ideThen in your init file:
(add-to-list 'load-path "~/.emacs.d/agent-ide")
(require 'agent-ide)For deferred loading with use-package, register the resume commands too:
(use-package agent-ide
:load-path "~/.emacs.d/agent-ide"
:commands (agent-ide agent-ide-inline
agent-ide-resume agent-ide-resume-history))You can then run M-x agent-ide-resume directly from a project file or Dired
after starting Emacs. Choose the saved conversation; no preliminary new session
is needed. Selecting the same connected conversation again reuses its buffer.
-
Make sure you have an ACP-compatible agent binary on your
PATH(e.g.cursor-agent,claude, or any agent exposing an ACP subcommand). -
Configure the agent command:
(setq agent-ide-command '("cursor-agent" "acp"))
-
Open a project and run
M-x agent-ide.
A transcript buffer opens, the agent connects, and you see a prompt: > Tell Agent what to do…
Type your prompt and press C-c C-m (or Return with a configured binding) to submit.
| Command | Keybinding | Description |
|---|---|---|
agent-ide |
— | Open a session for the current project (reuses existing) |
agent-ide-new-session |
C-u M-x agent-ide |
Start a fresh session, optionally in a different directory |
agent-ide-submit |
C-c RET |
Submit the current prompt |
agent-ide-interrupt |
C-c C-c / C-c C-k |
Stop the agent mid-response |
agent-ide-restart |
C-c C-r |
Kill and restart the current session |
agent-ide-resume |
C-c C-z |
Reconnect a disconnected session, otherwise choose project history; prefix shows all projects |
agent-ide-resume-history |
— | Choose backend sessions via session/list; prefix includes all projects |
agent-ide-set-model |
C-c C-s |
Switch model; prefer standard config options, with legacy fallback |
agent-ide-set-config |
C-c C-t |
Choose a backend setting and value (model, reasoning, mode, toggles) |
agent-ide-answer-question |
C-c C-e |
Open a pending structured question for review and submission |
agent-ide-attach-image |
C-c C-f |
Attach a PNG, JPEG, GIF or WebP file to the next prompt |
agent-ide-paste-image |
C-c C-v |
Attach an image from the clipboard |
agent-ide-remove-attachment |
— | Remove an image from the current draft |
agent-ide-reconnect |
— | Reconnect an idle session, preserving its ID, transcript and draft |
agent-ide-yank-region |
C-c C-y |
Insert the active region as file+line context |
agent-ide-sidebar |
C-c C-b |
Focus the session sidebar |
agent-ide-switch-buffer |
C-c C-j |
Choose an open agent buffer with minibuffer completion |
agent-ide-approve-permission |
C-c C-a |
Allow the newest pending request once; use C-u to always allow |
agent-ide-decline-permission |
C-c C-d |
Decline the newest pending request |
agent-ide-select-permission-option |
C-c C-p |
Choose any offered permission response or cancel |
Use C-c C-j in any session buffer, including its editable prompt, to choose
an open agent buffer across projects. It uses ordinary buffer completion, like
C-x b, restricted to agent sessions, and defaults to the most recently visited
other session. Drafts are preserved and closed buffers are excluded. The command
is also available as M-x agent-ide-switch-buffer from other buffers.
Run M-x agent-ide-resume to choose a saved conversation for the current
project. Use C-u M-x agent-ide-resume to search all projects. Candidates
show the first prompt's title, backend, directory, last activity and session ID.
Selecting an already connected conversation opens its existing buffer.
When an agent process exits, its transcript stays open with a disconnected
status. Press C-c C-z to reconnect in that buffer. Existing messages and
the editable draft are preserved. During restoration you can edit the draft;
submission is enabled once the session is ready. C-c C-r still starts a
fresh conversation.
Agent IDE selects the supported ACP method automatically:
| Situation | Method |
|---|---|
| Existing transcript and backend supports resume | session/resume |
| History is needed, or backend only supports load | session/load |
| Backend only supports resume | session/resume, with a notice if earlier messages are unavailable |
A successful load replaces the displayed history, preserving the draft and
rebuilding prompt history for M-p / M-n. Historical messages do not trigger
inline response overlays. Failed loads keep the previous transcript and offer
retry, choose-session and new-session buttons. Restoration never automatically
resends an interrupted prompt or creates a replacement conversation.
History is fetched directly from the selected backend using session/list,
including all pages. No local sessions.json index is read or written; any old
index file is unused and can be deleted. Sessions created in other clients are
available when the backend includes them in its list.
In an Agent IDE buffer (or from a sidebar entry), history uses that session's
original command and environment. In a project buffer, it uses the configured
agent-ide-command and agent-ide-environment. A prefix lists all projects for
that backend. Discovery uses a temporary connection without creating a new
conversation; C-g cancels it. Each request times out after
agent-ide-history-request-timeout seconds (default 30).
The backend must advertise sessionCapabilities.list for discovery, and
loadSession or sessionCapabilities.resume for restoration. Unsupported
listing reports an error; reconnecting an open buffer by its session ID still
works. The backend remains responsible for retaining conversations.
Missing session IDs, removed directories and unsupported capabilities are
reported without falling back to a new conversation.
C-c C-t displays the settings reported by the backend, including grouped
choices and boolean switches. The full configuration is refreshed after a
change or config_option_update; unsupported option types are ignored.
C-c C-s remains the model shortcut. Session titles from session_info_update
appear in the sidebar; buffer names remain stable.
Structured questions appear in the transcript with an Answer question
button. C-c C-e opens an editable form with Submit, Decline and
Cancel controls. Required fields, typed values, enum choices and basic
length/range constraints are checked before submission. Optional fields have
an Include checkbox. Closing the form or pressing C-c C-k cancels it.
Only form-mode elicitation is advertised; URL-mode authentication is not
implemented. Cancelling a turn also cancels pending approvals and questions.
Images stay attached to the draft until submission; the prompt displays their
names with a clickable × to remove them. Backspace at the start of the
prompt removes the last image; C-u C-c C-v removes the sole image or opens
an attachment picker. Submit text and images together, or an image alone. Failed submissions
restore their attachments without removing newer ones. Images are kept in
memory, with a default limit of 20 MiB each, configurable via
agent-ide-attachment-max-bytes. Clipboard paste uses Emacs clipboard support
or pngpaste on macOS. The backend must advertise image input support.
After hot-reloading this update, existing sessions need
M-x agent-ide-reconnect once they are idle to negotiate elicitation and boolean
configuration support and receive their initial configuration. Existing image
capabilities, cancellation fixes and incoming title updates work immediately.
M-x agent-ide-inline opens a small prompt window below the current
window, bound to the current project's agent session. The session's
transcript buffer runs in the background and keeps the full conversation.
Responses stream into an overlay viewport at point in the buffer where
you invoked the command.
| Key | Action |
|---|---|
C-c RET / C-c C-m |
Send the prompt; the window closes and the response streams into a viewport at point |
C-c SPC |
Cycle the reference context (region, line, defun, window, buffer); SPC repeats, C-g clears |
C-c ? |
Show key help |
C-c C-b |
Switch the conversation to another live session |
C-c C-v |
Visit the session's transcript buffer |
C-c C-k |
Quit the prompt window |
On the response viewport:
| Key / Mouse | Action |
|---|---|
M-RET or mouse-1 |
Action menu: visit / reply / clear / copy / height± / quit |
C-M-n / C-M-p, mouse wheel |
Scroll the viewport |
C-M-v / C-M-S-v |
Page up/down |
C-c C-u (prefix) |
Clearing with a prefix also aborts the running turn |
| Key | Action |
|---|---|
C-c RET |
Submit prompt |
M-p / M-n |
Cycle through prompt history |
/ |
Insert a slash for agent commands |
TAB |
Complete slash commands (with descriptions) |
The header shows: an animated Agent IDE icon · model name · project directory · context left: N% when the agent reports its context capacity. Hover over the percentage for remaining and total tokens. Context state is retained independently of end-turn token accounting. The transparent PNG is cached in four rotated frames for lightweight animation.
- Markdown rendering — code fences (syntax-highlighted), inline code, bold/italic, links, headings, and wrapped pipe tables. Tables use a cached character-width layout inspired by markdown-ts-appear, with independent layouts for different window widths. The original Markdown remains available for copying. Cell text (including inline code) prefers your monospaced default font; borders prefer an installed Sarasa SC grid font. Customize
agent-ide-table-faceandagent-ide-table-border-faceindependently. Both fonts should have the same Latin character width, with CJK glyphs occupying two columns and border glyphs one. After changing faces, runM-x agent-ide-table-refreshto refresh existing tables. Novalignor Tree-sitter dependency is needed. - Streaming messages — agent text appears word-by-word, markdown-rendered as it arrives.
- Media previews — Markdown images render inline; GIF/APNG, animated WebP and video links use
canvas-video. ACP image content blocks also render in messages and expanded tool output. - Thinking blocks — agent reasoning is shown inside foldable blocks (collapsed by default).
- Tool calls — each tool invocation gets a compact summary with expandable output; diffs are syntax-highlighted.
- Permission prompts — inline buttons plus cursor-independent shortcuts:
C-c C-aallows once,C-u C-c C-aalways allows,C-c C-ddeclines, andC-c C-pshows every option. - Plan rendering — when the agent produces a plan, entries are listed inline.
- Read-only transcript — all agent output is frozen; only the current prompt is editable.
Streaming Markdown refreshes are batched every 50 ms in both the transcript
and inline viewport. Completed paragraphs and code blocks retain their rendering
while new text arrives. Very long unfinished blocks refresh less frequently to
bound repeated parsing; finishing the reply immediately reconciles the full
Markdown. Set agent-ide-stream-render-interval to adjust the batching delay
(zero disables batching). Pending refreshes are cancelled when their buffer closes.
Use  for images and animations, or
[watch](clip.mp4) for video. Local paths resolve against the session project;
paths containing spaces can use .
HTTP(S) images download asynchronously; data:image/...;base64,... also works.
Previews preserve the original Markdown when copied or saved.
Media previews require graphical Emacs. Static formats depend on Emacs image
support. Animations and videos additionally require canvas-video on load-path,
its compiled libmpv module, and a Canvas-capable Emacs. Videos start paused;
animations loop silently. Use the Canvas controls or its C-c C-v prefix for
playback. C-c C-o opens the image or a dedicated Canvas player. Missing files
and unavailable decoders leave readable links with an error message.
The inline response viewport displays static images and offers Canvas playback
links for animations/videos; embedded players appear in the session transcript.
Set agent-ide-media-preview to disable previews, or adjust
agent-ide-media-max-width / agent-ide-media-max-height (default 640 × 400).
Run M-x agent-ide-preview-media to refresh existing messages after changing
settings or installing Canvas. Closing the buffer or removing a media link
releases its downloads, temporary files and player.
A left sidebar lists live sessions. Each entry shows project/[status] (or [ask] when a permission prompt is waiting), model, and an optional third line for the active tool/approval. From a session buffer, press C-c C-b (or M-x agent-ide-sidebar) to focus it.
| Key | Action |
|---|---|
RET / mouse-1 |
Display that session’s buffer via existing agent-ide--display-buffer |
n / p |
Move by entry (two physical lines per entry) |
k |
Kill session (confirm when agent-ide-sidebar-confirm-kill is non-nil) |
r |
Restore the session at point |
h |
Choose backend sessions for the entry's project; prefix shows all projects |
g |
Manual refresh |
q |
Hide sidebar (set user-dismissed; do not kill sessions) |
All options are under the agent-ide customize group (M-x customize-group RET agent-ide).
| Option | Default | Description |
|---|---|---|
agent-ide-command |
("cursor-agent" "acp") |
The ACP backend command |
agent-ide-environment |
nil |
Extra environment variables for the agent process |
agent-ide-buffer-name-prefix |
"agent" |
Session buffer name prefix (e.g. *agent:myproject*) |
agent-ide-new-session-split |
nil |
Where to open new sessions: nil (current window), vertical (right side), or horizontal (bottom) |
agent-ide-select-window-on-open |
t |
Focus the session window when it opens |
agent-ide-text-file-capabilities |
t |
Advertise ACP file read/write to the agent |
agent-ide-model |
nil |
Default model ID applied after session creation |
agent-ide-mcp-servers |
[] |
MCP servers passed to session/new |
agent-ide-history-request-timeout |
30 |
Seconds to wait for each session discovery request |
agent-ide-prompt-placeholder-text |
"Tell Agent what to do..." |
Empty-prompt placeholder |
agent-ide-running-placeholder-text |
"Working..." |
Placeholder while the agent processes |
agent-ide-header-icon-animation-interval |
0.18 |
Seconds between rotations of the Agent IDE header icon; nil disables animation |
agent-ide-sidebar-width |
0.14 |
Left side-window width |
agent-ide-sidebar-auto-show |
nil |
Auto-show on session create when enabled; ignored for refresh while user-dismissed |
agent-ide-sidebar-confirm-kill |
t |
Confirm before kill |
agent-ide-latex-preview |
t |
Preview complete math fragments in graphical Emacs |
agent-ide-latex-process |
xelatex |
Conversion pipeline: xelatex (Chinese-capable SVG), dvisvgm (SVG) or dvipng (PNG) |
agent-ide-latex-cjk-font |
Songti SC on macOS; FandolSong-Regular.otf elsewhere |
Chinese font for XeLaTeX |
agent-ide-latex-scale |
1.3 |
Formula image scale |
agent-ide-latex-timeout |
20 |
Maximum seconds per formula conversion |
Formula previews default to XeLaTeX and require graphical Emacs with SVG support,
xelatex and dvisvgm in Emacs's exec-path, the TeX package xeCJK, and the
font selected by agent-ide-latex-cjk-font. The default font is Songti SC on
macOS and the TeX Live font FandolSong-Regular.otf on other systems.
This supports Chinese inside formulas, for example \(x^2\text{,指数为二}\).
Formula previews launch XeLaTeX and then dvisvgm as asynchronous external
processes. They do not depend on Org or start another Emacs. Agent output and
editing remain responsive while compilation runs. A built-in preamble loads
amsmath, amssymb and xcolor, plus xeCJK and the selected Chinese font for
XeLaTeX. For formulas without Chinese, select dvisvgm with latex, or dvipng
with latex and PNG support. The timeout covers both compilation and image
conversion; errors retain diagnostics and release temporary files before the
next queued formula starts.
Use $x^2$ or \(x^2\) for inline math, and $$...$$ or \[...\] for
display math. Previews appear after the closing delimiter arrives, including in
inline replies. Fenced code blocks (including latex blocks) and inline code
keep their source. Dollar-delimited inline math must stay on one line and have
no spaces immediately inside its delimiters; ordinary $5 and $10 stays text.
Move the text cursor into a formula in the session buffer to reveal its LaTeX
source, as with org-fragtog; moving out restores the cached preview immediately.
This also works while composing in session and inline input boxes. Complete
formulas are previewed after each editing command; move back into a formula to
edit its source. Edits refresh the preview, and sending always uses the original
LaTeX text. Input styling and undo history are preserved.
The underlying LaTeX text remains available for copying. Missing tools, invalid
formulas and conversion timeouts leave the source visible. Identical formulas
share cached images during the Emacs session. Formula foreground colors preserve
the theme's exact RGB values; explicit LaTeX color commands remain effective.
Refreshing after an upgrade also repairs eligible monochrome SVG caches without
recompiling them. Other old images are regenerated with the corrected colors.
On conversion failure, hover over
the formula to see the error summary, or place point in its source and run
M-x agent-ide-latex-show-error to read the retained diagnostic log.
Run M-x agent-ide-preview-latex in a session to preview existing messages or
refresh after changing the engine, Chinese font, scale or theme. This preserves
the editable prompt. Each Markdown body is refreshed separately so raw tool
output cannot disrupt later replies. Recent replies are queued first when old
formulas need conversion.
New replies take priority over history refresh and session replay, including
formulas already waiting in the history queue. A conversion already running is
allowed to finish before the next live formula starts.
For example:
(setq agent-ide-latex-scale 1.3)
;; Then run M-x agent-ide-preview-latex in the session.When upgrading an already running Emacs from the previous default, enable the
new engine with (setq agent-ide-latex-process 'xelatex) and refresh previews.
To turn previews off, set agent-ide-latex-preview to nil; run the same command
to remove existing previews from the current session.
(setq agent-ide-new-session-split 'vertical)Opens each session in a right-side window at 42% width.
;; Cursor Agent
(setq agent-ide-command '("cursor-agent" "acp"))
;; Claude Code (if it exposes an ACP subcommand)
(setq agent-ide-command '("claude" "acp"))
;; Custom agent with extra env
(setq agent-ide-command '("my-agent" "--acp")
agent-ide-environment '("MY_TOKEN=xxx" "DEBUG=1"))(setq agent-ide-mcp-servers
'[((name . "filesystem")
(command . "npx")
(args . ["-y" "@modelcontextprotocol/server-filesystem" "/tmp"]))])agent-ide includes built-in hot-reload support for hacking on the package itself:
| Command | Keybinding | Description |
|---|---|---|
agent-ide-load-file |
C-c C-l |
Reload a single source file |
agent-ide-reload-current-file |
— | Reload the file being visited |
agent-ide-reload-all |
— | Reload all project files in dependency order |
agent-ide-reload-last |
— | Reload the most recently loaded file |
File load order: core → history → protocol → latex → media → stream → table → renderer → session-mode → session → transcript → sidebar → inline → agent-ide.
Run restoration tests with the installed acp package:
emacs -Q --batch --eval '(progn (require (quote package)) (package-initialize))' \
-L . -l acp -l agent-ide-resume-test.el \
-f ert-run-tests-batch-and-exitThe process integration test uses Python 3 and a local ACP fixture with temporary session data. It exercises process exit, reconnection, cold restoration and continued prompting without contacting an agent service.
Run streaming performance and lifecycle regression tests with:
emacs -Q --batch --eval '(progn (require (quote package)) (package-initialize))' \
-L . -l agent-ide-stream-test.el -f ert-run-tests-batch-and-exitThese check bounded rendering work even with batching disabled, cross-chunk Markdown, final flushing and timer cleanup without contacting an agent service.
Run formula preview tests with:
emacs -Q --batch -L . -l agent-ide-latex-test.el -f ert-run-tests-batch-and-exitThe SVG/PNG integration tests use local TeX tools, and skip when those tools or image types are unavailable. They do not contact an agent service.
Run media tests with:
emacs -Q --batch -L . -l agent-ide-media-test.el -f ert-run-tests-batch-and-exitAdd the canvas-video directory with -L to
exercise its adapter and lifecycle. The native GIF test requires graphical
Emacs and AGENT_IDE_TEST_GIF pointing to a local animation; batch tests skip it.
agent-ide.el Entry point, defcustom, require all
├── agent-ide-core.el Session struct, helpers, buffer management
├── agent-ide-history.el ACP session discovery and completion candidates
├── agent-ide-config.el Backend configuration selectors
├── agent-ide-elicitation.el Structured question forms and cancellation
├── agent-ide-attachment.el Draft image attachments and clipboard input
├── agent-ide-renderer.el Transcript rendering, markdown, diff, folds, faces
├── agent-ide-stream.el Batched streaming Markdown and completed-block reuse
├── agent-ide-latex.el Math recognition and asynchronous TeX formula previews
├── agent-ide-media.el Image downloads, previews and canvas-video integration
├── agent-ide-protocol.el ACP bridge (init, prompt, cancel, fs ops)
├── agent-ide-session-mode.el Major mode, keymaps, completion, edit guard
├── agent-ide-transcript.el ACP event dispatch (notifications, requests)
├── agent-ide-session.el User commands, lifecycle, yank-region, set-model
└── agent-ide-sidebar.el Session list side window, switch/kill
Plugins may register on agent-ide-pre-submit-functions to defer submission
(SESSION PROMPT); return non-nil to handle the prompt and call
agent-ide-deliver-prompt later.
MIT — feel free to use, modify, and share.