# hermes-feishu-streaming-card: a live card layer for a Hermes agent

> The Hermes Feishu streaming card plugin turns a Hermes Agent Gateway into an updating Feishu or Lark card, with task sections, approval and choice buttons, continuation cards, expiry states and per turn token statistics. It is a sidecar rather than an agent, it runs as a Python 3.9 plugin, and its v5 release reorganised the whole reading flow.

**baileyh8/hermes-feishu-streaming-card** — Feishu streaming card for Hermes Gateway

- Repository: https://github.com/baileyh8/hermes-feishu-streaming-card
- Stars: 693 · Forks: 86
- Language: Python
- License: MIT
- Published: 2026-10-21 · Updated: 2026-10-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/baileyh8-hermes-feishu-streaming-card

## A sidecar that renders Hermes, it does not replace it

The plugin, abbreviated HFC, turns the Feishu or Lark replies of the Hermes Agent Gateway into continuously updated interactive cards. The scope statement in the readme is precise: models, tools and tasks are still executed by Hermes, and HFC is responsible for card display, interaction and delivery.

That division has a consequence worth internalising before you install anything. Hermes remains the agent, HFC is a sidecar that observes the gateway and renders what it sees. The badges in the readme say the same thing, listing the runtime as sidecar only, and the package description calls it a gateway Feishu streaming card sidecar plugin. The entry point is registered in the hermes_agent.plugins group, so it loads as a plugin rather than as a separate service you point traffic at.

The target audience is stated plainly: people who already use the Hermes Agent, or who are about to connect it to Feishu. If you are looking for an agent framework, this is the wrong project, and if you are on Slack or Teams rather than Feishu or Lark, the card format is the whole integration point and it will not apply.

The project is MIT licensed, written in Python, and the last push was on 2026-10-22 with v5.0.4 tagged 2026-10-20, so the work is current.

The underlying agent is the Hermes Agent from Nous Research, and the repository documentation repeatedly stresses that the plugin does not alter authorisation decisions. When the card takes over a message, it reduces repeated native text, but attachments and paths where delivery cannot be confirmed still keep a necessary fallback.

## The v5 layout separates the task, the process and the answer

Version 5 reorganised the reading flow from the start of a task, through waiting for a confirmation, to the final answer. The change table in the readme lists five areas, and each maps to a concrete thing a user sees.

Task sections are the first. Status, body text, execution process and statistics each get their own place, with long answers keeping their full content and the process staying available to expand and review. Interactive continuation is the second: approvals, single choice, multiple choice and text input keep using the original Hermes flow, and when there is a reliable target, the old card gets a link to view the continuation.

Explicit result states are the third, and this is the one that addresses a real support problem. A refusal shows as already refused, a natural timeout shows as already timed out, and after expiry the question and the option record are kept while the action buttons are withdrawn. Stale buttons that silently do nothing are the kind of detail that generates bug reports.

Per turn statistics are the fourth: the footer shows the model actually used, elapsed time, input and output tokens and context usage, with missing fields left out rather than filled with invented numbers. That last constraint is the right one for a metric display.

Configurability you can check is the fifth. The readme describes a generated minimal YAML that contrasts the values already loaded by the process with the values that will be loaded next time, so you can preview offline before changing anything. The upgrade path in the same paragraph says the task preset is not applied automatically, that existing classic, focused and detailed presets stay as they are, and that profile or bot level values can still override a global setting.

## The two configuration keys that switch on the task layout

Adopting the v5 task layout is a two line configuration change merged into the global card section of your existing config, followed by a sidecar restart. The readme is explicit that you should not overwrite the whole file, because explicit profile and bot values can still override the global settings.

```yaml
card:
  reading_preset: task
  timeline_expanded: false
```

The effect of the pair is worth spelling out, because the two lines are not redundant. The task preset itself defaults to expanded, so the second line is the one that actually chooses to collapse the execution process, while the finished result can still be expanded later.

That is a small configuration surface for a large layout change, and it is the shape a plugin should have. Everything else in the plugin is driven by Hermes, so the configuration a user actually touches is small, and the readme documents a card-config command that shows the running configuration, which is the command to reach for when the card does not look the way you expect.

The readme also lists the reasons a user would want the plugin at all, and those are worth reading as a description of the design. Knowing whether a task is progressing is answered by showing the current tool action, the process log and the answer, and distinguishing running, waiting, failed and completed. Typing less and seeing less screen spam is answered by buttons and forms for approvals and clarifications, with system prompts gathered in one place. Long answers stay readable because the body and the thinking or tool process are separated, with Markdown, code and tables supported and optional reading presets.

## Installation runs a script that writes your .env and starts a sidecar

The prerequisites are an installed Hermes Agent, Python 3.9 or newer, and a Feishu or Lark bot already connected to Hermes with an App ID and App Secret. The first time connection, permissions and environment notes are in the install manual, and the package classifiers confirm the Python 3.9 through 3.12 range and mark the development status as production and stable.

On macOS and Linux the install is a single pipeline:

```bash
curl -fsSL https://raw.githubusercontent.com/baileyh8/hermes-feishu-streaming-card/main/install.sh | bash
```

On Windows PowerShell it is the equivalent:

```powershell
irm https://raw.githubusercontent.com/baileyh8/hermes-feishu-streaming-card/main/install.ps1 | iex
```

The script resolves the latest stable release by default, installs into the environment Hermes uses, reads or prompts for credentials and writes them to a local .env, then completes configuration, hook installation and sidecar startup. If you already have the package, the integrated installer can be run by hand:

```bash
python3 -m hermes_feishu_card.cli setup --hermes-dir ~/.hermes/hermes-agent --config ~/.hermes/config.yaml --yes
```

The runtime dependencies are deliberately small, aiohttp and PyYAML in the package metadata, and the requirements file lists pyyaml and regex. Test extras pull in pytest and pytest-asyncio, and the quality extras pin ruff and mypy to exact versions for Python 3.10 and newer.

The plugin also ships as a command line entry point named hermes-feishu-card, which is what the status, doctor and card-config commands come from.

## The v4 to v5 upgrade is a planned procedure, not a reinstall

The readme leads with the reassurance that matters most for an existing bot: you do not have to recreate it. You keep the actual Hermes directory, the config file, the credential file and the profile, and the readme warns against copying the example paths blindly into a split HOME, Docker or multi instance environment.

The steps are deliberate. First, record the current HFC and Hermes versions and how the service starts, back up the config, the .env and the installer recovery data, wait for running tasks to finish, then stop the Gateway, Desktop and sidecar with your existing service manager. Second, run the install script pinned to the exact version, keeping the same config and credential paths, and only once that tag is actually published, since the installer checks the origin and compatibility of the old installation. Third, if the diagnostics ask for the old hook to be restored first, run the official restore command it gives and reinstall, and if the source has drifted in an unknown way, stop and investigate rather than editing gateway/run.py by hand or deleting a manifest or a backup to force things through. Fourth, merge the two configuration lines if you want the new task layout, keeping the rest of your credentials, routing, native tables and reading presets. Fifth, restore the service manager, restart the Gateway and Desktop, and run status, doctor --explain and card-config --running, then send the bot a message to confirm the card and the footer.

The pinned install looks like this on macOS or Linux, with the paths to be changed to match your own installation:

```bash
export HERMES_DIR="$HOME/.hermes/hermes-agent"
export HFC_CONFIG="$HOME/.hermes/config.yaml"
export HFC_ENV_FILE="$HOME/.hermes/.env"
curl -fsSL https://raw.githubusercontent.com/baileyh8/hermes-feishu-streaming-card/v5.0.4/install.sh | bash -s -- --version v5.0.4 --config "$HFC_CONFIG" --env-file "$HFC_ENV_FILE"
```

The readme closes with a warning that is easy to skim past: upgrading HFC and upgrading Hermes are two different things, and the Feishu slash update command is not the version upgrade command for this plugin. Windows, Docker and split HOME setups have their own full guide.

## A small dependency footprint with a large surface area to test

The plugin is a narrow package in dependency terms and a wide one in behaviour, and that combination sets the risk.

On dependencies it is small. aiohttp and PyYAML are the only runtime requirements, Python 3.9 is the floor, and the code lives in the hermes_feishu_card package with a pyproject.toml that uses setuptools as the build backend. The repository has a tests directory, a pytest configuration with asyncio in auto mode, a CHANGELOG, a PROJECT_LOG, a TODO, an AGENTS.md, a config.yaml.example, docker-compose example and smoke files, install scripts for Docker and for the two platforms, a legacy directory and a tools directory.

On behaviour it is the opposite. The card has to render a live task, survive a Hermes version change, show a refusal differently from a timeout, withdraw expired buttons, keep a continuation reachable, and report token usage that Hermes actually provided. The readme documents the notice lifecycle, a Feishu acceptance checklist, a maintenance guide, a notification lifecycle page and a source-of-truth note on the visuals, and it explains that the interface screenshots were taken from real acceptance runs with avatars, names and identity references removed by a generative tool, with the originals kept as evidence.

Two details in the release notes give a sense of the churn. v5.0.4 adds an optional output rate for eligible legacy installations, fixes completion card cleanup after verified Session Authority delivery across a task, and connects precise preflight and compression completion messages to a 15 second withdrawal, with generation rate off by default and unknown source code keeping the native Hermes delivery. v5.0.1 supports the inherited completion and approval renderer hooks of Hermes 0.22.x, with pinned source regression coverage.

The readme is honest that the cover image is AI generated promotional visual rather than a product screenshot, and that the actual flow is a task streaming updates, then a wait for your choice, then the recorded action, then continued output, then the full result with the turn statistics. For a plugin whose value is entirely in how a card looks and behaves, that distinction between the marketing image and the acceptance screenshots is the one to keep in mind.

## Conclusion

Adopt the Hermes Feishu streaming card plugin if you already run a Hermes Agent behind a Feishu or Lark bot and your users are tired of plain text replies, especially where approvals and clarifications need buttons. Do not adopt it as a standalone agent platform, because the model, the tools and the tasks still belong to Hermes and the plugin does not change authorisation decisions, and do not adopt it if you are not on Feishu, since the card format is the integration point. Before you upgrade from v4 to v5, back up your config and .env, pin the version with the install script, and run status, doctor --explain and card-config --running once the gateway is back up.

## FAQ

### What does the Hermes Feishu streaming card plugin do?

It turns the Feishu or Lark replies of the Hermes Agent Gateway into continuously updated interactive cards, with task sections, approval and choice buttons, continuation cards, expiry states and per turn statistics. Models, tools and tasks are still executed by Hermes, and the plugin handles card display, interaction and delivery.

### How do I install the Hermes Feishu streaming card plugin?

On macOS or Linux run the install script with curl piped to bash, and on Windows use the PowerShell equivalent. The script resolves the latest stable release, installs into the Hermes environment, writes credentials to a local .env, and completes configuration, hook installation and sidecar startup.

### How do I switch on the v5 task layout?

Merge reading_preset: task and timeline_expanded: false into the global card section of your existing config and restart the sidecar, without overwriting the whole file. The task preset defaults to expanded, so the second line is what chooses to collapse the process, and profile or bot values can still override the global setting.

### What should I check after upgrading from v4.x to v5?

Back up your config, .env and installer recovery data first, stop the Gateway, Desktop and sidecar with your existing service manager, then install the pinned version with the install script. After restarting, run status, doctor --explain and card-config --running, and send the bot a message to confirm the card and footer.

### Does the plugin change what the agent is allowed to do?

No. The readme states that Hermes continues to handle model and tool execution and that the plugin does not change authorisation decisions. The card takes over messages explicitly and reduces repeated native text, while attachments and paths where delivery cannot be confirmed keep a necessary fallback.

## Sources

- [baileyh8/hermes-feishu-streaming-card on GitHub](https://github.com/baileyh8/hermes-feishu-streaming-card)
- [Issues](https://github.com/baileyh8/hermes-feishu-streaming-card/issues)
- [License: MIT](https://github.com/baileyh8/hermes-feishu-streaming-card/blob/main/LICENSE)
- [README](https://github.com/baileyh8/hermes-feishu-streaming-card/blob/main/README.md)
- [Releases](https://github.com/baileyh8/hermes-feishu-streaming-card/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/baileyh8-hermes-feishu-streaming-card