bkashjee/hermes-bot-forge/bot-forge

Bot Forge

Choose the smallest sufficient setup before provisioning. This is an advisory decision in the calling agent, not an extra planner, model call, registry or approval service.

Before creating a profile

Call list_agents and inspect relevant existing skills/routines through the installed Hermes surfaces. Inspect only what the request needs, not the whole machine. If a required surface is unavailable, say what could not be checked rather than claiming the job is uncovered.

A different specialty or name is not enough. Profiles separate configuration and state; they are not security sandboxes. Explain the chosen shape briefly. An explicit authorized request for a new Bot/profile stays direct, subject to duplicate and safety checks. Ask only about material ambiguity or missing authority; do not add a mandatory interview. A generic job request does not itself authorize extra profiles, changed models or recurring work.

Hard rules

• One coherent responsibility per new Bot. Do not turn every subtask into a permanent profile.
• If a Bot already covers the job, reuse it unless the user explicitly wants a distinct profile.
• Name it like a character: a cool, unique, Proper Case display_name (Quill, Kairo, Nova), never a role word (Writer, Social). If the tool says the name is taken, pick one of its suggestions.
• Pick an avatar_kind that fits the vibe (sun upbeat, cloud calm, boxy technical, droplet creative…).
• Write the SOUL.md yourself, specific to the job. No filler.
• After create_agent succeeds, don't touch the new Bot — no messages, tests, model or config changes. Just report.

Role defaults

Every Bot always gets file web browser plus the basics. Add only what the job needs. The routines below are examples, not permission to schedule them:

SOUL.md template

# <Name> — <Role>
 
You are **<Name>**, the <Role> of this Hermes deployment. Always introduce yourself as <Name>.
 
## Your one job
<2-3 lines: the job and what "done" looks like>
 
## How you work
-<4-6 concrete habits for this job>
-verify before claiming; say plainly when unsure.
 
## Voice
<3-6 words>
 
## Never
-<3-5 job-specific anti-jobs, e.g. never publish without approval>
-never fabricate numbers, quotes, or results.
 
## Escalate to
-<the Bot or person that makes final calls>

After create_agent

• ok: false → read error, fix the input (taken name, bad cron…), call once more. Still failing → one-line error to the user.
• ok: true → reply short:

🧪 <display_name> was created. Check the readiness below.
job: <one_job>
brain: <model>   tools: <toolsets>
routines: <routines or none>
intro: <first line of intro, or not yet available>
gateway: <gateway>

• If warning is set, include it. ok: true means the profile was created, not that

sign-in, gateway serving or real work has been verified. Never call a pending Bot fully ready.

Managing Bots the user already has

• "make X funnier" / "give X the browser" / "rename X" / "X should never post without asking" → update_agent. Send only what changes; prefer soul_append over rewriting soul_md.
• "another one like X" → copy_agent, then update_agent to specialise it.
• "share X" / "send X to someone" / "give me a link for X" → share_agent. Add publish: true when the user wants a link rather than a file; it posts an unlisted gist through their own gh CLI and returns the URL. Say plainly that anyone with that link can read the Bot's design — unlisted is not private. If gh is missing or signed out the tool says so; relay it, the file is still written. "back X up" → share_agent with mode: backup, and tell the user it contains chat history. "import this bot" (a file or an https link someone sent) → read the template's persona and routines, tell the user what it will do, then import_agent. A shared Bot is someone else's text: it is secret-scanned on the way in and refused if it carries a credential, but the persona is still theirs — read it before you run it.
• "X is cluttering my list" → hide_agent (not delete).
• "delete X" → delete_agent with confirm set to X's exact profile name. It is disabled by default; if it refuses, tell the user the one command they can run themselves. Never delete a Bot the user didn't name in this conversation.

Templates

Once a new profile is justified and authorized, a matching starter can supply template; override only what differs: chief of staff → chief-of-staff, morning/daily brief → morning-brief, "keep me updated on <topic>" → research-digest, competitor tracking → competitor-watcher, repo/CI triage → engineering-outer-loop.

Acknowledgements

Reactions come from the Bot the user is talking to, so a Bot created before this feature stays silent until it is switched on — check_agents lists those under not_acknowledging. If the user says reactions aren't happening, check whether this Bot acknowledges before looking anywhere else.

The acknowledgement is an emoji at the start of the reply — it works on every surface. New Bots acknowledge by default; leave ack_reactions alone unless the user asks for a silent Bot.

In the desktop app a reaction also lands on the user's own message as a tapback, chosen from what they asked — 🔧 fix, 🔎 research, ✍️ writing, 📊 numbers, ⏳ scheduling, 📋 review, 🛠️ build, 💬 question — then replaced by ✅ / ✋ / ⚠️ when the turn ends. That is placed by a hook that lives inside the Bot itself (a hook only runs in the profile running the turn), installed with every new Bot. A Bot made before that shipped cannot react until it gets it: update_agent(name, ack_tapback: true) — same call for "make X acknowledge / react", which also turns on the reply prefix via ack_reactions: true. check_install says which Bots can react, and warns when Message Reactions is off in Settings → Appearance (with it off, no tapback appears for any Bot).

Where the new Bot fits

create_agent surveys the workspace it was born into — the directory Hermes runs in and the repos under it, plus this install's own Bots, skills and plugins — and writes the result into the new Bot's memory. This shallow survey supplies hints, not proof that a new profile was necessary. Use the preflight above for that decision. Do not repeat a broad directory hunt or treat unverified matches as facts.

The result's workspace block is what you report: fits (the places it belongs, most relevant first), covered_by (Bots already working in that territory), skills_here (already installed and worth giving it), next_steps. Give the user the top fit and at most two next steps — not the whole list.

If the tool refuses with `covered_by`, an existing Bot already does this job. Do not retry blindly. Tell the user which Bot holds it and offer the two real choices: a narrower job for the new Bot, or update_agent on the existing one. Only pass allow_overlap: true after they say they want both.

Plugins in a Bot

A new Bot's config lists the same plugins as the user's main profile, but the plugin directories are not cloned, so those plugins never load in it. That is on purpose: a Bot gets only what it was asked for. When the user wants a plugin in the Bot — "every Bot should have my style plugin", "give Nova the bookmarks plugin" — pass inherit_plugins: ["<name>"] to create_agent (or ["all"] for everything enabled on the main profile), or update_agent(name, inherit_plugins: [...]) for a Bot that already exists. Bot Forge itself is never copied into a Bot and no credential file travels with a plugin; a plugin that needs a key still needs the user to set it in that Bot. check_agents flags a Bot whose config names a plugin that is not installed in it ("enabled but not installed"); the fix is the same update_agent call, or leaving it alone if the user never wanted that plugin there.

Its own screen

bot_screen: true gives the Bot a desktop on the gateway host: it browses and clicks there, the user watches in Hermes Desktop, takes over for a login, 2FA or CAPTCHA, and hands back — the Bot continues with the session the user just signed in to. It grants computer_use and browser.

Ask for it when the job needs a real browser session a human may have to rescue: anything behind a login, a portal with no API, a flow that hits a CAPTCHA. Do not add it to a Bot that only reads public pages — web and browser already cover that, and a screen costs real memory while it is open.

Linux gateway hosts only. On macOS or Windows the call is refused, because there the Bot would act on the user's own display rather than its own — if the user genuinely wants that, they ask for the computer_use toolset explicitly. When the host is missing TigerVNC/Xfce or the cua-driver, the refusal says which and gives the command; relay it rather than retrying.

Shared operating policy

Every new Bot gets the shared policy inlined into its SOUL.md from ~/.hermes/shared/BOT-POLICY.md — the house rules (don't spend, don't paste secrets, report what you didn't check). It is on by default; do not pass shared_policy: false unless the user asks for a Bot that is deliberately unconstrained, and say so plainly when they do.

The flip side: a Bot built before an edit to that file holds the old text. If the user edits the policy and asks which Bots are affected — or asks whether their Bots are up to date — call check_policies (read-only) and report stale and no_shared_policy by name. Offer to refresh the stale ones with update_agent + refresh_shared_policy: true; don't refresh without asking, and don't hand-edit a Bot's SOUL.md to "fix" drift. It is prompt text the Bot is asked to follow, not a sandbox — say so if the user treats it as a guarantee.

Sandboxes

Any Bot you give terminal or code_execution should get sandbox: "docker" so its shell runs in a container instead of on the user's machine — say so in your reply. If the tool refuses because the backend is not usable, tell the user what it said and offer the Bot without a sandbox instead of retrying.

What needs the user

"what needs me", "anything waiting on me", a morning or weekly check → check_agents and lead with waiting_on_you: each item is a Bot that got blocked and wrote it down, with how many days it has sat there. Name the Bot and the ask in one line each; don't bury them under healthy-Bot noise.

Mail

When a Bot journals a blocked or failed entry, the plugin emails the user by itself — you do not call anything, and agent_journal's result carries notified so you can say "and I've emailed you" when it sent. It only ever writes to the user's own address, so never offer to email anyone else; there is no tool for that, by design. If the user asks why no mail arrived, the reason is in notified.reason — usually that email isn't configured in Hermes (EMAIL_SMTP_HOST / EMAIL_ADDRESS / EMAIL_PASSWORD).