hermes-agent-rs: Instructions file for Codex

Hermes Agent (Rust) — Development Guide

Instructions for AI coding assistants and developers working on the hermes-agent-rust codebase.

Parity status: 13/13 scoped items completed. See README.md for the full tracker.

---

Build & Test

cargo build --release                    # Binary at target/release/hermes
cargo test --workspace                   # 1,428 tests, all crates
cargo test -p hermes-parity-tests        # Parity fixture tests only
cargo clippy --workspace --all-targets   # Lint (target: -D warnings)
cargo fmt --all --check                  # Format check

# Eval framework with real agent loop
cargo build -p hermes-eval --features agent-loop

Artifact 锁：Blocking waiting for file lock on artifact directory

终端里 cargo run 与编辑器里的 rust-analyzer（cargo check）会争用同一 target/ artifact 锁，表现为长时间阻塞。

仓库内缓解（已提交）：

1. .vscode/settings.json："rust-analyzer.cargo.targetDir": true —— 让 rust-analyzer 使用 target 下独立子目录做检查，与命令行 cargo build / cargo run 分离（改完后请重载窗口 / 重启 rust-analyzer）。
2. scripts/hermes：若已存在 target/debug/hermes，则直接执行该二进制，避免每次 cargo run 抢锁；需要强制走 cargo 时：HERMES_USE_CARGO=1 ./scripts/hermes …。首次可 chmod +x scripts/hermes，或始终 sh scripts/hermes …。

若仍卡住：确认没有其它终端在长时间 cargo build，必要时结束残留 cargo 进程后再试。

---

Project Structure

hermes-agent-rust/
├── Cargo.toml                # Workspace root — 16 crates, pinned deps
├── AGENTS.md                 # This file (loaded by Hermes at runtime)
├── PARITY_PLAN.md            # 8-week parity roadmap
├── Dockerfile                # Multi-stage release build
├── scripts/
│   ├── hermes                # 优先 target/debug/hermes，减轻与 RA 的 artifact 锁竞争
│   └── record_fixtures.py    # Fixture recording script
└── crates/
    ├── hermes-core/          # Shared types, traits, error hierarchy
    ├── hermes-agent/         # Agent loop, LLM providers, memory plugins, context
    ├── hermes-tools/         # Tool registry, dispatch, 30 tool backends
    ├── hermes-gateway/       # Message gateway, 17 platform adapters
    ├── hermes-cli/           # CLI/TUI binary, slash commands, app state
    ├── hermes-config/        # Config loading, YAML/JSON/env merging, validation
    ├── hermes-intelligence/  # Smart routing, prompt builder, usage pricing, display
    ├── hermes-skills/        # Skill management, file store, hub client, versioning
    ├── hermes-environments/  # Terminal backends (Local/Docker/SSH/Daytona/Modal/Singularity)
    ├── hermes-cron/          # Cron scheduling and persistence
    ├── hermes-mcp/           # Model Context Protocol client/server
    ├── hermes-acp/           # Agent Communication Protocol
    ├── hermes-eval/          # Evaluation framework (Runner, BenchmarkAdapter, Verifier)
    ├── hermes-server/        # HTTP/WebSocket API server
    ├── hermes-telemetry/     # OpenTelemetry + Prometheus metrics
    └── hermes-parity-tests/  # Golden fixture tests for behavioral parity