Guide · Agent skill

How to use the Emacs Channel for NanoClaw agent skill

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

The add-emacs skill adds Emacs as a messaging channel for NanoClaw, the personal assistant. It opens a chat buffer inside Emacs and lets you send org-mode entries or selected regions to the agent, with replies landing in your file. This guide is for people who already run NanoClaw and use Doom, Spacemacs or vanilla Emacs; by the end you will know what the skill changes, how to install it, and how to check that it works.

Emacs Channel for NanoClawnanocoai/nanoclaw · MIT Download the skill

Quick start

1Download and unzip the skill. Download the ZIP from this page and unzip it into ~/.claude/skills/ or a project's .claude/skills/ folder, or upload it under Settings, Capabilities, Skills in the Claude apps.
2Enable the channel in .env. Add EMACS_ENABLED=true and any optional EMACS_* values to your NanoClaw .env file.
3Build and test the install. Run pnpm run build, then run the registration test with vitest to confirm the channel registers.
4Wire the channel to an agent group. Run /init-first-agent to create the agent group and wire Emacs, or use the register step on an existing agent group.
5Add the Emacs config. Add the load line and keybindings for Doom, Spacemacs or vanilla Emacs, then reload Emacs.
6Restart and verify. Restart NanoClaw, curl the endpoint, and send a test message from the chat buffer with C-c C-c.

What is an agent skill, and what does this one do?

An agent skill is a folder of instructions and files that an AI agent can load to gain a specific capability. This skill, add-emacs, teaches a NanoClaw install to accept messages from Emacs through a local HTTP bridge. No bot token or external service is needed.

Ask while coding: open the chat buffer and 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 in your org file.
Meeting notes: send an org agenda entry and get a summary or action items back as a child node.
Draft writing: send org prose and receive revisions or continuations in place.
Research capture: ask a question in your org notes and the answer lands where you need it.

Install the add-emacs skill

Download the ZIP for this skill from this page and unzip it into ~/.claude/skills/ for personal use, or into a project's .claude/skills/ folder to scope it to one project. Alternatively, in the Claude apps go to Settings, then Capabilities, then Skills, and upload the ZIP there.

The skill package contains SKILL.md and REMOVE.md. SKILL.md holds the setup steps the agent follows; REMOVE.md explains how to undo them.

Requires a NanoClaw checkout with pnpm and Node, and a git remote carrying the channels branch.
Requires Emacs 27.1 or newer.
Optional: a random EMACS_AUTH_TOKEN value.

Enable the Emacs channel and set the port and token

The adapter is gated by EMACS_ENABLED so the HTTP port is not opened on hosts that are not running Emacs. Add these lines to .env in your NanoClaw project. The port and platform id are optional; the auth token is recommended but not required.

EMACS_ENABLED=true turns the channel on.
EMACS_CHANNEL_PORT defaults to 8766; change it only if that port is taken.
EMACS_AUTH_TOKEN is optional; set it to a random string to lock the endpoint.
EMACS_PLATFORM_ID defaults to default; change it only if you want a non-default chat id.

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

The source recommends an auth token even on single-user machines, because it stops other local processes from reaching the endpoint.

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

Load the Emacs client in your config

The Lisp client is emacs/nanoclaw.el in your checkout. It needs only Emacs builtins (url, json, org), so no package manager is involved. Add the load line and keybindings for your distribution, then reload.

Doom Emacs: add to ~/.config/doom/config.el (or ~/.doom.d/config.el), then run M-x doom/reload. Spacemacs: add to dotspacemacs/user-config in ~/.spacemacs, then run M-x dotspacemacs/sync-configuration-layers or restart. Vanilla Emacs: add to ~/.emacs.d/init.el, then run M-x eval-buffer or restart.

Replace the path with your actual NanoClaw checkout location. If you set an auth token, also add it to Emacs; if you changed the port, set nanoclaw-port.

Doom: map! bindings under SPC N c (chat) and SPC N o (org send).
Spacemacs: SPC a N c and SPC a N o.
Vanilla: C-c n c and C-c n o.

(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)

Verify the bridge and the Emacs buffer

Restart NanoClaw after building, then check the HTTP endpoint. The expected response with no token is an empty messages list. If you set a token, send it as a Bearer header.

In Emacs, open the chat buffer with your keybinding, type a message and press C-c C-c to send (RET inserts newlines). A response should appear within a few seconds. The log file logs/nanoclaw.log should show "Emacs channel listening" at startup.

Expected endpoint response: {"messages":[]}
Log line to look for: Emacs channel listening

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

What people use it for

Ask the agent about a function or error while staying in your editor.
Select a region of code and get a review response inserted as a child heading in an org file.
Send an org agenda entry from a meeting and get a summary or action item list back.
Continue a conversation started in another channel such than Telegram inside Emacs, when both are wired to the same agent group with agent-shared session mode.

Frequently asked questions

How do I install the add-emacs skill?

Download the ZIP from this page and unzip it into ~/.claude/skills/ for personal use or a project's .claude/skills/ folder. You can also upload the ZIP in the Claude apps under Settings, then Capabilities, then Skills.

What do I need before I can use it?

You need a NanoClaw checkout with pnpm, Node, and a git remote that carries the channels branch, plus Emacs 27.1 or newer. A random EMACS_AUTH_TOKEN is optional but recommended.

Does it need a bot token or an external service?

No. The skill describes a local HTTP bridge, so it does not need a bot token or external service. The channel runs on localhost.

Is the add-emacs skill free?

The skill is released under the MIT licence, as listed for the nanocoai/nanoclaw repository. Check the repository's licence file for the full terms.

Why does curl return nothing or an error?

Confirm EMACS_ENABLED=true is in .env, that you rebuilt and restarted NanoClaw, and that the port matches EMACS_CHANNEL_PORT (default 8766). If you set an auth token, the curl request must include the Bearer header. Check logs/nanoclaw.log for the Emacs channel listening line.

Can I use this on a shared machine?

The source describes the channel as single-user, and the local port is open whenever it is enabled. It is not a good fit for multi-user or shared machines.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Choose this skill if you already run NanoClaw and want to ask it questions or send org-mode text from inside Emacs. Skip it if you do not use NanoClaw or Emacs, or if the machine is shared, since the channel is single-user and the port stays open while enabled.

Download the skill