mirror of
https://github.com/nesquena/hermes-webui.git
synced 2026-06-02 07:00:43 +00:00
nesquena-hermes
81 lines
3.2 KiB
Markdown
81 lines
3.2 KiB
Markdown
# Agent instructions for Hermes WebUI
|
|
|
|
This file is the shared entry point for AI assistants working in this
|
|
repository. Keep it project-specific and safe to publish. Do not put personal
|
|
machine setup, private network details, credentials, tokens, or local-only
|
|
workflow notes here.
|
|
|
|
## Read first
|
|
|
|
Before making changes, read:
|
|
|
|
1. `README.md`
|
|
2. `CONTRIBUTING.md`
|
|
3. `docs/CONTRACTS.md`
|
|
4. `CHANGELOG.md`
|
|
|
|
For architecture, testing, or setup work, also read the matching reference:
|
|
|
|
- `ARCHITECTURE.md` for design constraints and current module layout
|
|
- `TESTING.md` for local verification commands and manual test guidance
|
|
- `docs/onboarding.md` for first-run onboarding behavior
|
|
- `docs/troubleshooting.md` for diagnostic flows
|
|
- `docs/rfcs/README.md` for larger RFCs and state/durability contracts
|
|
|
|
For UI or UX work, read `docs/UIUX-GUIDE.md` and `DESIGN.md` before
|
|
changing layout, interaction flow, themes, chat rendering, or composer chrome.
|
|
|
|
## Onboarding and reinstall support
|
|
|
|
If the task involves install, reinstall, bootstrap, first-run onboarding,
|
|
provider setup, local model server setup, Docker onboarding, WSL onboarding, or
|
|
support for a failed first run, read `docs/onboarding-agent-checklist.md`
|
|
before running commands or inspecting logs.
|
|
|
|
Follow that checklist's safety rules:
|
|
|
|
- use isolated `HERMES_HOME` and `HERMES_WEBUI_STATE_DIR` for trials unless the
|
|
human explicitly asks to use real state
|
|
- do not delete or overwrite a real `~/.hermes` directory without explicit
|
|
approval
|
|
- do not print API keys, OAuth tokens, cookies, full `.env` files, full
|
|
`auth.json` files, or password hashes
|
|
- collect non-secret status and log evidence before recommending a fix
|
|
|
|
## Contribution style
|
|
|
|
- Keep one logical change per PR; split unrelated refactors or cleanup.
|
|
- Read `docs/CONTRACTS.md` and the linked contract/RFC for the touched
|
|
subsystem before editing.
|
|
- Prefer the existing Python + vanilla JavaScript structure. Do not add
|
|
dependencies, build tools, frameworks, or long-lived processes without clear
|
|
justification and a rollback story.
|
|
- Update docs when changing setup, onboarding, runtime behavior, architecture,
|
|
testing guidance, or user-facing workflows.
|
|
- Update `CHANGELOG.md` for user-visible behavior, setup, workflow, or
|
|
documentation changes that should be release-note ready.
|
|
- For UI or UX changes, include before/after evidence and test relevant
|
|
desktop, narrow, and mobile states.
|
|
- For behavior changes, add or update automated tests where practical and list
|
|
the manual verification performed.
|
|
- For runtime, streaming, recovery, replay, compression, or sidebar metadata
|
|
changes, name the state layer being mutated and prove the relevant invariant.
|
|
|
|
## Local state and secrets
|
|
|
|
Hermes WebUI can read and write real agent state, sessions, workspaces,
|
|
credentials, and cron data. Treat local validation as potentially destructive
|
|
unless you have confirmed the active state directories.
|
|
|
|
Prefer isolated trial state for experiments:
|
|
|
|
```bash
|
|
HERMES_HOME=/tmp/hermes-webui-agent-home \
|
|
HERMES_WEBUI_STATE_DIR=/tmp/hermes-webui-agent-state \
|
|
HERMES_WEBUI_PORT=8789 \
|
|
python3 bootstrap.py
|
|
```
|
|
|
|
Do not include private machine instructions in this tracked file. Use a
|
|
git-ignored local note for personal workflow details.
|