{"id":49308746,"url":"https://github.com/cuttlefisch/mae","last_synced_at":"2026-06-27T02:02:23.301Z","repository":{"id":351654563,"uuid":"1211907605","full_name":"cuttlefisch/mae","owner":"cuttlefisch","description":"AI-native Emacs successor — Rust core, R7RS Scheme, collaborative editing, LSP/DAP, Babel, 130+ AI tools, GUI + terminal","archived":false,"fork":false,"pushed_at":"2026-06-22T15:27:31.000Z","size":25939,"stargazers_count":3,"open_issues_count":4,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-22T15:27:34.891Z","etag":null,"topics":["ai-agent","ai-editor","ai-ide","code-editor","collaborative-editing","crdt","dap","development-environment","emacs","lisp","literate-programming","lsp","modal-editing","org-mode","rust","scheme","tree-sitter","vim"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cuttlefisch.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"cuttlefisch"}},"created_at":"2026-04-15T21:47:36.000Z","updated_at":"2026-06-15T15:04:09.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/cuttlefisch/mae","commit_stats":null,"previous_names":["cuttlefisch/mae"],"tags_count":38,"template":false,"template_full_name":null,"purl":"pkg:github/cuttlefisch/mae","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cuttlefisch%2Fmae","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cuttlefisch%2Fmae/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cuttlefisch%2Fmae/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cuttlefisch%2Fmae/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cuttlefisch","download_url":"https://codeload.github.com/cuttlefisch/mae/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cuttlefisch%2Fmae/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34839005,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-27T02:00:06.362Z","response_time":126,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agent","ai-editor","ai-ide","code-editor","collaborative-editing","crdt","dap","development-environment","emacs","lisp","literate-programming","lsp","modal-editing","org-mode","rust","scheme","tree-sitter","vim"],"created_at":"2026-04-26T11:03:08.898Z","updated_at":"2026-06-27T02:02:23.293Z","avatar_url":"https://github.com/cuttlefisch.png","language":"Rust","funding_links":["https://github.com/sponsors/cuttlefisch"],"categories":[],"sub_categories":[],"readme":"# MAE — Modern AI Editor\n\n[![License: GPL-3.0-or-later](https://img.shields.io/badge/License-GPL--3.0--or--later-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)\n[![Rust](https://img.shields.io/badge/Rust-stable-orange.svg)](https://www.rust-lang.org/)\n[![Tests](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/cuttlefisch/6f6375e4dc527a9953e6898124329f4c/raw/mae-tests.json)](#)\n[![Lines of Code](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/cuttlefisch/6f6375e4dc527a9953e6898124329f4c/raw/mae-loc.json)](#)\n[![Built with AI](https://img.shields.io/badge/Built%20with-Claude%20+%20Gemini%20+%20DeepSeek-blueviolet.svg)](https://github.com/cuttlefisch/mae)\n\nAn AI-native lisp machine IDE — a programmable development environment where the\nhuman and the AI are peer actors calling the same Scheme primitives. Built on a\nRust core with an embedded R7RS-small runtime. GUI + terminal.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/mae-screenshot.png\" alt=\"MAE dashboard screenshot\" width=\"700\"\u003e\n\u003c/p\u003e\n\n## Features\n\n- **AI as peer actor** — 450+ editor commands exposed as AI tools. The AI calls\n  the same `dispatch_builtin()` as your keybindings. No shadow API, no simulated\n  keystrokes.\n- **Collaborative editing** — CRDT sync engine (yrs/YATA) with daemon,\n  WAL persistence, per-user undo, awareness protocol, PSK authentication, and\n  mDNS peer discovery. Collaborative KB sharing enables real-time knowledge base\n  sync across instances with offline edit + reconnect support.\n- **Org-mode babel** — Execute code blocks in 12 languages, noweb expansion,\n  `:tangle` directive, `:var` cross-references, safety policies. Export to\n  HTML and Markdown with TOC, syntax highlighting, tag filtering.\n- **Runtime redefinability** — Embedded R7RS Scheme (mae-scheme). Redefine any\n  function while running. 45+ primitives, 18 hook points, `init.scm` is a\n  real program.\n- **Full vi modal editing** — Motions, operators, text objects, count prefix,\n  dot repeat, macros, registers, marks, surround, visual block mode, multi-cursor.\n- **LSP first-class** — Go-to-definition, references, hover, completion, rename,\n  format, symbol outline, breadcrumbs, peek references. AI gets structured\n  semantic data.\n- **DAP first-class** — Multi-language debugging (Python, Rust, C/C++).\n  Breakpoints (conditional, logpoint), watch expressions, exception breakpoints.\n  AI can set breakpoints and inspect variables.\n- **Multi-provider AI** — Claude, OpenAI, Gemini, and DeepSeek. Provider-aware\n  prompt tuning. Tiered prompt system (Full/Compact) with per-model guardrails.\n- **Graph knowledge base** — CozoDB (Datalog) primary backend with SQLite fallback.\n  400+ typed nodes, 20 relationship types, agenda queries, node versioning, meta-node\n  composition, block-level addressing, HNSW vector index (GraphRAG-ready). Federated\n  instances, org-mode parser. Same docs the AI reads.\n- **Tree-sitter** — 13 languages with structural parse trees. AI can query\n  syntax trees for code reasoning.\n- **GUI + Terminal** — winit + Skia 2D hardware-accelerated GUI, ratatui\n  terminal fallback. Inline images (PNG/JPG/SVG), variable-height rendering,\n  inertial scrolling. Desktop launcher for freedesktop environments.\n- **Embedded terminal** — Full VT100/VT500 via `alacritty_terminal`. AI can\n  observe output and send input. `Ctrl-\\ Ctrl-n` exits to normal mode.\n\n## Architecture\n\n```\n   Human (keys)      Scheme (eval)      AI / MCP (tool call)\n        │                  │                     │\n        ▼                  ▼                     ▼\n   ┌───────────┐    ┌─────────────┐    ┌────────────────────┐\n   │ Keymap    │    │ (run-cmd)   │    │  Tool wrappers     │\n   │ Lookup    │    │ (define-    │    │  → same functions  │\n   │           │    │  command)   │    │  as keybindings    │\n   └─────┬─────┘    └──────┬──────┘    └─────────┬──────────┘\n         │                 │                     │\n         └────────────┬────┴─────────────────────┘\n                      ▼\n         ┌───────────────────────────┐\n         │     Editor Core API       │\n         │  dispatch_builtin()       │\n         │  buffer.insert/delete()   │\n         │  lsp/dap/kb/shell ops     │\n         │                           │\n         │  450+ commands · same     │\n         │  functions for all actors │\n         └─────────────┬─────────────┘\n                       ▼\n         ┌───────────────────────────┐\n         │      Editor State         │\n         │  Buffers · LSP · DAP      │\n         │  Shell · KB · Themes      │\n         └───────────────────────────┘\n```\n\nAll three actors converge on the same Editor Core API. The AI's tools are thin\nwrappers — `buffer_read` calls the same `buffer.line()` the renderer uses;\n`lsp_definition` queues the same intent as pressing `gd`. When a package author\nwrites `(define my/summarize ...)`, it's immediately available to both the\nuser's keybinding and the AI's tool palette.\n\n### Crate Layout\n\n```\nmae (binary)\n ├── mae-core        Buffer (rope), editor state, commands, keymap, syntax\n ├── mae-renderer    Terminal rendering (ratatui), status bar, popups, shell viewport\n ├── mae-gui         GUI rendering (winit + Skia 2D), mouse input, font config, inline images\n ├── mae-scheme      R7RS-small Scheme runtime, init.scm loading, hook dispatch\n ├── mae-ai          Claude + OpenAI + Gemini + DeepSeek providers, tool execution, conversation\n ├── mae-lsp         LSP client — connection, navigation, diagnostics, completion, formatting\n ├── mae-dap         DAP client — protocol types, transport, breakpoints, stepping, watches\n ├── mae-shell       Terminal emulator (alacritty_terminal), PTY management\n ├── mae-kb          Knowledge base — CozoDB graph store, typed relationships, org parser, federation\n ├── mae-mcp         MCP server — Unix socket, JSON-RPC, stdio shim\n ├── mae-sync        Collaborative sync — yrs CRDT, ropey bridge, encoding helpers\n ├── mae-daemon        Background daemon — KB persistence, collab sync, WAL persistence\n ├── mae-babel       Org-babel executor — 12 languages, persistent sessions, language backends\n ├── mae-export      Org/Markdown export — HTML, Markdown, TOC, syntax highlighting\n ├── mae-canvas      Visual buffer (diagrams, drawings)\n ├── mae-snippets    YASnippet-style templates — tab-stops, mirrors, transforms\n ├── mae-format      Formatter bridge — prettier, black, rustfmt (complements LSP format)\n ├── mae-make        Build runner — Makefile/Cargo.toml/package.json detection\n ├── mae-lookup      Unified lookup — LSP def + docs URL + man pages\n └── mae-spell       Spellcheck — hunspell/aspell integration, inline markers\n```\n\n## Getting Started\n\n### Prerequisites\n\n- **Rust stable** (1.95+) via [rustup](https://rustup.rs)\n- **GUI deps:** `clang`, `fontconfig-devel`, `freetype-devel` (Fedora) / `clang`, `libclang-dev`, `libfontconfig1-dev`, `libfreetype6-dev` (Debian/Ubuntu) / Xcode CLI Tools (macOS)\n- **TUI-only:** `make build-tui` — no clang or GUI deps needed\n- **Optional:** `make setup-dev` installs `clang`, `lldb`, `rust-analyzer`, `debugpy` for full self-test coverage\n- **Check deps:** `make doctor` — reports all prerequisites with install commands\n\n### Build \u0026 Run\n\n```sh\ngit clone git@github.com:cuttlefisch/mae.git \u0026\u0026 cd mae\nmake doctor                     # check prerequisites\nmake build                      # GUI build (default)\nmake install                    # install to ~/.local/bin + desktop launcher\nmae --init-config               # generate init.scm (+ config.toml bootstrap) + wizard\nmae file.rs                     # GUI by default; falls back to terminal over SSH/tty/headless\nmae --no-gui file.rs            # force terminal mode (also --tui / -nw)\nmae --gui file.rs               # force the GUI backend\nmake build-tui                  # terminal-only (no clang/skia dependency)\n```\n\n**macOS:** `make install PREFIX=/usr/local/bin` or add `~/.local/bin` to PATH.\n**WSL:** `make install-tui` (terminal-only, no X11 needed).\n\n### Container Build\n\nNo Rust installation needed — everything runs inside Docker:\n\n```sh\ngit clone git@github.com:cuttlefisch/mae.git \u0026\u0026 cd mae\nmake docker-ci          # full CI pipeline (fmt + clippy + check + test)\nmake docker-new-user    # validate first-run experience in clean environment\nmake docker-dev         # interactive dev shell with Rust toolchain\n```\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for the full container development workflow.\n\n### AI Setup\n\n\u003e [!CAUTION]\n\u003e **MAE is in early Alpha.** AI features and cost guardrails are experimental.\n\u003e Always monitor your API usage and costs directly in your provider dashboards.\n\nThe simplest way to enable AI is to export an API key. MAE auto-detects the\nprovider:\n\n```sh\nexport ANTHROPIC_API_KEY=sk-ant-...    # Claude (default) — https://console.anthropic.com/settings/keys\nexport OPENAI_API_KEY=sk-...           # OpenAI          — https://platform.openai.com/api-keys\nexport GEMINI_API_KEY=...              # Gemini           — https://aistudio.google.com/apikey\nexport DEEPSEEK_API_KEY=...            # DeepSeek         — https://platform.deepseek.com/api_keys\n```\n\nTo persist the startup AI bootstrap (provider/model/credentials only — read before\nthe Scheme runtime starts), add it to `~/.config/mae/config.toml`:\n\n```toml\n[ai]\nprovider = \"claude\"                    # claude | openai | gemini | deepseek | ollama\nmodel = \"claude-sonnet-4-20250514\"     # any supported model name\n# api_key_command = \"pass show mae/anthropic\"  # password manager integration\n# auto_approve_tier = \"shell\"          # readonly | write | shell (default) | privileged\n# editor = \"claude\"                    # CLI command for SPC a a (AI agent shell)\n```\n\nAll other AI behavior is configured in `init.scm` (see [Configuration](#configuration)),\nnot config.toml. Provider-aware prompt tuning is automatic — Gemini gets explicit\nJSON examples, DeepSeek gets anti-looping guardrails.\n\n### First 10 Minutes\n\nA guided path for a brand-new user — copy-paste in order:\n\n1. **Generate config** — `mae --init-config` (runs a short wizard; safe defaults).\n2. **Open and edit** — `mae README.md`, press `i` to insert, type, `Esc`, then `:w` to save.\n3. **Make your first AI call** — `export ANTHROPIC_API_KEY=sk-ant-...`, relaunch, press\n   `SPC a p`, and ask *\"explain the function under my cursor.\"*\n4. **Find your way around** — `SPC SPC` opens the command palette (fuzzy-search every\n   command); every leader key shows a which-key menu, so just press `SPC` and read.\n5. **Learn interactively** — `:tutor` for the 13-lesson tutorial, or `SPC h h` for the\n   help knowledge base.\n6. **(Optional) Share a KB** — start a daemon (`mae-daemon`), then `SPC C K m` opens the\n   `*KB Sharing*` management buffer. See [docs/COLLABORATION.md](docs/COLLABORATION.md).\n\nIf anything in this list doesn't work as written, that's a bug — please file it.\n\n### First Steps (key reference)\n\n1. `:tutor` — interactive tutorial (13 lessons: vim, beginner, AI tracks)\n2. `SPC SPC` — command palette (fuzzy search all commands)\n3. `SPC f f` — find file in project\n4. `SPC h h` — help index (knowledge base)\n5. `SPC a a` — launch AI agent in embedded shell\n6. `SPC a p` — start an AI conversation\n7. `:self-test` — verify AI integration\n\n### Drive MAE with Your Coding Agent\n\nMAE's core thesis is that the AI is a *peer actor*, not a plugin — your external\ncoding agent (Claude Code, etc.) can drive the editor through the **same** tools the\nbuilt-in agent uses, over MCP. A running MAE exposes 135+ tools on a per-process Unix\nsocket; the `mae-mcp-shim` binary bridges MCP-over-stdio to that socket:\n\n```sh\n# Point your agent's MCP config at the shim; it auto-discovers /tmp/mae-{PID}.sock\nmae-mcp-shim\n```\n\nDay-one tools worth knowing: `introspect` (editor state snapshot), `execute_command`\n(run any command), `kb_search` / `lsp_definition` (navigate code semantically), and\n`kb_sharing_status` (introspect shared-KB membership/roles before managing). The full\ntool catalog and selection guidance live in\n[CLAUDE.md](CLAUDE.md#developing-mae-inside-mae-mcp-tools).\n\n### Configuration\n\n`init.scm` is MAE's **primary configuration surface** — options\n(`(set-option!)` / `:set` / `:set-save`), keybindings, module selection\n(`(mae!)`), and hooks live here, and `:set-save` writes here. `config.toml` is a\nnarrow **legacy bootstrap** read at startup *before* the Scheme runtime; it is\nbeing retired — prefer init.scm for new settings:\n\n| File | Role | Format |\n|------|------|--------|\n| `~/.config/mae/init.scm` | **Primary.** Modules, keybindings, options, hooks, packages, custom commands | Scheme (programmatic, live-reloadable) |\n| `~/.config/mae/config.toml` | *Legacy bootstrap* (being retired): AI provider/model, theme/font, LSP server paths, performance, daemon/collab connection — parsed before the Scheme runtime | TOML (static, declarative) |\n| `.mae/init.scm` (per-project) | Project-local overrides, loaded after user config | Scheme |\n\n**`init.scm` is the primary user config.** It's a real Scheme program, not a\nsettings file:\n\n```scheme\n;; Module selection — declare which modules to load\n(mae!\n  :editor \"keymap-doom\" \"surround\" \"search\" \"registers\" \"macros\"\n  :ui     \"dashboard\" \"file-tree\")\n\n;; Third-party packages — install with `mae sync`\n(package! \"splash-themes\" :source \"github:cuttlefisch/mae-splash-themes\")\n\n;; Editor options (91+ registered, all Scheme-accessible)\n(set-option! \"theme\" \"gruvbox-dark\")\n(set-option! \"relative-line-numbers\" \"true\")\n(set-option! \"font-size\" \"14\")\n\n;; Custom keybindings\n(define-key \"normal\" \"SPC t t\" \"cycle-theme\")\n\n;; Hooks\n(add-hook! \"before-save\" \"lsp-format\")\n```\n\n**`config.toml` is the legacy startup bootstrap** for provider/credential\nplumbing that doesn't belong in version-controlled Scheme — and never in\nplaintext config.toml either; use `api_key_command`. It is being retired; prefer\ninit.scm for new settings. `mae --init-config` generates both files with a\nguided wizard.\n\nUseful commands:\n- `mae --init-config` — generate config.toml + init.scm + wizard\n- `mae --check-config` — validate config + init.scm without launching (CI-friendly)\n- `mae --clean` / `mae -q` — pristine launch, skip all config/init/history (like `emacs -q`)\n- `:edit-config` — edit `init.scm` from inside the editor\n- `:edit-settings` — edit `config.toml` from inside the editor\n- `:describe-configuration` — health report (AI, LSP, DAP status)\n\n## Module System\n\nMAE uses a Doom Emacs-inspired module system. Each module is a directory with\n`module.toml` (metadata), `autoloads.scm` (keybindings), and optionally `init.scm`\n(user config). Modules are loaded at startup and can be live-reloaded.\n\n```sh\nmae pkg list            # list installed modules with status\nmae pkg info surround   # show module details and dependencies\nmae pkg doctor          # health check all modules\nmae pkg sync            # synchronize module state\nmae pkg create mymod    # scaffold a new module from template\n```\n\n**25 built-in modules** by category:\n\n| Category | Modules |\n|----------|---------|\n| Keymap | `keymap-doom`, `keymap-leader`, `keymap-nonmodal` |\n| UI | `dashboard`, `file-tree`, `notifications` |\n| Editor | `surround`, `marks-jumps`, `search`, `registers`, `macros`, `multicursor`, `tables` |\n| Tools | `snippets`, `format`, `make`, `lookup`, `spell`, `debug` |\n| Markup | `org`, `markdown`, `agenda`, `dailies` |\n| Collab | `git-status`, `kb-sharing` |\n\nEnable modules with `+flag` syntax in `init.scm`. See [Extension Guide](docs/EXTENSION_GUIDE.md)\nfor authoring custom modules.\n\n## Vim-Level Editing\n\nFull vi modal editing with 450+ commands:\n\n| Category | Features |\n|----------|----------|\n| Modes | Normal, Insert, Visual (char/line/block), Command, Search, ShellInsert |\n| Motions | hjkl, w/b/e/W/B/E, f/F/t/T, %, {/}, 0/$, gg/G, H/M/L, ge/gE |\n| Operators | d, c, y — compose with any motion or text object |\n| Text objects | `iw`, `aw`, `i(`, `a{`, `i\"`, `it` (tag), and more |\n| Count prefix | 5j, 3dd, 2dw |\n| Dot repeat | Full `.` repeat for change/delete/insert sequences |\n| Registers | Named (`\"a`–`\"z`), numbered (`\"0`–`\"9`), system clipboard (`\"+`) |\n| Macros | `qa` record, `q` stop, `@a` play, `@@` repeat |\n| Marks | `ma` set, `'a` jump, `` `a `` exact position |\n| Search | `/pattern`, `?pattern`, `n`/`N`, `*`, `:s///g`, `:%s` |\n| Surround | `ys{motion}{char}`, `cs{old}{new}`, `ds{char}` (vim-surround) |\n| Multi-cursor | `Ctrl-d` add next match, `Ctrl-Alt-d` add all, `mc-align` |\n| Scroll | Ctrl-U/D/F/B, zz/zt/zb, inertial (kinetic) scrolling in GUI |\n| Leader | `SPC` leader system (Doom Emacs style) with which-key popup |\n| Code folding | `za` toggle, `zM` close all, `zR` open all (tree-sitter ranges) |\n| File tree | `SPC f t` sidebar with expand/collapse, git markers |\n| Git status | `SPC g s` Magit-style: stage/unstage/discard at hunk level |\n| Swap files | Crash recovery via non-destructive swap files |\n\n### Key Bindings\n\n| Key | Mode | Action |\n|-----|------|--------|\n| `i`, `a`, `A`, `o`, `O` | Normal | Enter insert mode |\n| `Esc` | Any | Return to normal mode |\n| `v` / `V` | Normal | Visual char / line selection |\n| `d`, `c`, `y` | Normal/Visual | Delete, change, yank |\n| `.` | Normal | Repeat last edit |\n| `/`, `?` | Normal | Search forward / backward |\n| `:` | Normal | Command mode |\n| `gd` | Normal | Go to definition (LSP) |\n| `gr` | Normal | Find references (LSP) |\n| `K` | Normal | Hover docs (LSP) |\n| `SPC SPC` | Normal | Command palette |\n| `SPC f f` | Normal | Fuzzy file picker |\n| `SPC a a` | Normal | AI agent (shell) |\n| `SPC a p` | Normal | AI conversation |\n| `SPC o t` | Normal | Open terminal |\n| `SPC d b` | Normal | Toggle breakpoint |\n| `SPC h h` | Normal | Help index |\n| `Ctrl-\\ Ctrl-n` | ShellInsert | Exit terminal → Normal |\n\n### Ex Commands\n\n```\n:w              Save\n:e path         Open file\n:q              Quit\n:wq             Save and quit\n:s/old/new/g    Substitute (current line)\n:%s/old/new/g   Substitute (whole buffer)\n:theme name     Switch theme\n:eval (expr)    Evaluate Scheme\n:help topic     Open help\n:terminal       Open terminal\n:tutor          Interactive tutorial\n:self-test      AI integration test\n:set opt=val    Set editor option\n:split / :vsplit  Window splitting\n:diagnostics    Show LSP diagnostics\n:messages       View message log\n:describe-configuration  Show config health report\n```\n\n## Stack\n\n| Layer | Technology | Why |\n|-------|-----------|-----|\n| Core | Rust | Eliminates GC problem, ownership model for concurrency |\n| Extensions | Scheme R7RS-small (mae-scheme) | Runtime redefinability, hygienic macros, tail calls |\n| Terminal UI | ratatui + crossterm | Platform-specific code in the library, not us |\n| GUI | winit + skia-safe | Hardware-accelerated 2D, mouse, fonts, inline images |\n| Terminal emulator | alacritty_terminal | Full VT100/VT500, same engine as Alacritty |\n| AI | Claude / OpenAI / Gemini / DeepSeek | Tool-calling maps 1:1 to command API |\n| Protocols | LSP + DAP | First-class — exposed to Scheme and AI |\n| Knowledge base | CozoDB (Datalog) + SQLite | Graph store, typed relationships, versioning, HNSW vector index |\n| Syntax | tree-sitter | 13 languages, structural parse trees |\n| Literate programming | Org-babel | 12 execution languages, tangle, noweb, export |\n\n## Roadmap\n\nSee [ROADMAP.md](ROADMAP.md) for detailed milestone tracking.\n\n| Phase | Status | Summary |\n|-------|--------|---------|\n| 1. Core + Renderer | ✅ Complete | Buffer (rope), event loop, terminal renderer, modal editing |\n| 2. Scheme Runtime | ✅ Complete | R7RS-small (mae-scheme), config loading, `define-key`, REPL |\n| 3. AI Integration | ✅ Complete | Multi-provider tool-calling, conversation, permissions |\n| 4. LSP + DAP + Syntax | ✅ Complete | Full LSP client, DAP client, 13-language tree-sitter |\n| 5. Knowledge Base | ✅ Complete | CozoDB graph, org parser, typed relationships, versioning, federation |\n| 6. Embedded Shell | ✅ Complete | alacritty_terminal, MCP bridge, file auto-reload |\n| 7. Documentation | ✅ Complete | Tutor (13 lessons), `:describe-configuration`, `--check-config` |\n| 8. GUI Backend | ✅ Complete | winit + Skia, inline images, variable-height, inertial scroll |\n| 9. Babel + Export | ✅ Complete | 12-language executor, HTML/Markdown export, KB federation |\n| 10. AI Agent Efficiency | ✅ Complete | Tiered prompts, provider-aware hints, target dispatch, frame profiling |\n| 11. Module System | ✅ Complete | 19 modules (Doom model), `mae pkg` CLI, flags, live reload |\n| 12. Collaborative Editing | ✅ Complete | CRDT daemon sync, multi-peer sync, WAL persistence, awareness, per-user undo, PSK auth, KB sharing E2E |\n| 13. Scheme Runtime | ✅ Complete | mae-scheme R7RS-small VM, Steel fully removed, 2,200+ Scheme tests |\n| 14. Graph KB | ✅ Complete | CozoDB default, 20 typed rel types, agenda queries, versioning, HNSW index, views |\n| **Next** | 🔧 In progress | AI hygiene, task management, live GraphRAG, GUI views. See [ROADMAP.md](ROADMAP.md) |\n\n## Design Lineage\n\nMAE is informed by analysis of [35 years of Emacs git\nhistory](https://github.com/emacs-mirror/emacs) — identifying the structural\ndecisions that led to its current maintenance burden:\n\n- **GC retrofit is intractable** — 23,901 commits across 3 branches, still\n  unmerged. MAE uses Rust ownership (no GC needed).\n- **`xdisp.c` is 38,605 lines** — monolithic display engine. MAE uses a\n  `Renderer` trait with separate terminal and GUI backends.\n- **Fix ratio doubled** — from 15% to 32% over 35 years. Rust's type system\n  structurally prevents this.\n- **Bus factor of ~4** — top 5 contributors = 50.8% of commits. MAE enforces\n  module boundaries across 20 crates.\n\n## Self-Hosting\n\nMAE is used to develop itself. The AI agent runs in an embedded shell, calling\nthe same tools the human uses. The GUI is the primary development target.\n\n## Model Compatibility\n\nMAE supports 33+ model prefixes across 8 providers. Run `:model-exam` to\nvalidate any model's tool-calling capabilities with a deterministic 12-test\nexam (6 categories: navigation, editing, search, tool selection, knowledge base, diagnostics). See [MODEL_SUPPORT.md](docs/MODEL_SUPPORT.md) for the full compatibility\nmatrix and exam instructions.\n\n## Data Directories\n\nMAE follows the [XDG Base Directory Specification](https://specifications.freedesktop.org/basedir-spec/latest/):\n\n| Path | Contents |\n|------|----------|\n| `~/.config/mae/` | `config.toml`, `init.scm`, `help/*.org`, `packages/` |\n| `~/.local/share/mae/` | `swap/`, `transcripts/`, `exam-results/` |\n| `~/.local/share/mae/kb/` | `local/{slug}/primary.cozo` (CozoDB graph stores) |\n| `~/.local/state/mae/` | `logs/`, `history.scm` |\n| `.mae/` (per-project) | `session.json`, `conversation.json`, `memory/`, `plans/` |\n\n## Contributing\n\nFeature branches + PR workflow. See [CONTRIBUTING.md](CONTRIBUTING.md) for the\nfull guide. Report bugs at [github.com/cuttlefisch/mae/issues](https://github.com/cuttlefisch/mae/issues).\nCheck [Known Bugs](ROADMAP.md#known-bugs) before filing.\n\n```bash\nmake doctor      # Check build prerequisites\nmake ci          # Full CI pipeline locally (no GUI)\nmake verify      # check + test + GUI check with summary\nmake self-test   # AI-driven end-to-end self-test (headless)\n```\n\nFor end-to-end workflow documentation, see [docs/USER_STORIES.md](docs/USER_STORIES.md).\nFor feature parity goals, see [docs/COMPETITIVE_ANALYSIS.md](docs/COMPETITIVE_ANALYSIS.md).\nSee [CLAUDE.md](CLAUDE.md) for architecture principles and development guide.\n\n## License\n\nGPL-3.0-or-later — see [LICENSE](LICENSE) for details.\n\nContributions are owned by their authors. No copyright assignment required.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcuttlefisch%2Fmae","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcuttlefisch%2Fmae","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcuttlefisch%2Fmae/lists"}