EmallCode

A terminal-native AI coding agent written in Go.

EmallCode is a single-binary CLI/TUI that drives Anthropic-style models (Claude, or any compatible endpoint such as a local MLX server) to read, write, and edit code with full tool-use, sub-agents, MCP integration, LSP-driven self-correction, and configurable hooks.

中文版见下方 / Chinese version below

---

Features at a glance

• Tools out of the box: Bash (with AST validation), Read / Write / Edit (with mtime safety), Glob, Grep, Agent (sub-agent dispatch), WebFetch, WebSearch.
• Permission gate: ask / allow / deny per call, persisted rules, modal in TUI.
• MCP client: speak to any stdio MCP server (@modelcontextprotocol/server-filesystem, GitHub, Notion, …) and expose their tools to the model as mcp__<server>__<tool>.
• LSP integration: configure gopls (or any language server); after Edit/Write the diagnostics are automatically attached to the tool result so the model can self-correct compile errors.
• Hooks: shell scripts triggered before/after tool use, or at turn end (PreToolUse / PostToolUse / Stop) — auto-format, run tests, feed the output back to the model on failure.
• Sub-agents: Agent tool spawns a focused sub-agent with its own context, tool whitelist, and even its own (cheaper) model — main context stays clean.
• Custom slash commands: drop a markdown file into ~/.emall/commands/ and it becomes /<filename> with optional $ARGUMENTS substitution.
• Persistent sessions: every conversation saved as JSONL, --continue / --resume <id> to pick up where you left off, /compact to summarize and shrink the context.
• Multi-model routing: main conversation, /compact, sub-agents can each use a different model (mix sonnet/haiku for cost savings).
• /cost: per-model token + cost breakdown for the current session.
• TUI polish: streaming markdown render, collapsing tool panels, scroll percentage indicator, real-time token/cost display.

---

Install

Build from source (recommended)

git clone https://github.com/emallcode/emall.git
cd emall
make build       # → bin/emall
make install     # → $GOPATH/bin/emall

Requires Go 1.22+.

Quick check

emall --version

---

Quickstart (5 minutes)

1. Initialize a project:

   cd your-project
   emall --init
   

   This creates .emall/settings.local.json, EMALL.md, and .emall/.gitignore.

2. Set your credentials: edit .emall/settings.local.json:

   {
     "apiKey": "sk-ant-...",
     "model": "claude-sonnet-4-5",
   
     // Optional: route compact + agent to a cheaper model
     "models": {
       "compact": "claude-haiku-4-5",
       "agent":   "claude-haiku-4-5"
     }
   }
   

   For a local MLX endpoint:

   {
     "apiKey": "local",
     "baseURL": "http://localhost:9000",
     "model": "your-local-model"
   }
   

3. (Optional) Describe your project in EMALL.md — it is auto-loaded into the assistant's system prompt at session start.

4. Start chatting:

   emall
   

   Tap Enter to send. Tools that need permission pop a modal — y accepts once, A accepts and remembers (writes a rule into .emall/settings.local.json).

---

Configuration layers

Settings are merged in this order (later layers override earlier ones):

1. defaults
2. ~/.emall/settings.json          user, shared
3. ~/.emall/settings.local.json    user, secrets (gitignore)
4. ./.emall/settings.json          project, shared (commit)
5. ./.emall/settings.local.json    project, secrets (gitignore)
6. EMALL_*  environment variables  (override anything for one run)

Inspect the merged result:

emall --config-show

Full field reference: see docs/configuration.md.

---

Built-in slash commands

Command	Effect
/help	List all commands (built-in + custom)
/compact [hint]	Summarize the conversation, replace history with a single user message containing the summary
/clear	Clear the screen history (JSONL on disk untouched)
/cost	Show per-model token + cost breakdown

Custom commands: drop a markdown file into ~/.emall/commands/ or ./.emall/commands/. The filename (lowercased, without .md) becomes the command name. See docs/configuration.md.

---

Diagnostic flags

emall --version            # version string
emall --help               # this list
emall --init               # write project template (.emall/ + EMALL.md)
emall --config-show        # merged settings + per-layer source
emall --sessions           # list session JSONL files for cwd
emall --continue           # resume the most recent session in cwd
emall --resume <id>        # resume a specific session
emall --mcp-status         # spawn configured MCP servers and print readiness

---

Make targets

make build       # bin/emall
make install     # $GOPATH/bin/emall
make test        # all tests
make test-race   # with -race
make test-cover  # coverage summary
make vet
make fmt
make tidy
make clean

---

Testing

make test-race

Runs ~270 tests across all packages with the race detector. Some tests (MCP, LSP, fetch) spawn helper subprocesses or hit the network — see their _test.go files for skip conditions.

---

Contributing

This is currently a personal project but issues / PRs are welcome. Conventions:

• gofmt + goimports on save
• make test-race must pass before merging
• New features: include tests in the corresponding _test.go

---

License

(TBD — pick a license before publishing.)

---

中文版

EmallCode 是一个用 Go 写的终端编码代理，单二进制部署，目标是让 LLM （Claude 或任意兼容端点，比如本地 MLX 服务）能在你的项目里读写代码、 调工具、派子代理、用 MCP 工具，并通过 LSP / Hooks 自动完成"改完代码 → 跑测试 → 失败后自我修复"的闭环。

核心能力

• 内置工具：Bash（含 AST 校验）、Read / Write / Edit（mtime 防踩踏）、 Glob、Grep、Agent（派子代理）、WebFetch、WebSearch
• 权限闸门：每次调用 ask / allow / deny；用户可让规则永久记忆
• MCP 客户端：接任何 stdio MCP server，工具自动以 mcp__<server>__<tool> 注册给模型
• LSP 集成：配置 gopls/tsserver，Edit/Write 后 diagnostics 自动 附在 tool_result 末尾，模型看到错误就自我修复
• Hooks：PreToolUse / PostToolUse / Stop 三种钩子，自动格式化、 跑测试，失败时把输出回灌让模型继续修
• 子代理：Agent 工具让主代理派出独立上下文 + 独立工具白名单 + 独立模型的子代理处理调研类任务
• 自定义 slash 命令：往 ~/.emall/commands/ 丢 markdown 文件即可
• 会话持久化：JSONL 写盘 + --continue / --resume <id> 接续， /compact 摘要压缩
• 多模型路由：主对话 / compact / 子代理可分别用不同模型省钱
• /cost：按模型分桶展示 token 和成本

5 分钟上手

git clone https://github.com/emallcode/emall.git
cd emall
make build && make install

cd your-project
emall --init
# 编辑 .emall/settings.local.json 填 apiKey / model
emall

详细文档

• docs/configuration.md — 完整配置参考
• docs/ 目录 — 架构 / 设计 / 流程图

测试

make test-race

Hello