ECA Development#
Building local#
- Install babashka.
- Run
bb debug-cli, it will generate a JVM embedded binary at project root where you can just./eca.
Project structure#
The ECA codebase follows a pragmatic layered layout that separates concerns clearly so that you can jump straight to the part you need to change.
Files overview#
| Path | Responsibility |
|---|---|
bb.edn |
Babashka tasks (e.g. bb test, bb debug-cli) for local workflows and CI, the main entrypoint for most tasks. |
deps.edn |
Clojure dependency coordinates and aliases used by the JVM build and the native GraalVM image. |
docs/ |
Markdown documentation shown at https://eca.dev |
src/eca/main.clj |
The CLI interface (eca server, etc.). |
src/eca/server.clj |
stdio entry point; wires everything together via jsonrpc4clj: the protocol methods core serves, then the modules' (:rpc). |
src/eca/handlers.clj |
Entrypoint for all features; every JSON-RPC request/notification lands here. |
src/eca/messenger.clj |
Protocol to send requests/notifications back to the client (stdio or remote). |
src/eca/db.clj + db/ |
In-memory state atom (db*); sessions, chats, tool servers — all state lives here. db/ saves and loads it: the cache files (io), chat files (chats), the global cache (global_cache), loading and migrating (migration). |
src/eca/config.clj |
Centralized place to get ECA configs from multiple places (global, local, env, initializationOptions). |
src/eca/logger.clj |
Logger interface, logs to stderr (stdout is reserved for JSON-RPC). |
src/eca/shared.clj |
Shared utility fns for the whole project. |
src/eca/llm_api.clj + llm_api/ |
Public façade used by features to call an LLM, through the provider modules' APIs; llm_api/ classifies their errors (errors.clj) and renews login tokens (auth.clj). |
src/eca/llm_util.clj |
Streaming/event helpers shared by providers. |
src/eca/features/ |
Core capabilities exposed to the editor |
├─ chat.clj + chat/ |
The chat engine: chat.clj is its entry (prompt, commands, tool-call answers, stop); chat/ has a turn's requests (turn, their callbacks, recovery), compaction, the lifecycle (content, events, finish), the tool-call state machine and batches, steering, replay, chat operations and the system prompt. |
├─ commands.clj |
Lists the modules' commands, with the skills, custom commands and MCP prompts they give, and runs the one typed. |
├─ context.clj |
Contexts attached to prompts: files, folders, the cursor, and the ones modules give. |
├─ prompt.clj |
System prompt templates and variable interpolation. |
├─ index.clj |
Workspace files, as index.ignoreFiles allows. |
└─ tools.clj + tools/ |
Tool pipeline: tool servers, calls; tools/util.clj helpers. The approval rules are eca/approval's (modules/approval.clj). |
src/eca/modules/ |
Modules: the runtime (modules.clj, events.clj, loader.clj, ...) and the built-in modules, one namespace each, listed in built_in.clj, which eca.main hands to the runtime |
├─ core.clj |
ECA's own commands (/model, /compact, /context, /modules, ...) and prompt sections; the chat ones (/fork, /resume, /export, /debug-chat, ...) are in chat_management.clj. |
├─ tools/ |
Built-in tools: filesystem.clj, shell.clj, git.clj, editor.clj, task.clj, ... |
├─ providers/ |
LLM providers, each with its API when it has its own (anthropic.clj, openai.clj, openai_chat.clj, ...), declaring what's theirs: logins, quotas, request options, models, errors. |
├─ llm_providers.clj + llm_providers/ |
Logging into providers (/login, the providers panel's providers/* methods) and their subscription quotas (/quota). |
├─ agents.clj + agents/ |
Agents from config and Markdown files, and the agents ECA ships; subagents.clj + subagents/ likewise. |
├─ mcp.clj |
MCP (Model Context Protocol) servers integration, with their OAuth. |
├─ hooks.clj |
User-configured hooks triggered on server events. |
├─ skills.clj, rules.clj |
Skills and rules: discovery, loading, their tools and prompt sections. |
├─ remote.clj + remote/ |
Optional remote HTTP/SSE server exposing chats to non-stdio clients. |
| └─ ... | agents_md.clj (AGENTS.md files), chat_title.clj, compact_as_summary.clj, completion.clj and rewrite.clj (inline completion and rewrite), plugins.clj, approval.clj, manage.clj, otel.clj, repl.clj, ... |
src/eca/api.clj + api/ |
The module API: all that external modules see. |
src/eca/nrepl.clj |
Starts an nREPL when built with bb debug-cli. |
Together these files implement the request flow:
client/editor → stdin JSON-RPC → handlers → features and modules → llm_api → provider module → results streamed back via messenger.
With this map you can usually answer:
- "Where does request X enter the system?" – look in
handlers.clj. - "How is tool Y executed?" – see
src/eca/modules/tools/<y>.clj. - "How do we talk to provider Z?" – its module under
src/eca/modules/providers/.
Core and modules#
ECA is a core plus modules. Core is layered, lowest first, and a namespace requires only its own layer and lower ones:
- Libs:
eca.logger,eca.shared,eca.messenger,eca.cache, ... - The module runtime:
eca.modules,eca.modules.events,eca.modules.config-spec,eca.modules.data;eca.shell. - State and config:
eca.config,eca.db,eca.models,eca.llm-util, ... - The module loader and the module API (
eca.api,eca.api.test). - Engines:
eca.features.*(chat, tools, commands, prompt, ...),eca.llm-apiandeca.llm-api.*. - Wiring:
eca.server,eca.handlers,eca.main, the built-in modules list.
Every other feature is a module under src/eca/modules/, built in or external, with these rules:
- Core requires no built-in module, except the built-in list and the startup of plugins, remote and otel.
- Modules extend core through module keys (what they contribute: config, tools, tool servers, commands, protocol methods, contexts, prompt sections, providers, ...) and events (decisions at runtime). Core doesn't call a module, check a module's id (the startup of remote, otel and repl aside) or offer a multimethod for modules to extend.
- Every module key works for every module, built in or external; only the calls differ: a built-in's run inline, as the code it replaced, and an external module's are guarded (timeouts, failures counted).
- A built-in module uses another module's namespaces only when it requires that module (
:requires), so turning a module off never leaves its code running for another. Code two modules share goes in a core lib, or reaches the other module through an event, a module key or a function it hands over (likeeca/llm-providers'done!to a provider's login).
test/eca/architecture_test.clj checks the layers and the rules, also in requiring-resolves and fully qualified calls. Its allowlists hold the couplings left from before the rules (and the module API resolving the engines at runtime), and only shrink.
Unit Tests#
Run with bb test or run tests via Clojure REPL. CI runs the same task.
To run a single namespace or test, use kaocha's focus:
clojure -M:test --focus eca.features.chat-test
Integration Tests#
Run with bb integration-test, it will use your eca binary at project root (build one with bb debug-cli or bb prod-cli) to spawn a server process and communicate with it via JSONRPC, testing the whole eca flow like an editor. LLM and MCP servers are mocked (integration-test/llm_mock, integration-test/mcp_mock), so no API keys are needed.
Useful flags (see bb integration-test -h):
--dev: run the server from source via theclojureCLI instead of a binary.--ns integration.chat.anthropic-test: run only specific test namespaces (comma-separated);-llists them.--proxy: route requests through a transient Tinyproxy to verify proxy support.
Coding#
There are several ways of finding and fixing a bug or implementing a new feature:
- Create a test for your bug/feature, then implement the code following the test (TDD).
- Build a local
ecaJVM embedded binary usingbb debug-cli(requiresbabashka), and test it manually in your client pointing to it. After started, you can connect to the nrepl port mentioned in eca stderr, do you changes, evaluate and it will be affected on the running eca. - Using a debug binary you can connect to the REPL, make changes to the running eca process (really handy).
- Use ECA and tell to use the built-in repl-eca-development skill in this repo to test ECA via LLM.
Supporting a new editor#
When supporting a new editor, it's important to keep UX consistency across editors, check how other editors done or ask for help.
This step-by-step feature implementation help track progress and next steps:
- [ ] Create the plugin/extension repo (editor-code-assistant/eca-<editor> would be ideal), ask maintainers for permission.
- Server
- Manage ECA server process.
- [ ] Automatic download of latest server.
- [ ] Allow user specify server path/args.
- [ ] Commands for Start/stop server from editor.
- [ ] Show server status (modeline, bottom of editor, etc).
- [ ] JSONRPC communication with eca server process via stdin/stdout sending/receiving requests and notifications, check [protocol](./protocol.md).
- [ ] Allow check eca server process stderr for debugging/logs.
- [ ] Support `initialize` and `initialized` methods.
- [ ] Support `exit` and `shutdown` methods.
- Chat
- [ ] Open chat window
- [ ] Send user messages via `chat/prompt` request.
- [ ] Clear chat and Reset chat.
- [ ] Support receive chat contents via `chat/contentReceived` notification.
- [ ] Present and allow user change agents and models returned from `initialize` request.
- [ ] Present and add contexts via `chat/queryContext` request
- [ ] Support tools contents: run/approval/reject via `chat/toolCallApprove` or `chat/toolCallReject`.
- [ ] Support tools details: showing a file change like a diff.
- [ ] Support reason/thoughts content blocks.
- [ ] Show MCPs summary (running, failed, pending).
- [ ] Support chat commands (`/`) auto completion, querying via `chat/queryCommands`.
- [ ] Show usage (costs/tokens, or subscription quota) from usage content blocks.
- [ ] keybindings: navigate through chat blocks/messages, clear chat.
- MCP
- [ ] Open MCP details window
- [ ] Receive MCP server updates and update chat and mcp-details ux.
- [ ] Basic plugin/extension documentation
Create a issue to help track the effort copying and pasting these check box to help track progress, example.
Please provide feedback of the difficulties implementing your server, especially missing docs, to make next integrations smoother!
Working on the docs#
The site at https://eca.dev is built with MkDocs Material from docs/ and mkdocs.yml. Both options below serve it at http://localhost:8000 and reload on save.
With Docker#
Uses the same image as CI, so plugins and versions match the published site.
docker run --rm -it -p 8000:8000 -v ${PWD}:/docs \
ghcr.io/editor-code-assistant/docs-image/docs-image serve -a 0.0.0.0:8000
To check a full build, as CI does:
docker run --rm -v ${PWD}:/docs ghcr.io/editor-code-assistant/docs-image/docs-image -- build
Without Docker#
Install uv, then run from the repo root:
uvx --with 'mkdocs-material==9.6.*' \
--with mkdocs-awesome-pages-plugin \
--with mkdocs-git-revision-date-localized-plugin \
mkdocs serve
The --with list mirrors plugins: in mkdocs.yml. If you add a plugin there, add it here too. The revision-date plugin reads git history, so run this from a git checkout.
mkdocs-material is pinned to 9.6 because the CI image is built on squidfunk/mkdocs-material:9.6. Without the pin, uvx installs the newest release, which can render differently from the published site. When the image moves to a new Material version, change the pin to match.