HeroClaude - Session Manager

Server

Quick Actions

Loading sessions...

Create New Session

Session Name (optional)

Task Description

Select Repositories

Loading repos...

Docker Image

CPU Cores

Memory (GB)

MCP Servers

filesystem

browser

heroindex

hero_embedder

Start session immediately after creation

Loading repositories...

Operation Logs

Loading logs...

Loading configuration...

API Documentation

JSON-RPC 2.0 endpoint: POST /rpc

server.info

Get server configuration and status.

{"jsonrpc":"2.0","id":1,"method":"server.info","params":[]}

server.health

Health check. Returns true if server is running.

{"jsonrpc":"2.0","id":1,"method":"server.health","params":[]}

session.create

Create a new session. Rsyncs repos and creates feature branches.

Params: repos (string[]), task (string), name? (string), image? (string), cpu? (int), memory_gb? (int), mcp_servers? (string[])

{"jsonrpc":"2.0","id":1,"method":"session.create","params":{"repos":["hero_lib"],"task":"Fix auth bug"}}

session.start

Start a created/stopped session (launches Docker container).

{"jsonrpc":"2.0","id":1,"method":"session.start","params":{"session_id":"a1b2c3d4"}}

session.stop

Stop a running session (preserves state).

session.finish

Commit changes, push branches, create pull requests.

session.destroy

Remove session container and all data from disk.

session.sync

Re-sync repos from CODEROOT into session sandbox.

session.list

List all sessions, optionally filtered by status.

session.info

Get detailed session information with live resource usage.

session.logs

Get session logs (rsync, claude, container).

session.exec

Execute a command inside a running session container.

repo.list

List available repositories in CODEROOT.

repo.info

Get detailed repository info (branch, size, last commit).

logs.get

Get aggregated operation logs.

logs.clear

Clear all operation logs.

HeroClaude Overview

HeroClaude is an ACP orchestration layer that manages multiple Claude Code sessions in isolated Docker containers.

It provides session management, repository scanning, code synchronization, and an MCP (Model Context Protocol) interface for AI assistants.

Environment Variables

Variable	Required	Description	Default
`CODEROOT`	Yes	Absolute path to directory containing all source repositories (must have `.git` folders)	`.`
`BUILDDIR`	Yes	Directory for build artifacts and session workspaces. Auto-created if missing.	`./build`
`HERO_CLAUDE_HOST`	No	Server binding address	`127.0.0.1`
`HERO_CLAUDE_PORT`	No	Server port number	`3780`
`HERO_CLAUDE_IMAGE`	No	Docker image for session sandboxes	`hero-claude-sandbox:latest`
`DOCKER_RUNTIME`	No	Docker command/runtime to use	`docker`
`CLAUDE_CONFIG_DIR`	No	Claude configuration directory path	`~/.claude`
`HERO_SECRET`	No	JWT authentication secret. Leave unset to disable authentication.	None
`RUST_LOG`	No	Logging level (trace, debug, info, warn, error)	`info`

Configuration Methods

1. Environment Variables

Set variables directly in shell:

export CODEROOT=/Volumes/RUST/code4
export BUILDDIR=./build
export HERO_CLAUDE_PORT=3780
cargo run --release

2. .env File

Create .env file in project root:

CODEROOT=/path/to/repos
BUILDDIR=./build
HERO_CLAUDE_PORT=3780

3. Via Makefile (Recommended)

Uses buildenv.sh automatically:

make run    # Release build
make rundev # Debug with logging

4. Build Configuration

Edit buildenv.sh for defaults:

export CODEROOT="${CODEROOT:-.}"
export BUILDDIR="${BUILDDIR:-./build}"

Quick Start

Copy configuration template:
```
cp .env.example .env
```

Edit .env with your paths:

CODEROOT=/Volumes/RUST/code4  # Your repos directory
BUILDDIR=./build              # Build workspace

Build and run:
```
make build
make run
```
Access web UI:
Open http://127.0.0.1:3780 in your browser

API Endpoints

Web Interface

GET / – Session manager UI

JSON-RPC API

POST /rpc – JSON-RPC 2.0 API

OpenRPC Schema

GET /openrpc.json – API specification

MCP Integration

POST /mcp – Model Context Protocol

Directory Structure

CODEROOT/                    # Your code directory
├── repo1/                   # Repository with .git
│   ├── .git/
│   └── ...
├── repo2/
│   ├── .git/
│   └── ...
└── ...

BUILDDIR/                    # Build and session workspace
├── sessions/               # Session workspaces
│   ├── session_id_1/
│   ├── session_id_2/
│   └── ...
└── logs/                   # Session logs

Key Concepts

Sessions

Isolated Docker containers where Claude Code instances run. Each session has its own workspace with synced repositories.

Repositories

Git repositories in CODEROOT are discovered automatically and can be synced into sessions via rsync.

Synchronization

Uses rsync to efficiently copy repositories from CODEROOT into session containers, excluding build artifacts and caches.

Status Management

Sessions have states: created → running → stopped → completed/destroyed

MCP Integration

HeroClaude exposes a Model Context Protocol (MCP) interface, allowing Claude Code to manage sessions remotely.

Add to Claude Code:

claude mcp add --transport http hero-claude http://localhost:3780/mcp

See the MCP tab for available tools and connection details.

Authentication

Without HERO_SECRET: API is publicly accessible (no authentication required)

With HERO_SECRET: All RPC calls require JWT authentication via Authorization header

Authorization: Bearer <jwt-token>

Set HERO_SECRET environment variable to enable authentication.

Troubleshooting

Failed to read CODEROOT: No such file or directory

Solution: Set CODEROOT to a valid directory path. The directory will be created automatically if it doesn't exist.

export CODEROOT=/Volumes/RUST/code4

Port already in use

Solution: Change HERO_CLAUDE_PORT or kill process using the port.

lsof -ti:3780 | xargs kill -9
make run --port 3781

No repositories found in CODEROOT

Solution: Ensure CODEROOT contains directories with .git folders.

ls -la $CODEROOT/*/.

Enable debug logging

Command: Set RUST_LOG environment variable.

RUST_LOG=debug make rundev

MCP Integration

Connect AI assistants (Claude, etc.) to HeroClaude via the Model Context Protocol (MCP).

Connection Details

MCP Endpoint	`loading...`
Protocol	JSON-RPC 2.0 over HTTP
Authentication	None (Public)

Claude Code Setup

Add HeroClaude as an MCP server in Claude Code:

loading...

Available MCP Tools

Tool	Description	Category
`session_create`	Create a new cloud session	Session
`session_start`	Start a session	Session
`session_stop`	Stop a session	Session
`session_finish`	Commit and create PR	Session
`session_destroy`	Destroy a session	Session
`session_list`	List sessions	Session
`session_info`	Session details	Session
`session_logs`	Session logs	Session
`session_sync`	Re-sync repos	Session
`session_exec`	Run command in container	Session
`repo_list`	List available repos	Repo
`repo_info`	Repo details	Repo
`server_info`	Server info	Server
`server_health`	Health check	Server
`logs_get`	Get operation logs	Server

Create New Session

API Documentation

Server 2

Session 10

Repository 2

Logs 2

HeroClaude Overview

Environment Variables

Configuration Methods

1. Environment Variables

2. .env File

3. Via Makefile (Recommended)

4. Build Configuration

Quick Start

API Endpoints

Web Interface

JSON-RPC API

OpenRPC Schema

MCP Integration

Directory Structure

Key Concepts

Sessions

Repositories

Synchronization

Status Management

MCP Integration

Authentication

Troubleshooting

Failed to read CODEROOT: No such file or directory

Port already in use

No repositories found in CODEROOT

Enable debug logging

MCP Integration

Connection Details

Claude Code Setup

Available MCP Tools