Camp Run with Hermes Agent

The official starter kit for the CAMP / RUN Hermes Agent hackathon — October 2, 2026 · Avtica Office.

Fork this repo, and in 45–60 minutes build one connected solution on top of a realistic business sandbox:

  LAYER 3 · DESKTOP PLUGIN      LAYER 2 · SKILL            LAYER 1 · MCP SERVER        SANDBOX
  "the face"                    "the playbook"             "the hands"
 ┌──────────────────┐        ┌──────────────────┐       ┌──────────────────┐       ┌──────────────┐
 │ Pane / command in│ ─────▶ │ SKILL.md teaches │ ────▶ │ Python tools that│ ────▶ │ data/store.db│
 │ Hermes Desktop   │        │ Hermes a workflow│       │ read & act on the│       │ Suki Mart    │
 └──────────────────┘        └──────────────────┘       │ data             │       └──────────────┘
                                                        └──────────────────┘

Everything runs locally on your laptop — no cloud, no accounts, no API keys for the data. Works offline.

---

Contents

• The sandbox: Suki Mart
• Before the event
• Quick start
• Layer 1 — MCP server
• Layer 2 — Skill
• Layer 3 — Desktop plugin
• Suggested timebox
• Rules & judging
• Troubleshooting

---

The sandbox: Suki Mart

Suki Mart is a fictional grocery and delivery chain with 12 branches across Metro Manila — BGC, Makati, Ortigas, Kapitolyo, Cubao, Katipunan, Tomas Morato, Shaw, Alabang, BF Parañaque, Marikina and Ermita.

It lives in one SQLite file, data/store.db, with ~230,000 rows across 18 tables and six months of history:

📖 Full column reference: data/SCHEMA.md

Three things to know:

1. “Today” inside the data is 2026-09-30. Use it for “this week”, “last 30 days”, “overdue”, etc.
2. The data is messy on purpose. Every department has real problems planted in it — the kind a real operations or customer team would lose sleep over. Finding one worth solving is part of the challenge.
3. You can’t break it for good. python data/seed.py rebuilds the exact same database in seconds.

The challenge track is Business Operations or Customer Experience (Open Innovation may also be considered).

---

Before the event

Do this at home — venue Wi-Fi is not the place to install things.

• [ ] Hermes Agent + Hermes Desktop installed → docs
• [ ] A working model provider (hermes model) — your own account
• [ ] hermes doctor passes
• [ ] uv available (uv --version) — the Hermes installer includes it
• [ ] git installed and this repo forked & cloned
• [ ] Python 3.10+ (only needed if you run the scripts directly)

---

Quick start

# 1. Fork this repo on GitHub, then clone YOUR fork
git clone https://github.com//Camp-Run-with-Hermes-Agent.git
cd Camp-Run-with-Hermes-Agent

# 2. Check the MCP server starts (Ctrl+C to stop — it waits silently for Hermes)
uv run mcp-server/server.py

# 3. Register it with Hermes — use the ABSOLUTE path to server.py
pwd        # macOS / Linux  →  e.g. /Users/you/Camp-Run-with-Hermes-Agent
cd         # Windows (cmd)  →  e.g. C:\Users\you\Camp-Run-with-Hermes-Agent

hermes mcp add suki --command uv --args run /ABSOLUTE/PATH/Camp-Run-with-Hermes-Agent/mcp-server/server.py

# 4. Restart Hermes (no hot-reload for MCP), then verify
hermes mcp test suki

Then ask Hermes: “Use the suki MCP server to describe the Suki Mart sandbox.”

Alternative to step 3 — add it to ~/.hermes/config.yaml yourself:

mcp_servers:
  suki:
    command: uv
    args: ["run", "/ABSOLUTE/PATH/Camp-Run-with-Hermes-Agent/mcp-server/server.py"]

---

Layer 1 — MCP server

📁 mcp-server/server.py

A working Python MCP server (FastMCP) with the database already wired up and two tools: describe_sandbox (exploration helper) and list_branches (an example domain tool). Your job: add the tools your idea needs.

@mcp.tool()
def find_stockout_risks(branch_code: str, days_of_cover: int = 3) -> list[dict]:
    """Products at a branch that will run out within N days at current sales pace."""
    return query("SELECT ... WHERE ...", (branch_code, days_of_cover))

Good tools:

• Answer one business question each, with clear parameters (branch_code, days, limit…).
• Keep SQL inside the tool. A generic “run any SQL” tool scores low — the judges want domain design.
• Return small, structured results. 20 clean rows beat 2,000 raw ones.
• Have a docstring written for the AI — it’s how Hermes decides when to call the tool.
• Can take action with the execute() helper (resolve a ticket, create a purchase order, flag a customer…).

After every change: restart Hermes, then hermes mcp test suki. Tools appear to the agent as mcp_suki_.

The server pins mcp<2 (the classic FastMCP API most docs and AI assistants use). uv run installs it automatically — no pip install needed.

---

Layer 2 — Skill

📁 skills/suki-team-skill/SKILL.md

A skill is a markdown procedure Hermes loads on demand. It teaches the agent when to act and how to chain your MCP tools into a real multi-step workflow — the sequence, the decision rules, and the output format.

# 1. Rename the folder AND the `name:` field to your skill's name (they must match)
# 2. Fill in the template, then install it:
cp -r skills/ ~/.hermes/skills/                      # macOS / Linux
xcopy /E /I skills\ %USERPROFILE%\.hermes\skills\   # Windows

Installed skills take effect in new sessions — start a new chat after installing. Test it by asking something that matches your skill’s description, or name it directly: “Use the \ skill to…”

📖 Working with Skills

---

Layer 3 — Desktop plugin

📁 desktop-plugin/suki-panel/plugin.js

A pane inside Hermes Desktop with buttons that trigger your skill, plus a ⌘K / Ctrl+K command. It’s a single JavaScript file — no build step.

# Rename the folder AND the `id` in plugin.js (they must match), then:
cp -r desktop-plugin/ ~/.hermes/desktop-plugins/                               # macOS / Linux
xcopy /E /I desktop-plugin\ %USERPROFILE%\.hermes\desktop-plugins\   # Windows

In Hermes Desktop: ⌘K / Ctrl+K → “Reload desktop plugins”, and enable it under Capabilities → Plugins if needed. Saves hot-reload after that.

Loader rules (from the SDK):

• Only three imports work: @hermes/plugin-sdk, react, react/jsx-runtime.
• The file isn’t compiled — write UI with jsx() / jsxs(), not `` syntax.
• Use theme variables (var(--ui-text-secondary)), never hardcoded colors.

Going further: the template sends prompts into the chat with host.composer.submit(). The SDK can do much more — sidebar pages, status-bar widgets, transcript directives that render your own components inside the agent’s reply, and a Python backend via ctx.rest. Hermes ships a bundled hermes-desktop-plugins skill — ask your agent to help you build the pane.

📖 Desktop Plugin SDK

---

Suggested timebox

Using Hermes (or any AI) to help write your code is allowed and encouraged. The idea, the design and the integration are what’s judged.

---

Rules & judging

📋 Full mechanics and scoring: docs/JUDGING.md

• Build on the Suki Mart sandbox data.
• Write your own MCP — catalog MCPs or existing plugins don’t count as your team’s build.
• Demo live from your laptop: problem → how Hermes is used → working output, in 5 minutes.

---

Troubleshooting

---

Repository layout

Camp-Run-with-Hermes-Agent/
├── data/
│   ├── store.db              ← the Suki Mart sandbox (SQLite)
│   ├── seed.py               ← deterministic generator = reset command
│   └── SCHEMA.md             ← tables, columns, relationships, enums
├── mcp-server/
│   └── server.py             ← Layer 1 template
├── skills/
│   └── suki-team-skill/
│       └── SKILL.md          ← Layer 2 template
├── desktop-plugin/
│   └── suki-panel/
│       └── plugin.js         ← Layer 3 template
└── docs/
    └── JUDGING.md            ← mechanics & scoring

---

License

MIT — fork it, remix it, ship it. Suki Mart and every person, business and record in the dataset are fictional; any resemblance to real entities is coincidental.

Built for CAMP / RUN · Avtica × DEVCON Manila · Powered by Hermes Agent by Nous Research.