You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
ECA (Editor Code Assistant) is a Clojure server that editors talk to over stdin/stdout JSON-RPC to provide AI coding features (chat, tools, MCP, agents). Shipped as a GraalVM native binary.
-`src/eca/llm_api.clj`: façade used by features to call an LLM; vendor adapters in `src/eca/llm_providers/` (anthropic, openai, google, ollama, copilot…).
10
+
-`src/eca/db.clj`: in-memory state (sessions, chats, MCP); `src/eca/config.clj`: config resolution from multiple sources.
11
+
-`src/eca/messenger.clj`: sends requests/notifications back to the client; `src/eca/remote/`: remote HTTP/SSE server mode.
12
+
-`src/eca/nrepl.clj`: starts an nREPL when nrepl/cider-nrepl are on the classpath (i.e. the `bb debug-cli` build; no flag needed) — port is logged to stderr, and you can eval against the live process.
- Production CLI (JVM): `bb prod-cli` | Production JAR: `bb prod-jar`
@@ -9,37 +20,41 @@ ECA Agent Guide (AGENTS.md)
9
20
- Run all unit tests: `bb test` (same as `clojure -M:test`)
10
21
- Run a single unit test namespace: `clojure -M:test --focus eca.main-test`
11
22
- Run a single unit test var: `clojure -M:test --focus eca.main-test/parse-opts-test`
12
-
- Run all integration tests (requires built `./eca` or `eca.exe`): `bb integration-test`
23
+
- Run all integration tests (requires built `./eca` or `eca.exe` at repo root): `bb integration-test`
13
24
- Run a single integration test: `bb integration-test --dev --ns integration.chat.mcp-remote-test`
25
+
-`--dev` runs the server from source via the `clojure` CLI (no binary build needed); `--list-ns` lists test namespaces; `--proxy` routes via Tinyproxy (must be installed).
26
+
- Integration tests use mock LLM/MCP servers (`integration-test/llm_mock`, `mcp_mock`) — no API keys needed.
14
27
15
28
- Lint/format:
16
29
- Lint: `clj-kondo --lint src test dev integration-test`
17
-
- Formatting not enforced; follow idiomatic Clojure (`cljfmt` optional).
30
+
- Formatting not enforced in CI; follow idiomatic Clojure. `.cljfmt.edn` defines extra indents: `task` and `future*` are `[[:inner 0]]`.
18
31
19
32
- Namespaces/imports:
20
33
- One file per `ns`; always `(set! *warn-on-reflection* true)` near top.
21
34
- Group `:require` as: Clojure stdlib, third‑party, then `eca.*`; sort within groups.
22
35
- Prefer `:as` aliases; avoid `:refer` except in tests (`clojure.test` and what you use).
23
36
24
37
- Naming/types/data:
25
-
- kebab-case for fns/vars, `eca.<area>[.<subarea>]` for namespaces.
26
-
- Use snake/camel case only when mirroring external data keys.
27
-
- Prefer immutable maps/vectors/sets; use namespaced keywords for domain data.
28
-
- Add type hints only to remove reflection where it shows up.
38
+
- Internal Clojure names and domain keys use kebab-case (`chat-id`, `tool-call-id`, `parent-chat-id`).
- Provider/MCP payloads mirror vendor specs and may use mixed conventions (`input_tokens`, `function_call`, `inputSchema`); do not “fix” these to Clojure style.
41
+
- Hook script stdin uses top-level snake_case for shell ergonomics (`hook_name`, `chat_id`, `db_cache_path`), while nested tool data may keep its original shape.
42
+
-- Add type hints only to remove reflection where it shows up.
29
43
30
44
- Errors/logging/flows:
31
45
- Use `ex-info` with data for exceptional paths; return `{:result-code ...}` maps from CLI flows.
32
-
-Never `println` for app logs; use `eca.logger/error|warn|info|debug` (stderr-based).
46
+
-**stdout is the JSON-RPC channel** — never print to stdout; use `eca.logger/error|warn|info|debug` (stderr-based) for all app logs.
33
47
- If a chat-scoped function contains any `logger/...` call, wrap the relevant body in `logger/with-chat-context`. Pass both `chat-id` and the current chat’s `parent-chat-id`.
34
48
- Consider wrapping chat-scoped functions that call downstream code known to log, or that start `future*` work whose logs should be attributed to the chat. If there is no downstream logging, `with-chat-context` is unnecessary; instead, consider whether the function should log an important chat lifecycle event.
35
49
36
50
- Tests:
37
51
- Use `clojure.test` + `nubank/matcher-combinators`; keep tests deterministic.
38
52
- Put shared test helpers under `test/eca/test_helper.clj`.
53
+
- CI runs Linux, macOS, and Windows — use `eca.test-helper/file-path` / `file-uri` for Windows-safe paths in tests.
39
54
40
55
- General:
41
-
- Use java class typing to avoid GraalVM reflection issues
42
-
-Avoid adding too many comments, only add essential or when you think is really important to mention something.
56
+
- Use concrete Java class type hints when they prevent GraalVM/reflection issues.
57
+
-If changing dependency inputs in `deps.edn` or `bb.edn`, run `nix develop --command deps-lock-update`; PR CI fails if this leaves a `deps-lock.json` diff.
43
58
- ECA's protocol specification of client <-> server lives in docs/protocol.md
44
59
- If changing ECA config structure, remember to update its docs/config.json
45
-
- When adding support to a new feature or fixing a existing github issue, add a entry to Unreleased in CHANGELOG.md if not already there as last entry, be really concise (max 180 chars), implementation details not needed, mention the issue number in the end if you know it's related to one.
60
+
- When adding support to a new feature or fixing an existing GitHub issue, add a concise Unreleased `CHANGELOG.md`entry(max 180 chars, issue number if known).
`client/editor` → `stdin JSON-RPC` → `handlers` → `features` → `llm_api` → `llm_provider` → results streamed back via `messenger`.
50
61
51
62
With this map you can usually answer:
52
63
@@ -56,11 +67,23 @@ With this map you can usually answer:
56
67
57
68
### Unit Tests
58
69
59
-
Run with `bb test` or run test via Clojure REPL. CI will run the same task.
70
+
Run with `bb test` or run tests via Clojure REPL. CI runs the same task.
71
+
72
+
To run a single namespace or test, use kaocha's focus:
73
+
74
+
```bash
75
+
clojure -M:test --focus eca.features.chat-test
76
+
```
60
77
61
78
### Integration Tests
62
79
63
-
Run with `bb integration-test`, it will use your `eca` binary project root to spawn a server process and communicate with it via JSONRPC, testing the whole eca flow like an editor.
80
+
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.
81
+
82
+
Useful flags (see `bb integration-test -h`):
83
+
84
+
-`--dev`: run the server from source via the `clojure` CLI instead of a binary.
85
+
-`--ns integration.chat.anthropic-test`: run only specific test namespaces (comma-separated); `-l` lists them.
86
+
-`--proxy`: route requests through a transient Tinyproxy to verify proxy support.
Analyze this codebase and create an AGENTS.md file containing:
2
-
1. Build/lint/test commands - especially for running a single test
3
-
2. Code style guidelines including imports, formatting, types, naming conventions, error handling, etc.
1
+
Analyze this codebase and create or update an AGENTS.md file containing the essential information an AI coding agent needs to work effectively in this repository.
4
2
5
-
The file you create will be given to agentic coding agents (such as yourself) that operate in this repository. Make it about 20 lines long.
3
+
Create or update it at the repository root. If {{workspaceRoots}} contains multiple roots, inspect them and ask which root should receive AGENTS.md before writing.
6
4
7
-
If there's already an AGENTS.md, improve it if it's located in {{workspaceRoots}}.
5
+
## Step 1: Explore the codebase
6
+
7
+
Read the actual contents of files like these (skip any that don't exist — this is not an exhaustive list):
-**Architectural constraints** — things that constrain how code should be written (e.g., "must work with GraalVM native image", "no reflection")
27
+
28
+
Do not invent missing conventions. If missing information is essential to avoid misleading instructions, ask targeted questions (via ask_user tool) before writing AGENTS.md. Otherwise omit unknown conventions rather than guessing.
29
+
30
+
## Step 2: Write AGENTS.md
31
+
32
+
Write a concise AGENTS.md. Every line must pass this test: **would removing it cause an agent to make mistakes or work less efficiently?** If not, cut it.
- Non-obvious gotchas or architectural constraints
41
+
- Concise architecture notes that are not obvious from filenames: major boundaries, request/data flow, extension points, generated-code areas, or constraints that affect how changes should be made
42
+
- Key information from existing AI tool configs — read instructions meant for other AI tools and adapt them for AGENTS.md
43
+
44
+
Exclude:
45
+
- File-by-file structure or component lists (agents can discover these by reading code)
46
+
- Standard language conventions agents already know
- Information that changes frequently — reference the source file instead
49
+
- Detailed tutorials — link to docs instead
50
+
51
+
Use short sections with bullet points, not paragraphs.
52
+
53
+
If AGENTS.md already exists in the chosen repository root, read it first. Improve it by filling gaps, removing outdated information, and tightening the language. Preserve what's already correct and useful.
0 commit comments