100yenadmin/boardstate-hermes-plugin

Última atividade de origem registrada: 14 de outubro de 2026 às 17:21

Catálogo do SkillsMP atualizado: 9 de novembro de 2026 às 14:22

skills coletadas: 1

Estrelas no GitHub: 13
Forks no GitHub: 1

Instalar com um assistente de IA

Copie este prompt para o assistente de IA que você usa.

Follow https://skillsmp.com/skill-install/prompt.md to install Agent Skills from https://github.com/100yenadmin/boardstate-hermes-plugin.

README do repositório

Arquivo de origem do README: README.md

Ler o README original

Expandir README completo

# Boardstate for Hermes ![Boardstate: a live board your agent builds for you](docs/media/banner.png) Boardstate gives Hermes a durable board that the agent can build with native tools. Open the **Board** tab in `hermes dashboard` or the **Board** page in Hermes Desktop, then ask Hermes to create tabs, add widgets, arrange a layout, or review its design. Widgets include notes, markdown, tables, charts, KPI cards, live Hermes data, and approvals. Changes are stored as a validated workspace document and appear live when the dashboard socket is available. Boardstate is one unified Hermes plugin: the agent tools, Web dashboard tab, Python backend, Desktop page, and loopback Node sidecar install from this repository together. ## Install Boardstate requires Hermes 0.21.2 or newer and Node.js 20 or newer. Boardstate looks for Node in `HERMES_NODE_BIN`, then in Hermes' own Node lookup, then on `PATH`. ```bash hermes plugins install boardstate --enable ``` This installs the catalog entry at its reviewed pin. To install a specific release straight from this repository, pin its commit: ```bash hermes plugins install 100yenadmin/boardstate-hermes-plugin --ref <40-character commit sha> --enable ``` Each [release](https://github.com/100yenadmin/boardstate-hermes-plugin/releases) names its commit sha. `--ref` takes a full sha, not a tag. Hermes scans this install as a community source. On Hermes 0.23.0, 1.5.4 scans `safe`, so it installs with no prompt and no `--force`, including from Hermes Desktop and scripts. CI runs that scanner on every later commit and fails on anything that would not scan `safe` (see "Security scanner notes" below). 1.5.3 and earlier scan `caution`. If Boardstate is already installed, for example at an older catalog pin, remove it first. The board stays in `boardstate-state` (see "Uninstall" below). Then run the line above: ```bash hermes plugins remove boardstate ``` `hermes plugins update boardstate` follows the catalog pin, so it does not move a catalog install to a newer release. Use this form when `hermes plugins install boardstate` gives an older version than the latest release. Hermes 0.23.0 falls back to the catalog copy it shipped with when it cannot use the published catalog ([NousResearch/hermes-agent#151856](https://github.com/NousResearch/hermes-agent/issues/151856)). To enable an installed copy later: ```bash hermes plugins enable boardstate ``` Start `hermes dashboard` for the Web tab. The unified package also contributes a Desktop plugin; enable **Boardstate** under **Capabilities → Plugins** in Hermes Desktop. The two surfaces have separate enable switches by design. After you update or reinstall the plugin, quit and reopen Hermes Desktop. **Rescan** under **Capabilities → Plugins** copies the new Desktop files, but a Desktop plugin that is already loaded keeps running its old code until the app restarts. ### Profiles On Hermes 0.21.x, `hermes -p <name> dashboard` re-runs as the default profile with `--open-profile <name>`. Web dashboard plugins load from the root `~/.hermes/plugins`, and their state comes from the dashboard process's `HERMES_HOME`, so the web **Board** tab shows the default profile's board. Install with `hermes plugins install …` (no `-p`) for the dashboard, and with `hermes -p <name> plugins install …` for that profile's agent tools. Hermes Desktop loads the Desktop half app-wide from `~/.hermes/desktop-plugins` once you switch it on under **Capabilities → Plugins**, and talks to the active profile's backend. ### Uninstall Run `hermes plugins remove boardstate`. The board itself stays in the `boardstate-state` directory of the profile's Hermes home: `$HERMES_HOME` when you set it, otherwise `~/.hermes` for the default profile and `~/.hermes/profiles/<name>` for a named profile. If you set `BOARDSTATE_HERMES_STATE_DIR`, the board is in that directory instead. Delete it if you no longer need the board. ## Native agent tools No hand-written `mcp_servers` entry is needed. The package registers these 19 tools in the `boardstate` toolset: - `boardstate_workspace_get` - `boardstate_tab_create`, `boardstate_tab_update`, `boardstate_tab_delete`, `boardstate_tabs_reorder` - `boardstate_widget_add`, `boardstate_widget_update`, `boardstate_widget_move`, `boardstate_widget_remove` - `boardstate_layout_set`, `boardstate_workspace_replace`, `boardstate_undo` - `boardstate_widget_catalog`, `boardstate_design_review`, `boardstate_widget_scaffold`, `boardstate_data_read` - `boardstate_tool_search`, `boardstate_connector_read`, `boardstate_connector_invoke` `boardstate_workspace_get` also returns what the user typed into each Notes card, read-only, as `notes` beside the document, so the agent can read and act on it. A Notes card that nobody has typed in has no entry. The two connector invocation tools and `boardstate_tool_search` are always discoverable. Without an operator-authored connector configuration they return a clear `no connectors configured` error. The existing Streamable HTTP MCP endpoint remains available as an optional compatibility path at `/api/plugins/boardstate/mcp`, but normal Hermes use should rely on the native tools. ## What runs Boardstate starts one Node sidecar on an ephemeral `127.0.0.1` port. Every spawn gets a random nonce. Its mode-0600 port record contains the port, nonce, process id, and owner kind so the agent and dashboard do not create competing writers. - An agent tool call can start the sidecar without the dashboard. That sidecar gets no operator secret at all, so operator-only verbs are unavailable until the dashboard replaces it. On it, `boardstate_connector_invoke` still runs approved readOnly connector tools; a mutating tool asks the agent to open the Board tab instead of parking. - When the dashboard finds an agent-owned sidecar, it terminates and replaces that process with a dashboard-owned one. Both use the same state directory, so the board survives. - An agent-owned sidecar is stopped when its owner exits if no live agent process adopted it. A process never stops a sidecar whose port record has moved to another spawn. - If every process named in the sidecar's port record (its owner and any adopters) dies without cleaning up, for example after `SIGKILL`, the sidecar notices within a few seconds and shuts itself down. - Live Hermes data widgets use the authenticated dashboard API. When only the agent half is running, they show an explicit "open the Board tab" unavailable message instead of crashing. The Desktop plugin stays inside the public plugin SDK. It uses `ctx.register` with `ROUTES_AREA` and `SIDEBAR_NAV_AREA` for the page and its nav row, `ctx.rest` for Boardstate requests, `ctx.socket` for server pushes, `ctx.onDispose` for cleanup, `ctx.setTimeout` when the SDK provides it (with a disposed fallback timer on older SDKs), and `host.notify` for template errors. OAuth remotes support request/response traffic but the SDK intentionally provides no live socket there, so the page reports **live updates unavailable** instead of pretending to be live. ## Network and security disclosure Boardstate makes no third-party network request by default. - The sidecar, dashboard bridge, native tool wrapper, and optional MCP path communicate on loopback only. Live Hermes widgets call the local Hermes dashboard API. - External connectors are opt-in. Only an operator-authored `$HERMES_HOME/boardstate-state/boardstate.connectors.json` can enable one. A connector may spawn its configured local command or contact its configured remote MCP URL; those are the only runtime paths that can reach outside Hermes. - Connector reads require an approved grant. Connector mutations park for an operator decision. A changed connector manifest re-pends its grant. A mutation whose wait times out is reported as parked, but a later confirm can still run it, so the agent is told not to retry it on its own (a retry can run the mutation twice) and to ask the operator for the outcome. - Operator approve/confirm/deny verbs use a separate in-memory secret that is never written to the port record. In gated multi-user mode, `boardstate.operators.json` is also required. - Sidecar traffic never goes through an `HTTP(S)_PROXY` from the environment. - The sidecar inherits the Hermes process environment, so provider keys there are available to connector `env` references. A dashboard-owned sidecar also receives the dashboard session token so live Hermes data widgets can read the local dashboard API. - **Limit of the operator gate.** It keeps approvals off the agent's tool surface: no `boardstate_*` tool, MCP call or board WebSocket can approve or confirm anything. It is not a boundary against an agent that has unrestricted shell access as the same OS user. In ungated loopback mode, such an agent can read the dashboard page, which carries the dashboard session token. In any mode, it can read a same-user process's environment, including the dashboard-owned sidecar's operator secret. If approvals must hold against the agent itself, run the agent's terminal in an isolated backend (for example Docker, SSH or Modal) or as a different OS user from the dashboard. - Text typed into a Notes card is visible to the agent: `boardstate_workspace_get` returns it read-only, like the rest of the board. Keep secrets out of Notes cards. - Approved custom widgets run in an opaque-origin iframe with a no-network Content Security Policy. Pending, rejected, and unknown widget assets all return 404. ## Connector configuration Connectors are optional. For example, after installing OfficeCLI, an operator can create: ```json { "connectors": [ { "name": "officecli", "transport": "stdio", "command": "officecli", "args": ["mcp"] } ] } ``` Save that as `$HERMES_HOME/boardstate-state/boardstate.connectors.json`, restart the dashboard, and approve only the requested tools you want. See [docs/connectors/officecli.md](docs/connectors/officecli.md). Connector grants are scoped to the active Hermes profile: Boardstate keeps separate state for each `HERMES_HOME`/profile, while sessions within one profile are the same agent and intentionally share native-tool grants. ## Security scanner notes On Hermes 0.23.0, `hermes plugins validate` and the install-time scan report `safe`: no HIGH or CRITICAL finding, so a pinned `owner/repo` install needs no `--force`. CI runs the v0.23.0 scanner on every commit (`test/install_scan.py`). Reviewers should still read every finding. Before 1.5.4 the scan reported `caution` for two HIGH findings, both dependency text in the committed `dashboard/sidecar/server.js` bundle that never runs. `build.mjs` now leaves both out of the bundle, and `test/scan-hygiene.mjs` checks the result: - `exfil_service`: the default Pipedream remote-MCP URL in `@boardstate/broker`'s Pipedream preset. Boardstate imports only the broker's OfficeCLI preset. The build lets esbuild tree-shake the broker's unused preset table, which takes the Pipedream and Composio presets with it. Operators still author connectors, any remote MCP URL included, in `boardstate.connectors.json`. - `sudo_usage`: a comment in the MCP SDK's stdio client about the environment variables a child process inherits. The build drops the comment; the code is unchanged. The MEDIUM and LOW findings are informational. They fall into these groups: - Character-code, base64, Unicode-escape, backtick and relative-path matches in the generated bundles: `server.js`, `dashboard/dist/index.js`, `dashboard/vendor/boardstate-browser.js` and `desktop/plugin.js`. - Oversized-file warnings for `server.js` and `docs/media/banner.png`. - Mentions in the docs and CI: `sudo` (this section, CHANGELOG.md and a CI step name), agent-config file names (AGENTS.md, CLAUDE.md, CONTRIBUTING.md, CHANGELOG.md, README.md and the pull request template), and `pip install` / `git clone` steps (AGENTS.md and `.github/workflows/ci.yml`). - `subprocess` use and path fixtures in `test/`. - An example loopback dashboard address in a comment in `dashboard/sidecar/src/hermes-data.ts`. Catalog self-updater check: the catalog CI flags a bundled JS file that contains both a GitHub raw-content URL and a file-write call. In the sidecar bundle, the only such URL was ajv's `$data` meta-schema **identifier** (its `$id` and the one `$ref` to it), which is never fetched. `build.mjs` rewrites that identifier consistently to `https://ajv.js.org/refs/data.json#`, so the check stays meaningful for this bundle: a later `releases/latest` or `raw.githubusercontent.com` URL next to a file write would still trip it. This repository's CI replays the check, with upstream's exact file enumeration, on every build. Boardstate has no updater; updates arrive only through a new catalog pin plus `hermes plugins update boardstate`. `dangerous` scanner results are not accepted. Reproduce the reviewed artifacts with: ```bash npm ci && npm run build && git diff --exit-code ``` ## Development and tests The build produces the Web bundle, root `desktop/plugin.js`, sidecar bundle, vendored Lit assets, and `dashboard/tools.schema.json`. The schema is generated from the same Boardstate tool factory and connector definitions the sidecar invokes. CI keeps the existing sidecar, connector, operator, widget, theme, Web, Desktop, and Python tests. It also pins Hermes upstream commit `38c289c0146ed8c8b2b767eca1fff6f5b7e6382e` and runs plugin validate, doctor, compat, native-tool dispatch, WebSocket auth, and the schema sync gate. ## Screenshots A board built by the agent through the native tools, in the Web **Board** tab: ![Boardstate Board tab in the Hermes web dashboard](docs/screenshots/web-board.png) The same kind of board on the **Board** page in Hermes Desktop: ![Boardstate Board page in Hermes Desktop](docs/screenshots/desktop-board.png) ## Troubleshooting and reporting a bug Boardstate has no agent-callable diagnostics tool yet. Collect recent logs with `hermes logs gui -n 300 | grep -i boardstate` (dashboard), `hermes logs desktop -n 300 | grep -i boardstate` (Desktop), or `hermes logs -n 300 | grep -i boardstate` (agent tools); remove tokens, credentials, private data, and local paths. In a browser tab where you are already signed in to your local Hermes dashboard, open `/api/plugins/boardstate/health` and check the browser console. The probe reports `ok`, `sidecar_running`, `sidecar_port`, `state_dir`, and `bundle_present`; leave `state_dir` out of the report. Don't copy session tokens or call the endpoint or the gateway by hand with credentials. On Hermes 0.21.6 or newer, ask your Hermes agent to "report a problem with Boardstate". On older versions, ask it to load the `boardstate:boardstate-report-problem` skill. Either way, review its draft before it is filed. Use the [bug report form](https://github.com/100yenadmin/boardstate-hermes-plugin/issues/new?template=bug_report.yml). Report security problems through a [private advisory](https://github.com/100yenadmin/boardstate-hermes-plugin/security/advisories/new). ## License MIT — see [LICENSE](LICENSE).

Carregando o README do repositório…

Skills neste repositório

classificação pendente

skill

ocupação

descrição

atualizado

boardstate-report-problem

sem classificação

Boardstate: report a bug or problem

Idioma do texto original: inglês

2026-10-14

Mostrando 1 de 1 skills coletadas.