AI Code Interface MCP server
Commit Nov 14, 2026Lets Emacs users drive multiple AI coding CLIs through one consistent workflow for prompting, code changes, review, and Git tasks.
Also known as tninja/ai-code-interface.el, ai-code-interface-el
- Stars
- 304
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 14, 2026
- License
- Apache-2.0
What is AI Code Interface MCP?
AI Code Interface lets Emacs users drive multiple AI coding CLIs through one consistent workflow for prompting, code changes, review, and Git tasks.
Summary generated from the project's README
Automated checks
Ran Nov 13, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablePass
- Open source license (OSI)Pass
- Commit or release in the last yearPass
- Package name not close to a popular packageNot checked
- Remote endpoint uses HTTPSNot checked
- Destructive tools are labelledNot checked
- No hidden instructions to the modelPass
- No critical advisory in the package or its dependenciesNot checked
README
View on GitHub[[file:./ai-code-interface.png]]
- AI Code Interface
[[https://melpa.org/#/ai-code][https://melpa.org/packages/ai-code-badge.svg]] [[https://stable.melpa.org/#/ai-code][https://stable.melpa.org/packages/ai-code-badge.svg]] [[https://github.com/tninja/ai-code-interface.el/graphs/contributors][https://img.shields.io/github/contributors/tninja/ai-code-interface.el.svg]] [[https://github.com/RoggeOhta/awesome-codex-cli][https://awesome.re/mentioned-badge.svg]]
AI Code Interface is a backend-agnostic Emacs workflow layer for AI-assisted software development.
Use Codex, Claude Code, Gemini CLI, Pi, agent-shell/ACP, and other coding agents while keeping the same Emacs workflow for context, prompting, code changes, review, TDD, Git, tasks, and session management.
** Why AI Code Interface?
AI coding agents change quickly. AI Code Interface keeps your developer workflow stable while allowing the agent underneath to change: the backend can change; your Emacs workflow does not have to.
If you want the deepest possible integration with one specific agent runtime, a dedicated client may be a better fit. If you use or evaluate multiple coding agents and want one consistent Emacs workflow, AI Code Interface is built for that.
Workflow portability is the core idea:
- Keep the same context and prompt workflow.
- Keep the same code-change, review, refactoring, and TDD workflow.
- Keep the same task, Git, MCP, and session workflow.
- Switch the AI backend without rebuilding your Emacs setup.
** Design Philosophy
AI Code Interface unifies developer workflows, not agent runtimes.
Native coding CLIs keep ownership of their own interaction model, tool execution, retries, queueing or steering, permissions, and other runtime behavior. AI Code Interface integrates with those capabilities rather than reimplementing them.
Structured external backends such as agent-shell/ACP can provide deeper lifecycle and UI integration when available, without making those semantics a requirement for every backend. This keeps the common workflow portable while allowing each backend to use its native strengths.
Supported AI coding CLIs: Claude Code, OpenAI Codex, Gemini CLI, GitHub Copilot CLI, Cursor CLI, Opencode, Aider, Grok CLI, Kiro CLI, Kilo, Pi, Antigravity CLI, Muse Code, CodeBuddy Code, and Open Interpreter, plus external backends such as agent-shell (ACP), ECA, claude-code-ide.el, and claude-code.el.
See [[https://github.com/tninja/ai-code-interface.el/tree/main#ai-coding-cli-backend][AI coding CLI backend]] for the full backend list and configuration details.
- Screenshot
[[./transient_menu.png]]
** New User Quick Start
If you are new to this package, follow this order:
- Read this section
- Run the setup in Installation
- Try one workflow in Typical Workflows Example
- Configure backend details in AI coding CLI backend
Minimal setup:
#+begin_src emacs-lisp (use-package ai-code :config (ai-code-set-backend 'codex) ;; Optional: use a narrower transient menu on smaller frames ;; (setq ai-code-menu-layout 'two-columns) (global-set-key (kbd "C-c a") #'ai-code-menu)) #+end_src
First 60 seconds:
C-c a a: Start the currently selected AI CLI sessionC-c a c: Ask AI to change current function/regionC-c a q: Ask question only (no code change)C-c a z: Jump back to AI session buffer
The first time you open C-c a, AI Code also shows a small quickstart buffer
with these core actions. You can reopen it later from C-c a h
(Help / Quick Start).
** Installation
Enable installation of packages from MELPA by adding an entry to package-archives after (require 'package) and before the call to package-initialize in your init.el or .emacs file:
#+begin_src emacs-lisp (require 'package) (add-to-list 'package-archives '("melpa" . "https://melpa.org/packages/") t) (package-initialize) #+end_src
- Use =M-x package-refresh-contents= or =M-x package-list-packages= to ensure that Emacs has fetched the MELPA package list
- Use =M-x package-install= to install =ai-code= package
- Import and configure =ai-code= in your init.el or .emacs file:
#+begin_src emacs-lisp (use-package ai-code ;; :straight (:host github :repo "tninja/ai-code-interface.el") ;; if you want to use straight to install, no need to have MELPA setting above :config ;; use codex as backend, other options are 'pi, 'claude-code, 'gemini, 'github-copilot-cli, 'open-interpreter, 'opencode, 'kilo, 'grok, 'cursor, 'kiro, 'codebuddy, 'aider, 'eca, 'agent-shell, 'claude-code-ide, 'claude-code-el (ai-code-set-backend 'codex) ;; Optional: default menu stays unchanged; use a narrower 2-column layout on smaller frames ;; (setq ai-code-menu-layout 'two-columns) ;; Enable global keybinding for the main menu (global-set-key (kbd "C-c a") #'ai-code-menu) ;; Optional: Use eat if you prefer, by default it is vterm ;; (setq ai-code-backends-infra-terminal-backend 'eat) ;; config for native CLI backends. for external backends such as agent-shell, claude-code-ide.el and claude-code.el, please check their own config ;; Optional: Try ghostel as an backend infra ;; (setq ai-code-backends-infra-terminal-backend 'ghostel) ;; Optional: Badge tab-bar tabs that show AI sessions with their state (○ idle, ◐ working, ✓ done unseen, ? needs input) ;; (ai-code-session-attention-mode 1) ;; Optional: Disable @ file completion in comments and AI sessions ;; (ai-code-prompt-filepath-completion-mode -1) ;; Optional: Ask AI to run test after code changes, for a tighter build-test loop (setq ai-code-auto-test-type 'ask-me) ;; Optional: Disable numbered next steps for discussion prompts at send time ;; (enabled by default) ;; (setq ai-code-discussion-auto-follow-up-enabled nil) ;; Optional: Show candidates as you type in task file, using company ;; (add-hook 'ai-code-prompt-mode-hook #'ai-code-prompt-completion-setup) ;; Optional: Turn on auto-revert buffer, so that the AI code change automatically appears in the buffer (global-auto-revert-mode 1) (setq auto-revert-interval 1) ;; set to 1 second for faster update ;; Optional: Set up Magit integration for AI commands in Magit popups (with-eval-after-load 'magit (ai-code-magit-setup-transients))) #+end_src
** Windows
Native Windows Emacs is supported. Ghostel is the recommended terminal backend because it uses ConPTY and provides pre-built Windows native modules. If the default vterm backend cannot start on native Windows, AI Code automatically falls back to Ghostel. See [[./docs/windows.org][Native Windows Support]] for setup and troubleshooting.
** Dependencies
*** Required Dependencies
- Emacs 29.1 or later
org: Org-mode supportmagit: Git integrationtransient: For the menu system- One of vterm (default), eat, or [[https://github.com/dakra/ghostel][ghostel]] needs to be installed to support native AI coding CLI backends, depending on
ai-code-backends-infra-terminal-backend. - [[https://github.com/dakra/ghostel][ghostel]] is a newly supported native backend infra option.
- Ghostel is an Emacs terminal emulator powered by libghostty-vt, the VT engine from Ghostty.
- AI Code enables Ghostel image support for AI sessions:
- terminal programs can use Ghostel's Kitty graphics protocol;
- local image paths printed by an AI CLI (for example =screenshot.png=) are previewed inline in the session buffer while the source path remains visible and clickable.
- tall local previews can use the optional =ultra-scroll= integration described below.
- while a local preview is visible, line scrolling (=scroll-up-line=, =scroll-down-line=, evil's =C-e= / =C-y=) and the plain mouse wheel move by pixels, one line height per step, instead of jumping a whole image.
- [[https://github.com/dakra/ghostel][ghostel]] is under active development, please install the latest version.
- To try it:
#+begin_src emacs-lisp (setq ai-code-backends-infra-terminal-backend 'ghostel) #+end_src
*** Optional Dependencies
- [[https://github.com/jdtsmith/ultra-scroll][ultra-scroll]]: Recommended for partial-pixel scrolling past tall local image previews in Ghostel. AI Code loads and dispatches it only while such a preview is visible, without enabling its global mode. Set =ai-code-ghostel-image-preview-prefer-ultra-scroll= to =nil= to opt out.
helm: For an enhanced auto-completion experience (ai-code-input.el).whisper: For speech-to-text input viaai-code-speech-to-text-input. Record audio, pressRETto stop, then choose whether to insert the transcription into the current buffer, send it to the active AI coding session with editable initial input, or copy it to the clipboard.gptel: For intelligent, AI-generated content headlines in the prompt file.- ai-code-task-use-gptel-filename: When non-nil, file name created by
ai-code-create-or-open-task-fileorai-code-create-file-or-dirwill have auto-generated filenames created by GPTel - ai-code-use-gptel-headline: When non-nil, prompts sent to the AI will have auto-generated headlines created by GPTel, providing better organization and readability in the prompt file
- ai-code-use-gptel-classify-prompt: When non-nil, and
ai-code-auto-test-typeorai-code-discussion-auto-follow-up-enabledis non-nil, classify whether the current prompt is about code changes so test prompts or discussion follow-up suggestions are only added when relevant
- ai-code-task-use-gptel-filename: When non-nil, file name created by
flycheck: To enable the =Fix Flycheck errors in scope= action under =C-c a b= and theai-code-flycheck-fix-errors-in-scopecommand.yasnippet: For snippet support in the prompt file. A library of snippets is included.- (emacs built-in) abbrev + skeleton is also a good way to expand prompt. [[./etc/prompt_expand_with_abbrev_skeleton.el][example abbrev to solve / iterate leetcode problem with tdd (need to set ai-code-auto-test-type with tdd)]], [[./examples/leetcode][example problem resolved]]
cape/company: For inline completion of prompts you have written before, described under [[*Reusing Prompts You Already Wrote][Reusing Prompts You Already Wrote]]. Prompt completion itself needs neither package.cape, when installed, adds English dictionary words to the same candidate list with no configuration;companyshows the candidates as you type once you opt in. Neither is a dependency, and neither is loaded when it is not installed.projectile: For project root initialization.helm-gtags: For tags creation and symbol navigation fallback from clickable session symbols.
*** Optional Screenshot Capture
The Insert submenu's =Screenshot= commands rely on an external program to capture an image. Install or configure the option for your platform:
| Platform | Screenshot capture | Setup | |-----------------+-----------------------------------+--------------------------------------------| | macOS | =screencapture= | Preinstalled; used by default with =-i=. | | Linux (Wayland) | =grim= | Install =grim=; selected when =WAYLAND_DISPLAY= is set. | | Linux (X11) | =import= from ImageMagick | Install the ImageMagick package. | | Windows | No compatible tool is bundled | Configure a capture program as shown below. |
Customize =ai-code-send-screenshot-command= when the default is unavailable. The command is a list containing the program followed by its arguments; AI Code appends the destination PNG path when invoking it:
#+begin_src emacs-lisp (setopt ai-code-send-screenshot-command '("my-screenshot-program" "--interactive")) #+end_src
** Key Features
- Transient-Driven Hub (
C-c a): One keystroke opens a contextual transient menu that groups every capability (CLI control, code actions, agile workflows, utilities) so you never need to memorize scattered keybindings.- If the default wide layout does not fit your frame well, set
ai-code-menu-layouttotwo-columnsfor a narrower menu with the same commands.
- If the default wide layout does not fit your frame well, set
- AI CLI Session Management: Start (
a), resume (R), or jump back into (z) the active AI CLI buffer, instantly swap backends (s), upgrade them (u), install backend skills (S), edit backend configs (g), open backend agent file (G), and run prompts against the current file (|). It supports multiple sessions per project. TheSentry is especially useful for installing shared skill packs such as [[https://github.com/obra/superpowers][obra/superpowers]].-
A task associated with a worktree uses that checkout for backend selection, behavior settings, and project session lookup, even when the task file is shared from the main repository. Shared task storage stays in the main repository.
-
Ztoggles the AI session dashboard in a window across the bottom of the frame, where you can inspect active sessions, refresh the list, visit a session buffer, kill a session, or open the repository's Magit status. PressZagain, orqin the dashboard, to close it. Besides repository, task file, backend and branch, each row shows the session's Status, how long it has been in that state (Since), its uncommitted changes (for example =2 files +3 −2=), and a one-line summary of the last prompt sent to it from Emacs; hover over the summary to see the prompt.With =tab-bar-mode= enabled, =RET= returns to the tab showing the session and focuses its window, preserving existing tab layouts. If no tab shows it, a new tab opens for the session.
[[file:./session_dashboard.png]]
-
Hsends a session checkpoint prompt when run from an AI session buffer, asking the AI to summarize the goal, files changed, current hypothesis, tests/build result, blockers, and next action. -
When resuming, selecting a UUID in the region appends that UUID automatically so you can continue a specific session.
-
In AI session side windows,
C-.grows andC-,shrinks the panel immediately. On left/right side windows it adjusts width; on top/bottom side windows it adjusts height.
-
- AI CLI Editor Viewport: Managed terminal TUI sessions support editing in a native Emacs viewport.
- Within managed AI CLI sessions, general
EDITOR/VISUALrequests auto-submit by default (ai-code-editor-viewport-auto-submitist). Set it tonilto make those requests save-only, includingkubectl editorcrontab -elaunched inside the session; Git editor requests are always save-only.
- Within managed AI CLI sessions, general
- Clickable Session Links: In AI session buffers, supported in-repo file references, nearby code symbols, and
http/httpsURLs are underlined and clickable. File links such assrc/foo.el:42,src/foo.el:42:7,src/foo.el:L42-L60, orsrc/foo.el#L42-L60jump directly to the right location, nearby symbols such assetq-local,ai-code-session-link-enabled, orUserService.processRequest()trigger code navigation in the associated file, and web links open in your browser. Symbol navigation first triesxref, thenhelm-gtagswhen available, and finally falls back to searching in the opened file buffer. Setai-code-session-link-enabledtonilif you want to disable this link rendering. [[./clickable_link_ai_session.png]] - Context-Aware Code Actions: The menu exposes dedicated entries for changing code (
c), implementing TODOs (i), asking questions (q), explaining code (x), sending free-form commands (<SPC>), and managing AI context (@). The context menu can copy scoped references with repository-relative or full paths, including the current function or selected line range. Each command automatically captures the surrounding function, region, or clipboard contents (viaC-u) to keep prompts precise.- In Dired, changing, asking, explaining, refactoring, copying, and adding context use all marked files/directories in buffer order, falling back to the file at point when nothing is marked. Insert follows the same rule unless an active Dired region selects its files explicitly.
- Address code annotation (
munder AI code actions with context): Manage source-file and Magit hunk annotations and ask AI for suggestions about them. Requires the optional, ordinary [[https://github.com/bastibe/annotate.el][annotate.el]] package, version 2.5.0 or newer (annotation IDs); no modified annotate fork is needed. If annotate.el is missing or no annotations exist, the command explains this instead of sending an empty request.- The command offers six ordered choices: 1. Add / Edit annotation at point, 2. Browse worktree annotations, 3. Ask AI about annotation at point, 4. Ask AI about worktree annotations, 5. Delete annotation at point, 6. Clear worktree annotations. Outside Git, "worktree" is replaced by "current file". The prompt displays the scope, annotation count (including replies), and whether the at-point annotation mode is enabled. In Magit buffers the at-point actions use hunk notes; elsewhere they use =annotate-mode= (enabled automatically when adding). Clearing asks for confirmation and preserves annotations outside the selected scope.
- Browse opens the read-only =AI Code Annotations= list with type, file, matched line number, status and text summary. =RET= jumps to an exact current match, or previews the snapshot if the note is stale; =v= previews the complete note, replies and snapshot. =e= edits note text and =d= deletes a note and its replies after confirmation. Both work on unmatched saved notes without changing source files or guessing new locations. In the note editor, =C-c C-c= saves and =C-c C-k= cancels.
- In the list, =m= toggles a mark, =s= asks AI about marked notes (or the current row when none are marked), =f= asks about every source and hunk note for the row's file, =w= asks about the entire scope, and =g= refreshes the list. Source replies are included with their selected root note. Outside the list, =M-x ai-code-annotation-send-file= asks about the current source file or Magit file section. These narrower scopes avoid sending unrelated notes and oversized worktree context.
- Use =annotate-mode= to annotate source files. For Magit status/diff buffers, use =M-x ai-code-annotate-magit-mode= instead (do not enable =annotate-mode= there). =C-c # a= edits a hunk/selected-line note, =C-c C-c= saves it, =C-c C-k= cancels, =C-c # d= deletes, =C-c # s= previews all saved worktree notes, and =C-c # w= copies them.
- Magit notes retain the original diff, file/old-file names, source line ranges, branch and HEAD. They survive refresh and reopening, and reattach only to exact, unambiguous hunk/context matches; branch and HEAD are metadata, so unrelated commits or branch switches do not detach staged/unstaged notes. Unmatched snapshots remain available for review, and notes exported without a Magit view of the worktree are marked =NOT CHECKED= rather than unmatched. =ai-code-annotate-magit-file= configures the separate database (default =~/.emacs.d/annotate-magit-reviews=, compatible with the earlier optional integration).
- The action collects source annotations from the active =annotate-file= database and databases associated with live annotated buffers in the current worktree. Live root notes override saved records, including unsaved edits/deletions, while retaining saved reply chains to surviving roots. Legacy records are read completely and migrated without truncation when written. Closed files using an unrelated, undiscovered local database are not scanned. Outside Git, only the current source file is included. Stale/missing source text is marked unmatched, with no guessed current line numbers. At-point requests distinguish a disabled annotation mode from an absence of notes; browsing saved notes does not require enabling their display mode.
- Before anything is sent, the assembled prompt always opens in the =AI Compose= buffer for review, with its character count in the header: edit it freely, then =C-c C-c= sends it or =C-c C-k= cancels without sending.
- AI focuses on each annotation and its replies; the associated source excerpts or original diff snapshots provide supporting context. It interprets the concern/question, checks whether replies already resolve it, and explains a focused response with reasons, risks and directly related proposed patches/tests. It does not perform a general code review or suggest unrelated changes, and waits for your decision. It must not modify files or resolve notes. Generic prompt suffixes and Org summary-write instructions are suppressed for this action. This is a suggestions-only prompt, not a backend filesystem sandbox: select a read-only backend permission mode if you need enforced write prevention. After reviewing, separately ask AI to implement only the suggestions you approve. Existing notes are not automatically deleted or resolved.
- When a visible AI session buffer already exists, prompts can be routed to that session directly instead of opening a new one.
- Insert into AI Sessions: Open the configurable
ai-code-menuprefix (C-c ain the configuration examples), then pressIto open the Insert submenu for files, Dired selections, regions, diagnostics-aware DWIM, screenshots, and clipboard images. TheIentry always remains available. If no session is running, pressing it reports that state; if only sessions for other projects are running, it opens the submenu with just theto...entries for choosing one explicitly. An editor viewport associated with the destination session receives the insertion when present; otherwise AI Code inserts into that session's TUI input without submitting it. Screenshot capture may require the [[*Optional Screenshot Capture][platform-specific utility described above]].- Inserted TUI content is always preceded and followed by two newline characters.[fn:insert-tui-spacing] In a viewport, AI Code omits the leading two newlines when the viewport is empty, keeps them when it already contains content, and always appends two newlines. Viewport attachments follow the same spacing rule.
- Agile Development Workflows: Use the refactoring navigator (
r), the guided TDD cycle (t), and the pull/review diff helper (v) to keep AI-assisted work aligned with agile best practices. Prompt authoring is first-class through quick access to the prompt file (p), build/test helper (b), and AI-assisted shell/file execution (!). In prompt files, send the current block withC-c C-c. - Acceptance Tests: Press =C-c a t= and select =7. Acceptance tests=. Optionally provide an original requirement or issue URL; leave it blank to let the agent follow human-authored references from the current Org task or AI session. The request is editable in Compose. Prefer stable E2E coverage when practical, otherwise integration/unit tests; explain the choice and comment on the linked acceptance criteria. Only tests and necessary test fixtures may be changed; implementation defects must be reported, not silently fixed. This is an agent instruction, not a filesystem permission boundary.
- Productivity & Debugging Utilities: Initialize project navigation assets (
.), investigate exceptions (e), debug Emacs runtime issues (d), auto-fix Flycheck issues in scope (f), create or open task files (k), open prompt history (p), capture session notes straight into Org (n), search notes with AI (/), and dictate prompts with speech-to-text (:). - Architecture Document Generation: Derive practical architecture documents for the current repository with
C-c a A(ai-code-derive-architecture-document). The command can generate architecture guardrails, a C4 PlantUML overview, a lightweight DDD context, or a test context document under.ai.code.files/architecture/so future AI coding sessions can reuse module boundaries, dependency rules, runtime flows, and validation expectations. See [[./docs/architecture/c4-overview.org][the C4 ar
AI Code Interface MCP questions
Which AI coding CLIs does AI Code Interface support?
It supports Claude Code, OpenAI Codex, Gemini CLI, GitHub Copilot CLI, Cursor CLI, Opencode, Aider, Grok CLI, Kiro CLI, Kilo, Pi, Antigravity CLI, Muse Code, CodeBuddy Code, and Open Interpreter, plus external backends such as agent-shell (ACP).
How do I switch the AI backend in AI Code Interface?
Call ai-code-set-backend with a backend symbol such as 'codex, 'claude-code, or 'gemini in your init file. This lets you change the AI backend without rebuilding your Emacs setup.
What Emacs version does AI Code Interface require?
It requires Emacs 29.1 or later, along with org, magit, transient, and a terminal backend such as vterm, eat, or ghostel.
How do I open the AI Code Interface menu?
Bind ai-code-menu to a key such as C-c a, then press it to open a transient menu that groups CLI control, code actions, agile workflows, and utilities.
Can AI Code Interface run on native Windows?
Yes, native Windows Emacs is supported, with Ghostel recommended as the terminal backend since it uses ConPTY; if vterm cannot start, AI Code falls back to Ghostel automatically.