hermes-webui AGENTS.md

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.
• For local pytest runs, use ./scripts/test.sh instead of bare python3, python -m pytest, or pytest. The script creates/uses the repo .venv, pins execution to Python 3.11-3.13, and installs missing dev test dependencies. HERMES_WEBUI_TEST_PYTHON selects the supported base interpreter used to create or rebuild .venv; it must not install test dependencies into a system/Homebrew interpreter directly. If a direct pytest invocation reports an unsupported interpreter, rerun through ./scripts/test.sh before debugging product code.
• 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.
• Do not edit CHANGELOG.md in ordinary contributor PRs. The release workflow owns changelog updates through release commits. If a change is release-note worthy, include concise release-note wording in the PR body instead.
• 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.
• For Docker build changes in docker_init.bash, mirror directory exclusions in both the rsync and cp -a paths — /opt/hermes may contain subdirectories with restricted permissions (e.g. .playwright/).