---
name: local-agent-gui
description: "Build local-first GUI wrappers for LLM agents (Hermes, Claude Code, OpenClaw, etc.) with a shared adapter protocol, chat UI, and animated avatar/scene layer."
version: 1.0.0
author: Hermes Agent
license: MIT
platforms: [linux, macos, windows]
metadata:
  hermes:
    tags: [gui, agent, local-first, dashboard, cli-wrapper, avatar, pixel-art, browser-ui]
    related_skills: [plan, sketch, local-web-collection-apps, hermes-agent]
---

# Local Agent GUI

Use this skill when the user wants a browser-based or desktop-style UI that sits on top of one or more existing LLM agents instead of replacing them.

Typical requests:
- "make Hermes usable without the terminal"
- "one GUI for Hermes, Claude Code, OpenClaw, and other agents"
- "add an avatar, sprites, or a themed workspace around the agent"
- "build a local dashboard that can switch between agents"

## Core principles

- Build local-first: run on `127.0.0.1` with no cloud dependency for the UI itself.
- Treat agents as pluggable backends, not hard-coded products.
- Normalize every backend into a small event protocol: user message, assistant message, status, tool request, tool result, error.
- Keep the UI independent from any one agent’s terminal format.
- Prefer a one-shot CLI adapter first, then deepen integrations only after the UI is usable.
- Make the visual layer state-driven: avatar/scene mood should reflect execution state, not invent it.

## Recommended architecture

1. Shared UI shell
   - agent picker
   - chat log
   - status/timeline
   - avatar or scene canvas
   - session list / history

2. Adapter layer
   - `echo` or noop adapter for smoke tests
   - `cli` adapter for commands like `hermes chat -q {prompt}` or `claude -p ... {prompt}`
   - optional deeper adapters later (streaming JSON, MCP, gateway, native APIs)

3. Session/state layer
   - local JSONL or SQLite
   - store normalized events, not raw terminal spam only
   - keep history reloadable from the UI

4. Visual layer
   - ASCII avatar for V1
   - canvas or sprite-based scene for V2
   - state transitions: idle, thinking, tool, speaking, error

## Adapter design

Use a config-driven agent registry, not code edits for every new backend.

Minimum config fields:
- `id`
- `name`
- `type` (`echo` or `cli` in V1)
- `description`
- `command` for CLI agents as argv array
- `timeout_seconds`
- `enabled`

Important rules:
- Do not use `shell=True` for agent commands.
- Use argv lists with placeholders like `{prompt}` and `{session_id}`.
- Keep the echo adapter around forever for tests and demos.

## UI / visual direction

Good directions for this class of app:
- retro terminal-to-office hybrid
- pixel-art control room
- arcade / Metal Slug-like office with walking agents
- clean futuristic shell with an animated mascot

When the user asks for a look-and-feel iteration:
- produce a throwaway sketch first if the visual direction is unclear
- compare 2-3 distinct stances instead of tweaking one layout blindly
- verify in the browser, not just from code

## Good implementation sequence

1. Build the backend with one echo agent and one CLI adapter.
2. Add chat + history + a single status indicator.
3. Add an avatar/scene canvas driven by execution state.
4. Add agent registry config and session persistence.
5. Add a second real agent (Hermes, Claude Code, etc.).
6. Polish the visuals into the requested aesthetic.
7. Add streaming and richer tool-call rendering later.

## Testing and verification

Test at three levels:
- adapter unit tests
- session/history tests
- live smoke test through the browser UI

The browser smoke test should confirm:
- the page loads
- the selected agent can change
- a message can be sent
- the avatar/scene visibly changes state
- the reply renders in the chat log

If the scene uses canvas or sprites, verify with a browser screenshot/vision pass, not just DOM checks.

## Common pitfalls

- Hard-wiring one agent’s CLI flags into the whole app.
- Building only a static mockup instead of a real message flow.
- Letting the avatar become decorative only; it should reflect state changes.
- Using raw terminal output as the UI model instead of normalized events.
- Ignoring the echo adapter, which is the easiest non-network smoke test.
- Making the agent list a code constant when it should be config-driven.

## Useful support files

- `references/verified-cli-adapters.md` - concrete command patterns and launch notes captured from this session.
- `templates/agents.json` - starter config for echo + Hermes + Claude Code + OpenClaw.

## When to load this skill

Load it before starting a project that gives a GUI to one or more LLM agents, especially if the user wants a local web app, a retro/pixel-art shell, or a mascot/avatar layered over agent execution.