hermes-agent
Manage 0xRay framework from Hermes Agent via the native xray-hermes plugin. Covers the 4 plugin tools (validate, codex_check, health, hooks), lifecycle hooks, slash commands, bridge architecture, and CLI fallback.
- License 许可
- MIT
- 所属仓库
- 0xRayAI/xray
- 最近更新
- 2026-11-13
- Stars
- ★ 2
- Forks
- 3
01 前言 Front Matter
- name
- hermes-agent
- author
- 0xRay AI
- version
- 2.1.0
- metadata
- { "hermes": { "tags": [ "0xRay", "Plugin", "Validation", "Codex", "GitHooks", "Bridge" ], "related_skills": [] } }
- description
- Manage 0xRay framework from Hermes Agent via the native xray-hermes plugin. Covers the 4 plugin tools (validate, codex_check, health, hooks), lifecycle hooks, slash commands, bridge architecture, and CLI fallback.
03 SKILL.md 正文
0xRay Hermes Plugin (xray-hermes)
Native Hermes plugin providing 0xRay framework integration — quality gates, codex enforcement, git hooks, and full pre/post processing pipeline. Runs via a Node.js bridge to compiled framework components.
When to Use
- User asks about 0xRay health, validation, or codex checks
- User wants to install/manage git hooks for automated enforcement
- User asks about the plugin's tools, hooks, or slash commands
- User asks about bridge errors or framework not loading
- User wants to validate files before committing or pushing
Plugin Architecture
~/.hermes/plugins/xray-hermes/
├── __init__.py # Plugin registration, hooks, slash commands
├── tools.py # 4 tool handlers (validate, codex_check, health, hooks)
├── schemas.py # JSON schemas the LLM sees
├── bridge.mjs # Node.js bridge to compiled 0xRay framework
├── plugin.yaml # Plugin metadata (name, version, tools, hooks)
├── types.py # TypeScript-equivalent type definitions
├── after-install.md # Post-install instructions
└── test_plugin.py # Tests
Bridge protocol: JSON over stdin/stdout to bridge.mjs (Node.js). The bridge lazy-loads compiled framework modules from dist/:
dist/plugin/quality-gate.js— codex violation detectiondist/processors/processor-manager.js— pre/post processor pipelinedist/state/state-manager.js— persistent statedist/core/features-config.js— feature flags
Fallback: When bridge is unavailable, tools fall back to npx 0xray CLI commands.
Config path resolution: XRAY_CONFIG_DIR/ > .xray/ > built-in defaults.
4 Tools
xray_validate
Run pre-commit validation on files. Uses bridge quality gate + processor pipeline, falls back to CLI.
xray_validate(files=["src/my-module.ts"], operation="commit")
xray_validate(files=["src/auth.ts", "src/auth.test.ts"], operation="modify")
Parameters:
files(required, array of strings) — file paths to validateoperation(string) — commit, create, modify, refactor (default: commit)
Returns: pass/fail with per-file results and violations.
xray_codex_check
Validate code against the 69-term Universal Development Codex. Checks error-handling, type-safety, performance, security, architecture.
xray_codex_check(code="const x: any = foo()", operation="create")
xray_codex_check(code=snippet, operation="modify", focus_areas=["security", "error-handling"])
Parameters:
code(string) — code snippet to check. If omitted, returns framework health instead.operation(required, string) — create, modify, refactorfocus_areas(array) — error-handling, type-safety, performance, security, architecture
Returns: violations list with actionable remediation.
xray_health
Framework health check. Returns version, loaded components, project root.
xray_health()
Returns: framework status, version, component availability, node version.
xray_hooks
Manage 0xRay git hooks (install, uninstall, list, status).
xray_hooks(action="install")
xray_hooks(action="status")
xray_hooks(action="list")
xray_hooks(action="uninstall", hooks=["pre-commit"])
Parameters:
action(required, string) — install, uninstall, list, statushooks(array) — which hooks to manage (default: all four)
Hooks available: pre-commit, post-commit, pre-push, post-push.
| Hook | Type | What it does |
|---|---|---|
pre-commit |
Blocking | TypeScript check + Codex validation before commit |
post-commit |
Non-blocking | Log archival + cleanup after commit |
pre-push |
Blocking | Full validation suite before push |
post-push |
Non-blocking | Comprehensive monitoring after push |
2 Lifecycle Hooks
These fire automatically — no action needed from the user or agent.
pre_tool_call
Fires before ANY tool executes:
- Tracks session stats
- Logs tool-start event to
logs/framework/plugin-tool-events.log - For code-producing tools (write_file, patch, execute_code, write, edit): runs quality gate + pre-processors via bridge
- For other tools: nudges when a 0xRay MCP alternative exists (e.g., grep → search_codebase, eslint → xray_lint)
post_tool_call
Fires after ANY tool returns:
- Logs tool-complete event
- For code-producing tools: runs post-processors via bridge
on_session_start (graceful fallback)
Fires when a new session starts. Resets stats and logs to disk. Registration is wrapped in try/except for hosts that don't support it yet.
Slash Command
/xray status — Plugin and framework health (calls bridge)
/xray stats — Session pipeline statistics
/xray help — Show available commands
/sr status — Alias
Session Stats (tracked automatically)
The plugin tracks per-session counters visible via /xray stats:
- total_tool_calls, code_operations, xray_mcp_calls, native_tool_calls
- quality_gate_runs, quality_gate_blocks
- pre_processor_runs, post_processor_runs
- bridge_calls, bridge_errors
Logging
All logs go to logs/framework/ in the project root:
| File | Content |
|---|---|
activity.log |
All pipeline events (quality gates, processors, nudges, errors) |
plugin-tool-events.log |
Tool start/complete events with durations |
Quick Decision Guide
| User Says | Tool / Command |
|---|---|
| "Is 0xRay working?" | xray_health() or /xray status |
| "Check these files before I commit" | xray_validate(files=[...], operation="commit") |
| "Is this code codex compliant?" | xray_codex_check(code=..., operation="create") |
| "Set up git hooks" | xray_hooks(action="install") |
| "What hooks are installed?" | xray_hooks(action="status") |
| "Show session stats" | /xray stats |
| "Why is the bridge failing?" | Check xray_health() → if framework: "not_loaded", verify dist/ symlink |
Bridge Commands (internal)
These are called by the Python tools via bridge.mjs, not directly by the LLM:
| Command | What it does |
|---|---|
health |
Framework health check |
validate |
Run quality gate on files |
codex-check |
Check code against codex rules |
pre-process |
Quality gate + pre-processors before tool |
post-process |
Post-processors after tool |
hooks |
Git hook management |
stats |
Bridge/framework statistics |
Bridge can be invoked directly for debugging:
echo '{"command":"health"}' | node ~/.hermes/plugins/xray-hermes/bridge.mjs
node ~/.hermes/plugins/xray-hermes/bridge.mjs health --cwd /path/to/project
Relationship to MCP Servers
The plugin and MCP servers are complementary:
- Plugin tools = offline-first, always available, lightweight (validate, codex check, health, hooks)
- MCP servers = deeper analysis requiring running Node.js (lint, security scan, architecture assessment, orchestration, codebase search)
The plugin's pre_tool_call hook nudges when an MCP alternative exists (e.g., "use mcp_xray_lint_lint instead of raw eslint"). This is advisory, not blocking.
Pitfalls
- Plugin requires restart after install/edit: Hermes loads plugins once at session start.
- Bridge needs
dist/symlink: The bridge loads compiled.jsfromdist/→node_modules/0xray/dist/. If the symlink breaks, bridge returnsframework: "not_loaded". xray_codex_checkwithoutcodeparam returns health, not a codex check. Passcodefor actual validation.- CLI fallback requires
npx 0xrayin PATH. If bridge fails and CLI isn't available, tools return errors. - Quality gate blocks are logged but NOT enforced (advisory). The tool returns violations; the agent decides what to do.
- Git hooks use symlinks from
.git/hooks/→hooks/. If thehooks/directory doesn't exist in the project,xray_hooks(action="install")skips those hooks. - Project root detection walks up from CWD looking for
node_modules/0xray,.xray/features.json, orpackage.json. Override withXRAY_PROJECT_ROOTenv var. logs/framework/is created automatically. Never breaks the agent if permissions fail.
04 同仓库更多 Skills
xray-orchestrator
Main orchestration skill for xray agents. Provides commands to coordinate agent work and invoke xray APIs through the local HTTP API server.
ui-ux-design
User interface and user experience design with mobile-first approach, cognitive simplicity, and accessibility-first principles
testing-strategy
Design comprehensive testing strategies and optimize test coverage
testing-best-practices
Testing best practices and quality assurance
tech-writer
Documentation writer for API docs, READMEs, ADRs, changelogs, and developer experience
strategist
Strategic guidance and complex problem-solving with architectural decision-making and risk analysis