add-emacs skill

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 EMACSPLATFORMID (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 unknownsenderpolicy 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 ~/src/nanoclaw/emacs/nanoclaw.el with your actual NanoClaw checkout path.

If EMACSAUTHTOKEN is set, also add (any distribution):

(setq nanoclaw-auth-token "<your-token>")

If you changed EMACSCHANNELPORT from the default:

(setq nanoclaw-port <your-port>)

Restart NanoClaw

Run from your NanoClaw project root:

pnpm run build
source setup/lib/install-slug.sh
launchctl kickstart -k gui/$(id -u)/$(launchd_label)   # macOS
# systemctl --user restart $(systemd_unit)             # Linux

Verify

HTTP endpoint

curl -s http://localhost:8766/api/messages?since=0

Expected: {"messages":[]}. With an auth token:

curl -s -H "Authorization: Bearer <token>" http://localhost:8766/api/messages?since=0

From Emacs

Tell the user: