devkit

hermes-devkit: Scratchpad for Hermes

A Hermes plugin that gives agents one managed home for drafts: a per-session scratchpad of
named buffers, edited in place, shown in the Desktop code viewer, and cleaned up with the chat.

Why

Agents draft constantly: code snippets, HTML mocks, lesson code, notes. Without a place meant
for drafts they land as loose files, a new one per revision (page.html, page_v2.html,
page_final.html...), in Hermes' shared temp folder ~/.hermes/cache/scratch. That folder is
also where Hermes and its tools put throwaway machinery (browser profiles, downloads, CI logs,
tempfile output), it is shared by every chat, and anything in it is pruned 24 hours after its
last write, whether or not the chat is still using it.

devkit separates the two. Drafts get their own location, scoped to the chat, kept as long as the
chat exists, and visible in one Desktop tab where you can review or clear them.

How the agent uses it alongside Hermes

The plugin adds a scratchpad tool and a short rule to every turn, so the agent picks the right
place for each kind of output:

| Output | Where it goes | Lifetime |
|---|---|---|
| Drafts you look at, discuss or iterate on: code, HTML pages, lesson pads, notes | scratchpad (this plugin), plugin-data/devkit/sessions/<chat>/ | until the chat is deleted |
| Throwaway machinery nobody reads: screenshots for the agent's own checks, downloads, logs, one-off helper scripts | Hermes' own ~/.hermes/cache/scratch (unchanged) | 24 h after the last write |
| Project work, or a file you ask for | write_file, or scratchpad action=promote | permanent |

Hermes' own scratch folder keeps working exactly as before; devkit only takes drafts out of it.

If the agent doesn't use it on its own: the per-turn rule makes the scratchpad the
default, but the model decides which tool to call, and it doesn't always pick the scratchpad
first, especially early in a chat or for a one-off snippet. If it writes a loose file or pastes
the code into the chat instead, just ask it to use the scratchpad ("put that in the
scratchpad"); it then keeps using it for the rest of the chat.

A typical exchange:

1. You ask for a small program. The agent calls scratchpad action=write name=main.py and
   action=open; the draft opens in the Desktop code viewer.
2. You edit it in the viewer, or ask for a change. The agent reads the buffer and
   action=patches it in place: still one main.py, no new files.
3. When the work belongs in a project, you say so and the agent runs
   action=promote path=~/project/main.py, which writes the file through Hermes' normal
   write_file (approvals apply).
4. Delete the chat and its buffers go with it.

Tool reference

| Action | What it does |
|---|---|
| write | Create or replace a buffer (name, content) |
| patch | Replace old_text with new_text in a buffer (replace_all for every match) |
| read | Return a buffer's content |
| list | List this chat's buffers |
| open | Show a buffer in the Desktop code viewer / preview (desktop_preview) |
| delete | Remove a buffer |
| promote | Write a buffer to a real file (path, absolute or ~; overwrite to replace) via write_file |

Buffer names are plain file names (main.py, page.html); the extension sets syntax
highlighting. Each buffer is capped at 2 MB.

The Scratchpad tab (Desktop)

A tab beside Files in the right-hand zone, hidden with it. Chats with drafts are grouped the
same way as the chat sidebar (Today, Yesterday, Earlier this week, Last week, then by month),
each with its files underneath:

• Click a chat title to open that chat.
• Click a file to open it in a tab in the main workspace, with line numbers, Edit/Save
  (your edits go straight into the buffer the agent reads) and Open chat.
• × deletes a file or a chat's drafts. Chats that were deleted are listed under
  Deleted chats with a Clear action; Clear all removes every draft. Deleting drafts
  never touches the chat itself.
• The tab refreshes whenever the agent uses the scratchpad.

Cleanup

Automatic, hourly, in one Hermes process at a time (file lock), with a one-hour grace period for
new folders:

1. Deleted chats: a folder whose chat is gone from Hermes' state.db is removed. If the
   database can't be read, nothing is removed; if a read matches none of the plugin's chats while
   two or more would be removed, it is treated as a schema change and skipped.
2. Idle chats: each folder carries the plugin's own stamp (created, last_active). A folder
   idle longer than idle_days (default 90, Hermes' session auto-prune window) is removed, even
   if the database can't be read.
3. Manual: the Scratchpad tab.

Disclosures

• Adds a short placement rule (about 120 tokens) to each turn's user message.
• Reads Hermes' state.db read-only, once an hour, from a background thread.
• Deletes only its own folders under <HERMES_HOME>/plugin-data/devkit/.
• No network calls, credentials, third-party services or telemetry.

Install

hermes plugins install devkit
hermes plugins enable devkit
hermes gateway restart

Then start a new chat (a chat's tools are fixed when it is created). For the tab, enable
devkit's Desktop half under Capabilities → Plugins (Hermes ships Desktop halves off).

Settings (plugins.entries.devkit.settings in config.yaml):

| Key | Default | Meaning |
|---|---|---|
| idle_days | 90 | Remove a chat's buffers after this many idle days |

Requirements

• Hermes >= 0.22.0.
• action=open needs the Desktop window bridge on the session gateway
  (NousResearch/hermes-agent#138917).
  On v0.22.1 without it, open reports "The preview pane is only available in the Hermes
  desktop app"; every other action works.

Development

plugin/              the installable package (catalog subdir)
  plugin.yaml        manifest
  __init__.py        registration: tool, hook, hourly cleanup
  scratchpad/        store, tool, per-turn rule
  dashboard/         backend routes for the tab (/api/plugins/devkit/)
  desktop/plugin.js  the Scratchpad tab
tests/               pytest suite
docs/                screenshots

ln -s /path/to/hermes-devkit/plugin ~/.hermes/plugins/devkit
hermes plugins enable devkit
hermes plugins validate /path/to/hermes-devkit/plugin --install-deps
python -m pytest tests -q      # with the Hermes test interpreter

License

MIT

README from the reviewed commit dbfa6b2; it updates when the author re-pins.