/add-emacs

name: add-emacs
description: Add Emacs as a channel. Opens an interactive chat buffer and org-mode integration so you can talk to NanoClaw from within Emacs (Doom, Spacemacs, or vanilla). Local HTTP bridge — no bot token or external service needed.

Add Emacs Channel

Adds Emacs support via a local HTTP bridge. Works with Doom Emacs, Spacemacs, and vanilla Emacs 27.1+.

What you can do with this

• **Ask while coding** — open the chat buffer (`C-c n c` / `SPC N c`), ask about a function or error without leaving Emacs
• **Code review** — select a region and send it with `nanoclaw-org-send`; the response appears as a child heading inline in your org file
• **Meeting notes** — send an org agenda entry; get a summary or action item list back as a child node
• **Draft writing** — send org prose; receive revisions or continuations in place
• **Research capture** — ask a question directly in your org notes; the answer lands exactly where you need it

Install

NanoClaw doesn't ship channels in trunk. This skill copies the Emacs adapter and the Lisp client in from the `channels` branch. Native HTTP bridge — no Chat SDK, no adapter package.

1. Copy the adapter and Lisp client

Fetch the `channels` branch from the configured remote that carries it, then overwrite the skill-owned files with the canonical registry copies:

src/channels/emacs.ts
src/channels/emacs.test.ts
src/channels/emacs-registration.test.ts
emacs/nanoclaw.el

2. Append the self-registration import

Append to `src/channels/index.ts` (skip if the line is already present):

import './emacs.js';

3. Build and validate

pnpm run build

pnpm exec vitest run src/channels/emacs-registration.test.ts

Both must be clean before proceeding. `emacs-registration.test.ts` is the one integration test: it imports the real channel barrel and asserts the registry contains `emacs`. It goes red if the `import './emacs.js';` line is deleted or drifts, or if the barrel fails to evaluate (so the channel genuinely would not register). The adapter uses only Node builtins (`http`), so there is no npm dependency to guard for this channel.

End-to-end message delivery from a real Emacs buffer is verified manually once the service is running — see Verify and Troubleshooting.

Enable

The adapter is gated by `EMACS_ENABLED` so the HTTP port isn't opened on hosts that aren't running Emacs. Add to `.env`:

EMACS_ENABLED=true
EMACS_CHANNEL_PORT=8766       # optional — change only if 8766 is taken
EMACS_AUTH_TOKEN=             # optional — set to a random string to lock the endpoint
EMACS_PLATFORM_ID=default     # optional — only change if you want a non-default chat id

Generate an auth token (recommended even on single-user machines — prevents other local processes from poking the endpoint):

node -e "console.log(require('crypto').randomBytes(16).toString('hex'))"

Wire the channel

Emacs is a single-user, single-chat channel. One host = one messaging group with `platform_id = "default"`.

If this is your first agent group

Run `/init-first-agent` — pick **Emacs** as the channel, use any short handle as the "user id" (e.g. your OS username), and the skill will create the agent group, wire the channel, and write a welcome message that the agent delivers back to your Emacs buffer.

Otherwise — wire to an existing agent group

Run the `register` step directly. The `EMACS_PLATFORM_ID` (default `default`) becomes the messaging group's platform id:

pnpm exec tsx setup/index.ts --step register -- \
  --platform-id "default" --name "Emacs" \
  --folder "<existing-folder>" --channel "emacs" \
  --session-mode "agent-shared" \
  --assistant-name "<existing-assistant-name>"

`agent-shared` puts Emacs messages in the same session as any other channel wired to the same agent group — so a conversation you started in Telegram continues in Emacs. Use `shared` to keep an independent Emacs thread with the same workspace, or a new `--folder` for a dedicated Emacs-only agent.

Alternatively create the rows with `ncl` — **the host service must be running** (`ncl` connects to it over a Unix socket). Engage mode/pattern and `unknown_sender_policy` default to the Emacs adapter's declared channel defaults:

ncl messaging-groups create --channel-type emacs --platform-id "default" --name "Emacs"
ncl wirings create --messaging-group-id <mg-id-from-above> --agent-group-id <ag-id> \
  --session-mode agent-shared

Configure Emacs

`nanoclaw.el` needs only Emacs 27.1+ builtins (`url`, `json`, `org`) — no package manager.

AskUserQuestion: Which Emacs distribution are you using?

• **Doom Emacs** — `config.el` with `map!` keybindings
• **Spacemacs** — `dotspacemacs/user-config` in `~/.spacemacs`
• **Vanilla Emacs / other** — `init.el` with `global-set-key`

**Doom Emacs** — add to `~/.config/doom/config.el` (or `~/.doom.d/config.el`):

;; NanoClaw — personal AI assistant channel
(load (expand-file-name "~/src/nanoclaw/emacs/nanoclaw.el"))

(map! :leader
      :prefix ("N" . "NanoClaw")
      :desc "Chat buffer"  "c" #'nanoclaw-chat
      :desc "Send org"     "o" #'nanoclaw-org-send)

Reload: `M-x doom/reload`

**Spacemacs** — add to `dotspacemacs/user-config` in `~/.spacemacs`:

;; NanoClaw — personal AI assistant channel
(load-file "~/src/nanoclaw/emacs/nanoclaw.el")

(spacemacs/set-leader-keys "aNc" #'nanoclaw-chat)
(spacemacs/set-leader-keys "aNo" #'nanoclaw-org-send)

Reload: `M-x dotspacemacs/sync-configuration-layers` or restart Emacs.

**Vanilla Emacs** — add to `~/.emacs.d/init.el`:

;; NanoClaw — personal AI assistant channel
(load-file "~/src/nanoclaw/emacs/nanoclaw.el")

(global-set-key (kbd "C-c n c") #'nanoclaw-chat)
(global-set-key (kbd "C-c n o") #'nanoclaw-org-send)

Reload: `M-x eval-buffer` or restart Emacs.

Replace `~