lhumina_code/hero_archive_claude

Archived

Fork 0

research specs #2

New issue

Open

opened 2026-04-04 10:25:40 +00:00 by despiegk · 2 comments

despiegk commented

2026-04-04 10:25:40 +00:00

Owner

research how this tool works
give me specs

how do we drive claude?
what API can we use

can we test this using openrpc

are there integration tests?

research how this tool works give me specs how do we drive claude? what API can we use can we test this using openrpc are there integration tests?

despiegk commented

2026-04-04 10:30:27 +00:00

Author

Owner

Research Spec for Issue #2 — hero_claude Architecture & Testing

1. Architecture Overview

hero_claude is a Rust workspace with 5 crates:

Crate	Type	Purpose
`hero_claude`	CLI binary	Registers server + UI with `hero_proc`; provides `--start`/`--stop`
`hero_claude_server`	Daemon	JSON-RPC 2.0 + MCP over Unix socket; orchestrates Docker containers running Claude Code
`hero_claude_sdk`	Library	Auto-generated typed Rust client from OpenRPC spec
`hero_claude_ui`	Daemon	Axum admin dashboard; proxies `/rpc` to server socket
`hero_claude_examples`	Examples	SDK usage examples and integration tests

Runtime topology:

hero_proc (supervisor)
  ├── hero_claude_server → ~/hero/var/sockets/hero_claude_server.sock
  │     POST /rpc, POST /mcp, GET /openrpc.json, GET /health
  └── hero_claude_ui → ~/hero/var/sockets/hero_claude_ui.sock
        GET / (dashboard), POST /rpc (proxied), GET /health

2. How Claude Is Driven

Claude is driven via Claude Code CLI (@anthropic-ai/claude-code) in headless mode inside Docker containers
The Anthropic HTTP API is NOT called directly — the CLI handles that
Docker image (Ubuntu 24.04) includes Rust, Node.js, and Claude Code CLI
Entrypoint script: claude --print --output-format=text "$SESSION_TASK"
Host's ~/.claude credentials are mounted read-only for Claude Max subscription

Session lifecycle:

session.create → CREATED → session.start → RUNNING → session.finish → COMPLETED
                                              ├── session.stop → STOPPED (resumable)
                                              └── session.destroy → DESTROYED

3. Available APIs

JSON-RPC 2.0 (16 methods at POST /rpc):

server.info, server.health
session.create, session.start, session.stop, session.finish, session.destroy
session.sync, session.list, session.info, session.logs, session.exec
repo.list, repo.info
logs.get, logs.clear

MCP at POST /mcp — same methods as MCP tools (protocol 2024-11-05)

Typed Rust SDK — auto-generated from OpenRPC spec via openrpc_client! macro

Full OpenRPC 1.3.2 spec served at GET /openrpc.json

4. Can We Test Using OpenRPC?

Yes. The system is fully OpenRPC-testable:

Machine-readable spec at /openrpc.json
SDK auto-generated from the spec
rpc.discover method returns the live spec
All communication is standard JSON-RPC 2.0 over Unix sockets
Can test with curl --unix-socket or any JSON-RPC client

5. Integration Tests

3 integration tests in crates/hero_claude_examples/tests/integration.rs:

test_server_health — starts service stack, calls server.health via SDK
test_rpc_discover — validates OpenRPC spec has non-empty methods
test_session_list — verifies session.list succeeds

0 unit tests currently exist.

Prerequisites: hero_proc running, binaries in ~/hero/bin/, CODEROOT/BUILDDIR env vars set.

6. Key Dependencies

hero_proc_sdk — process supervisor
hero_rpc_derive — openrpc_client! and openrpc_proxy! macros
hero_rpc_openrpc — OpenRPC Unix socket transport
axum + hyper_util — HTTP over Unix sockets
tokio — async runtime

## Research Spec for Issue #2 — hero_claude Architecture & Testing ### 1. Architecture Overview hero_claude is a Rust workspace with 5 crates: | Crate | Type | Purpose | |---|---|---| | `hero_claude` | CLI binary | Registers server + UI with `hero_proc`; provides `--start`/`--stop` | | `hero_claude_server` | Daemon | JSON-RPC 2.0 + MCP over Unix socket; orchestrates Docker containers running Claude Code | | `hero_claude_sdk` | Library | Auto-generated typed Rust client from OpenRPC spec | | `hero_claude_ui` | Daemon | Axum admin dashboard; proxies `/rpc` to server socket | | `hero_claude_examples` | Examples | SDK usage examples and integration tests | **Runtime topology:** ``` hero_proc (supervisor) ├── hero_claude_server → ~/hero/var/sockets/hero_claude_server.sock │ POST /rpc, POST /mcp, GET /openrpc.json, GET /health └── hero_claude_ui → ~/hero/var/sockets/hero_claude_ui.sock GET / (dashboard), POST /rpc (proxied), GET /health ``` ### 2. How Claude Is Driven - Claude is driven via **Claude Code CLI** (`@anthropic-ai/claude-code`) in headless mode inside Docker containers - The Anthropic HTTP API is NOT called directly — the CLI handles that - Docker image (Ubuntu 24.04) includes Rust, Node.js, and Claude Code CLI - Entrypoint script: `claude --print --output-format=text "$SESSION_TASK"` - Host's `~/.claude` credentials are mounted read-only for Claude Max subscription **Session lifecycle:** ``` session.create → CREATED → session.start → RUNNING → session.finish → COMPLETED ├── session.stop → STOPPED (resumable) └── session.destroy → DESTROYED ``` ### 3. Available APIs **JSON-RPC 2.0** (16 methods at `POST /rpc`): - `server.info`, `server.health` - `session.create`, `session.start`, `session.stop`, `session.finish`, `session.destroy` - `session.sync`, `session.list`, `session.info`, `session.logs`, `session.exec` - `repo.list`, `repo.info` - `logs.get`, `logs.clear` **MCP** at `POST /mcp` — same methods as MCP tools (protocol 2024-11-05) **Typed Rust SDK** — auto-generated from OpenRPC spec via `openrpc_client!` macro Full OpenRPC 1.3.2 spec served at `GET /openrpc.json` ### 4. Can We Test Using OpenRPC? **Yes.** The system is fully OpenRPC-testable: 1. Machine-readable spec at `/openrpc.json` 2. SDK auto-generated from the spec 3. `rpc.discover` method returns the live spec 4. All communication is standard JSON-RPC 2.0 over Unix sockets 5. Can test with `curl --unix-socket` or any JSON-RPC client ### 5. Integration Tests **3 integration tests** in `crates/hero_claude_examples/tests/integration.rs`: - `test_server_health` — starts service stack, calls `server.health` via SDK - `test_rpc_discover` — validates OpenRPC spec has non-empty methods - `test_session_list` — verifies `session.list` succeeds **0 unit tests** currently exist. **Prerequisites:** `hero_proc` running, binaries in `~/hero/bin/`, `CODEROOT`/`BUILDDIR` env vars set. ### 6. Key Dependencies - `hero_proc_sdk` — process supervisor - `hero_rpc_derive` — `openrpc_client!` and `openrpc_proxy!` macros - `hero_rpc_openrpc` — OpenRPC Unix socket transport - `axum` + `hyper_util` — HTTP over Unix sockets - `tokio` — async runtime

despiegk commented

2026-04-04 19:24:12 +00:00

Author

Owner

Implementation Summary

Changes Made

Created docs/ARCHITECTURE.md — comprehensive architecture and API reference document

What It Covers

How hero_claude works (Claude Code CLI in Docker containers, session lifecycle)
All available APIs (JSON-RPC 2.0 with 16 methods, MCP endpoint, typed Rust SDK)
OpenRPC testing approach (machine-readable spec, SDK-based testing, curl examples)
Integration test inventory (3 tests in hero_claude_examples, no unit tests yet)
Key dependencies and Docker image details

Files

docs/ARCHITECTURE.md (new)

## Implementation Summary ### Changes Made - Created `docs/ARCHITECTURE.md` — comprehensive architecture and API reference document ### What It Covers - How hero_claude works (Claude Code CLI in Docker containers, session lifecycle) - All available APIs (JSON-RPC 2.0 with 16 methods, MCP endpoint, typed Rust SDK) - OpenRPC testing approach (machine-readable spec, SDK-based testing, curl examples) - Integration test inventory (3 tests in hero_claude_examples, no unit tests yet) - Key dependencies and Docker image details ### Files - `docs/ARCHITECTURE.md` (new)

Commenting is not possible because the repository is archived.