Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
311 lines (222 loc) · 9.43 KB

CONTRIBUTING.md

File metadata and controls

311 lines (222 loc) · 9.43 KB
Raw

Contributing to HermesShell

Thank you for your interest in contributing. HermesShell is a community-maintained implementation of Hermes Agent (NousResearch) running inside NVIDIA OpenShell, and we want it to be a reliable reference for anyone who wants to run a sandboxed Hermes agent.

Table of Contents

What we're building

HermesShell has three layers:

  1. OpenShell integration — policy YAML files, profile, and the hermesshell CLI that wraps openshell commands
  2. Hermes configuration — hermes.yaml.example, persona.yaml.example, Dockerfile, docker-compose
  3. Documentation — feature reference, comparison table, test results

The most valuable contributions are in this order:

  • Correctness fixes — wrong OpenShell policy schema, wrong CLI flags, broken commands
  • Real-world testing — if you've run HermesShell on actual NVIDIA hardware, test reports are gold
  • New policy presets — for specific use cases (homeassistant, coding, research, etc.)
  • New platform policies — Slack, WhatsApp, Signal network rules
  • Docs improvements — anything that makes setup easier for a new user

Ways to contribute

Report a bug

Use the Bug Report issue template. Include:

  • Output of hermesshell doctor
  • Whether you're on OpenShell or Docker mode
  • OS and OpenShell version

Request a feature

Use the Feature Request template. The most welcome requests:

  • Additional policy presets for specific use cases
  • New platform integrations in the gateway policy
  • Missing OpenShell CLI features in the hermesshell wrapper
  • Hermes configuration improvements

Fix a bug or improve docs

Small fixes (typos, broken links, wrong commands) → open a PR directly.

Larger changes → open an issue first to discuss the approach.

Improve OpenShell policy correctness

If you work at NVIDIA or have access to OpenShell internals, correctness fixes to the policy YAML schema are extremely valuable. The schema in openshell/hermesshell-policy.yaml is our best effort from the public docs — if anything is wrong, please send a PR.

Development setup

Prerequisites

  • Docker Desktop or Docker Engine
  • Node.js >= 20 (install via nvm or your package manager)
  • bash 4+ (macOS: brew install bash)
  • git
  • Optional: NVIDIA GPU + OpenShell for full sandbox testing

Clone and verify

git clone https://github.com/ppritcha/hermesshell
cd hermesshell

# Build and test the CLI
cd cli && npm install && npm test && cd ..

# Run diagnostics (no model needed)
hermesshell doctor --quick

CLI tests should pass. Doctor may show WARN entries if OpenShell or an inference provider aren't installed yet.

Validate YAML files

# Requires: pip install pyyaml
python3 -c "
import yaml, sys, glob
for f in glob.glob('**/*.yaml', recursive=True):
    try:
        yaml.safe_load(open(f))
        print(f'OK  {f}')
    except yaml.YAMLError as e:
        print(f'ERR {f}: {e}')
        sys.exit(1)
"

Lint shell scripts

# Requires: brew install shellcheck (macOS) or apt-get install shellcheck (Linux)
shellcheck scripts/install.sh

Test Docker build

# Build the hermesshell container image
docker build -t hermesshell:latest .

# Verify Hermes is installed inside
docker run --rm hermesshell:latest hermes version

# Full compose test (CPU mode)
cp .env.example .env
docker compose up -d
docker exec hermesshell hermes status
docker compose down

Making changes

Branch naming

fix/policy-yaml-schema-v2
feat/homeassistant-policy-preset
docs/inference-routing-guide
test/live-gateway-test

Format: <type>/<short-description> using kebab-case.

Types: fix, feat, docs, test, ci, refactor, chore

Commit messages

Follow Conventional Commits:

fix(policy): correct Landlock compatibility field to best_effort
feat(preset): add homeassistant policy preset
docs(features): document voice note transcription for Discord
test(doctor): add jq fallback for JSON parsing
ci: add shellcheck to GitHub Actions

Format: <type>(<scope>): <description in imperative mood>

  • Use present tense: "add", "fix", "update" — not "added", "fixed", "updated"
  • Keep subject under 72 characters
  • Add a body if the change is non-obvious

One concern per PR

A PR that fixes a policy YAML schema issue should only fix that. A PR that adds a new preset should only add that preset and its documentation. Mixing unrelated changes makes review harder and slows merges.

Testing

Before every PR

Run both and make sure there are no new FAIL entries:

cd cli && npm test && cd ..
hermesshell doctor --quick

When changing policy YAML

Validate the schema:

python3 -c "
import yaml, sys, glob
for f in glob.glob('openshell/**/*.yaml', recursive=True):
    try:
        yaml.safe_load(open(f))
        print(f'OK  {f}')
    except yaml.YAMLError as e:
        print(f'ERR {f}: {e}')
        sys.exit(1)
"

When changing shell scripts

shellcheck scripts/install.sh

When changing CLI TypeScript

cd cli && npm test

When changing docker-compose.yml

docker compose config   # validates and prints resolved config
docker compose build    # builds the hermesshell image
docker compose up -d    # starts the stack
hermesshell doctor       # full check (no --quick)
docker compose down

If you have OpenShell

If you have NVIDIA hardware and OpenShell installed, run the full test:

hermesshell onboard
hermesshell doctor
hermesshell mybot chat "hello, verify you can respond"
hermesshell mybot policy add github
hermesshell mybot stop

Include your hermesshell doctor output in the PR body.

Pull request process

  1. Fork the repo and create a branch from main
  2. Make your changes — one concern per PR
  3. Run the tests — cd cli && npm test and hermesshell doctor --quick
  4. Lint your scripts — shellcheck on any modified .sh files
  5. Validate any YAML — python3 -c "import yaml; yaml.safe_load(open('your-file.yaml'))"
  6. Update docs if your change adds or removes a feature — update docs/features.md
  7. Open the PR using the PR template — fill in all sections
  8. One approval required before merge (from a maintainer or trusted contributor)

PR checklist (enforced by template)

  • hermesshell doctor --quick passes with no new FAIL entries
  • cd cli && npm test passes
  • shellcheck passes on any modified shell scripts
  • All modified YAML files parse without errors
  • CHANGELOG.md updated under [Unreleased]

Code standards

Shell scripts

  • All scripts start with #!/usr/bin/env bash
  • All scripts use set -euo pipefail (except where specific checks need to fail silently — document why)
  • Variables are always quoted: "$VAR", not $VAR
  • Local variables declared with local inside functions
  • Color codes defined as named variables at the top, never inline
  • Error messages go to stderr: echo "..." >&2
  • No hardcoded paths that won't work across environments — use $SCRIPT_DIR patterns
  • No cat piped to grep — use grep file directly
  • No backticks — use $(...) for command substitution

YAML files

  • 2-space indentation throughout
  • Comments explain why, not what (the YAML already shows what)
  • Every file has a header comment with purpose, usage, and reference link
  • String values are quoted when they contain special characters
  • Lists always use - with a space, never inline [a, b, c] for multi-item lists

Documentation

  • Markdown only — no HTML except where GitHub doesn't render Markdown (e.g., centered images)
  • Code blocks always specify the language for syntax highlighting
  • CLI commands are always wrapped in code blocks
  • Links use relative paths for internal docs, absolute URLs for external
  • No duplicate information — if something is in docs/features.md, link to it from README.md rather than copying it

What we won't merge

  • Changes that weaken security without a documented justification — e.g., opening up the network policy without a clear use case
  • Dockerfile changes that add root execution — Hermes must run as an unprivileged user
  • Breaking changes to the hermesshell CLI without a deprecation path — existing users depend on hermesshell start/stop/status/connect
  • Secret sprawl — never add API keys, tokens, or credentials to any file that isn't in .gitignore
  • Untested changes — if you can't run hermesshell doctor --quick successfully, we can't merge
  • Large scope creep — HermesShell is specifically Hermes + OpenShell. We won't merge general-purpose Hermes improvements unrelated to the sandbox

Questions?

Open a Discussion for anything that isn't a bug report or feature request. This is the right place for:

  • "Is this the right approach for X?"
  • "Has anyone gotten Y working?"
  • "What's the roadmap for Z?"

Credit

All contributors are listed in CHANGELOG.md. Significant contributors may be added to a CONTRIBUTORS.md file.