ECA Emacs

ECA (Editor Code Assistant) Emacs is an AI-powered pair-programming client for Emacs. Inspired by lsp-mode’s JSONRPC handling, it connects to an external eca server process to provide interactive chat, code suggestions, context management and more.

For more details about ECA, check ECA server.

Requirements

• Emacs 28.1 or later

Optional

• Custom eca server binary, it's automatically downloaded if eca-custom-command is nil
  • Place it on your $PATH or customize eca-custom-command
• whisper.el for Speech-to-Text support (optional)

Installation

Melpa

M-x package-install eca

Doom Emacs:

(package! eca :recipe (:host github :repo "editor-code-assistant/eca-emacs" :files ("*.el")))

Quickstart

1. Run M-x eca to start the eca process and initialize the workspace.

• eca-emacs will check for eca-custom-command;
• if not set, will check for a eca on $PATH;
• if not found, will download eca automatically and cache it.

2. The dedicated chat window <eca-chat> pops up.
3. Type your prompt after the > and press RET.
4. Attach more context auto completing after the @.

Tips

Functions

• eca-chat-add-context-at-point: Add the current function or selected lines to chat as context.
• eca-chat-add-file-context: Add the current file to chat as context.
• eca-keep-all-suggested-changes: Accept planned edit changes on file.
• eca-discard-all-suggested-changes: Reject planned edit changes on file.
• eca-chat-send-prompt: In case you wanna send prompts programatically in elisp.

Variables

• eca-extra-args: customize extra args to server to help debug like ("--verbose") or ("--log-level" "debug").
• eca-chat-usage-string-format: to customize what shows on mode-line for usage like costs and tokens.
• eca-chat-use-side-window: customize whether chat window is a side-window or a normal buffer.
• eca-chat-window-side: customize the chat window side.
• eca-chat-window-width: customize the chat window width.
• eca-chat-window-height: customize the chat window height.

Keybindings

You can access transient_ menu with commonly commands via M-x eca-transient-menu or by pressing C-c . in eca's windows.

Manual keybindings

Feature	key
Chat: clear	C-c C-l
Chat: reset	C-c C-k
Chat: talk	C-c C-t
Chat: Select behavior	C-c C-b
Chat: Select model	C-c C-m
Chat: Go to MCP details	C-c C-,
Chat: prev prompt history	C-↑
Chat: next prompt history	C-↓
Chat: go to prev block	C-c ↑
Chat: go to next block	C-c ↓
Chat: go to prev user msg	C-c C-↑
Chat: go to next user msg	C-c C-↓
Chat: toggle expandable content	C-c Tab
MCP: Go to chat	C-c C-,

Advanced Usage

Speech-to-Text support (Talk)

If you have whisper.el installed you can use the eca-chat-talk command (or use the C-t keybinding) to talk to the Editor Code Assistant. This will record audio until you press RET. Then, the recorded audio will be transcribed to text and placed into the chat buffer.

We recommend to use the small, it is a good trade-off between accuracy and transcription speed.

(use-package whisper
  :custom
  (whisper-model "small"))

Custom workspaces

Calling M-x eca with prefix C-u will ask for what workspaces to start the process.

Troubleshooting

Environment Variables Not Available (macOS/Linux GUI)

When launching Emacs from a GUI application (Dock, Applications folder, or desktop environment), it doesn't inherit environment variables from your shell configuration files (.zshrc, .bashrc, etc.). Since the ECA server is started as a subprocess from Emacs, it inherits Emacs' environment, which may be missing your API keys and other configuration.

Symptoms

• ECA fails to start with authentication errors
• Missing API keys for OpenAI, Anthropic, or other providers
• Custom configuration variables not found

Solution: Use exec-path-from-shell

Install and configure exec-path-from-shell to import your shell environment into Emacs:

(use-package exec-path-from-shell
  :init
  ;; Specify the environment variables ECA needs
  (setq exec-path-from-shell-variables
        '("ANTHROPIC_API_KEY"
          "OPENAI_API_KEY"
          "OLLAMA_API_BASE"
          "OPENAI_API_URL"
          "ANTHROPIC_API_URL"
          "ECA_CONFIG"
          "XDG_CONFIG_HOME"
          "PATH"
          "MANPATH"))
  ;; For macOS and Linux GUI environments
  (when (memq window-system '(mac ns x))
    (exec-path-from-shell-initialize)))

Alternative Solutions

1. Launch Emacs from Terminal: Start Emacs from your shell where environment variables are already loaded:

   emacs &

2. Manual Environment Setup: Set variables directly in your Emacs configuration:

   (setenv "ANTHROPIC_API_KEY" "your-key-here")
   (setenv "OPENAI_API_KEY" "your-key-here")

3. System-wide Environment: On macOS, you can set environment variables system-wide using launchctl:

   launchctl setenv ANTHROPIC_API_KEY "your-key-here"

ECA Server Connection Issues

Problem: ECA server fails to start or connect

1. Check ECA installation: Verify ECA is available on your PATH or set eca-custom-command:

   (setq eca-custom-command "/path/to/your/eca/binary")

2. Enable debug logging: Add extra arguments for debugging:

   (setq eca-extra-args '("--verbose" "--log-level" "debug"))

3. Check environment variables: Test if your API keys are available in Emacs:

   M-x eval-expression RET (getenv "ANTHROPIC_API_KEY") RET

Model-Specific Issues

OpenAI Models Not Working

• Ensure OPENAI_API_KEY is set in your environment
• For custom endpoints, set OPENAI_API_URL

Anthropic Models Not Working

• Ensure ANTHROPIC_API_KEY is set in your environment
• For custom endpoints, set ANTHROPIC_API_URL

Ollama Models Not Working

• Ensure Ollama is running locally
• Set OLLAMA_API_BASE if using a custom endpoint
• Use the ollama/ prefix for model names (e.g., ollama/llama2)

Debugging Steps

1. Verify environment: Check what environment variables are available to Emacs:

   M-x eval-expression RET process-environment RET

2. Test ECA manually: Try running ECA from terminal to verify it works:

   eca --help

3. Reset ECA: Clear the workspace and restart:

   M-x eca-chat-reset
   M-x eca  ; Start fresh
   

Contributing

Contributions are very welcome, please open a issue for discussion or pull request.