⚡ HYPERCLAW-MAX ⚡

🚀 A Local-First Autonomous Company in a Box

One server. Persistent agents. Layered memory. Surgical operations.

Quick Start • Installation • Key Terms • Architecture • Documentation • Privacy

🎯 What Is This?

Not a chatbot. Not a repo mirror. Not a one-shot coding script.

A public-safe distro for running a private AI operator stack on infrastructure you control.

HyperClaw-Max turns base OpenClaw into a more opinionated operating model for serious operators:

persistent specialist agents instead of one overloaded generalist
layered memory instead of flat context
operational state for tasks, delegations, and watchdogs
install, validation, and packaging surfaces that can be used and contributed to by third parties

In plain language:

you install HyperClaw-Max on a Linux machine you control
you add your own model keys and optional connector values
you get a persistent multi-agent system that can keep structured state, validate its config, and grow through optional adapters without depending on any private deployment

This public repo is meant to be:

installable from zero
honest about what is shipped today
extensible through optional adapters
usable without access to any operator-specific repo or runtime

🗝️ Key Terms

OpenClaw: the open-source base framework that HyperClaw-Max builds upon
Public core: the installable, auditable, contribution-safe part of this repo
Pack: the agent set materialized into a target root, such as DOC, CODEX, PA, HK
Fabric: the stateful layer that tracks work, such as tasks, delegations, and watchdogs
Overlay: an optional extension layered on top of the public core, such as finance or legal
context-intel: the current shipped analysis and diagnostics slice of the broader memory story

👥 Who Is This For?

Builders: people who want a real public-core codebase to inspect, extend, and ship against
Operators: people who want a local-first agent stack they can run on infrastructure they control
Technical evaluators: reviewers who need install, validation, and packaging surfaces that can be audited end to end
Early adopters: teams or individuals who want a clean core first, then optional adapters and overlays as needed

✅ What You Get Today

Public Core Shipped In This Repo

installable Python package with real CLI entrypoints
default persistent pack: DOC, CODEX, PA, HK
hyperclaw-first-run bootstrap over a clean target root
hyperclaw-materialize-pack overlay renderer
public config template plus runtime validation
operational-fabric bootstrap for tasks, delegations, watchdogs, and validation
Stage 1 context-intel core
public-safe systemd templates
optional finance and legal overlays

Optional Adapters And Templates

Telegram connector template
HTTP hook template
Gmail watch and calendar push examples
gateway environment override template
adapter docs for overlays, connectors, and future packaging lanes

Not Shipped Yet

full connector automation
full voice / browser runtime
full Tier 2-Tier 5 runtime extraction
repo-intel adapter implementation
full gateway/runtime parity with the reference deployment

⚡ Quick Start

Two fast paths:

Path A runs directly from the source tree. Path B installs the package and uses the public CLI entrypoints the way a normal operator would.

Prerequisites for both paths:

Python 3.11+
git
bash
ripgrep

For the full host baseline and optional runtime dependencies, see Installation Today.

A. Fastest Path From A Repo Checkout

Best for:

contributors
reviewers
source-level evaluation

git clone https://github.com/alessiolidoz-hash/HyperClaw-Max.git
cd HyperClaw-Max

TARGET_ROOT=.hyperclaw-max-demo
PYTHONPATH=src python3 -m hyperclaw_max.doctor --repo .
PYTHONPATH=src python3 -m hyperclaw_max.privacy_check --repo .
PYTHONPATH=src python3 -m hyperclaw_max.first_run "$TARGET_ROOT"
PYTHONPATH=src python3 -m hyperclaw_max.runtime_validate "$TARGET_ROOT/config/openclaw.public.example.jsonc"
PYTHONPATH=src python3 -m hyperclaw_max.ops_fabric.cli summary --state-dir "$TARGET_ROOT/runtime/state"
PYTHONPATH=src python3 -m unittest discover -s tests -q

B. Installed CLI Path

Best for:

operators testing a clean install flow
users who want package entrypoints instead of PYTHONPATH=src

git clone https://github.com/alessiolidoz-hash/HyperClaw-Max.git
cd HyperClaw-Max

python3 -m venv .venv
. .venv/bin/activate
pip install .

TARGET_ROOT=.hyperclaw-max-demo
hyperclaw-doctor --repo .
hyperclaw-privacy-check --repo .
hyperclaw-first-run "$TARGET_ROOT"
hyperclaw-validate-config "$TARGET_ROOT/config/openclaw.public.example.jsonc"
hyperclaw-ops-fabric summary --state-dir "$TARGET_ROOT/runtime/state"

Optional Smoke Test

PYTHONPATH=src python3 -m hyperclaw_max.context_intel.pack "telegram inbound dedupe" --repo . --format human

Use this as a quick sanity check for the shipped context-intel surface. Example outputs live in examples/README.md and examples/outputs/context-pack.json.

What this proves:

the public core works from a source checkout
the same surfaces are exposed as installed CLI entrypoints
the repo passes privacy and validation checks
the public pack can be materialized on a clean target root

🛠️ Installation Today

This is the current honest install surface for an external user.

Prerequisites

Component	Baseline
Host	Linux VPS or local Linux host
CPU	ARM64 or x86_64, 8 vCPU recommended
RAM	16 GB recommended
Python	3.11+
Node	Optional: 20+ for broader gateway or adapter surfaces
Services	`systemd --user` if using gateway templates

Core packages:

apt install -y git ripgrep bash curl

Useful during setup:

apt install -y jq gh

1. Clone And Install

git clone https://github.com/alessiolidoz-hash/HyperClaw-Max.git
cd HyperClaw-Max

python3 -m venv .venv
. .venv/bin/activate
pip install .

2. Bootstrap A Clean Target Root

TARGET_ROOT=/opt/hyperclaw-max
hyperclaw-first-run "$TARGET_ROOT"

This writes:

config/openclaw.public.example.jsonc
runtime/state/*.json
workspace boot files for the core pack
pack metadata and materialized overlay state

3. Configure The Required Inputs

Edit:

"$TARGET_ROOT/config/openclaw.public.example.jsonc"

For a real runtime, provide your own values for:

OPENCLAW_GATEWAY_TOKEN
OPENAI_API_KEY

Optional but common:

ANTHROPIC_API_KEY if you keep the default fallback model
TELEGRAM_BOT_TOKEN and TELEGRAM_OWNER_CHAT_ID if enabling Telegram
OPENCLAW_HOOKS_TOKEN if enabling HTTP hooks
GMAIL_WATCH_TOPIC if enabling the Gmail watch example

Rules:

keep optional channels disabled until you are ready to configure them
inject your own keys and tokens after install
edit the provider section if you want a different model/provider mix than the shipped example

4. Validate The Public Core

hyperclaw-doctor --repo .
hyperclaw-privacy-check --repo .
hyperclaw-validate-config "$TARGET_ROOT/config/openclaw.public.example.jsonc"
hyperclaw-ops-fabric validate --state-dir "$TARGET_ROOT/runtime/state"
hyperclaw-ops-fabric summary --state-dir "$TARGET_ROOT/runtime/state"
python3 -m unittest discover -s tests -q

5. Add Optional Adapters When Needed

Examples:

hyperclaw-materialize-pack "$TARGET_ROOT" --force
hyperclaw-materialize-pack "$TARGET_ROOT" --include-optional finance
materialize finance or legal overlays
enable Telegram or HTTP hooks
wire systemd templates for the gateway surface

Useful docs:

Current scope: the public install surface is real for public core bootstrap, validation, and optional template wiring. Connector automation, voice lanes, and repo-intel packaging remain later adapter work.

🧠 Architecture

graph TB
    subgraph "User Interface"
        USER[User / Owner]
        TG[Telegram / Connectors]
    end

    subgraph "Orchestration Layer"
        DOC[DOC - Orchestrator]
    end

    subgraph "Specialist Agents"
        CODEX[CODEX - Code & Infra]
        PA[PA - Intake & Routing]
        HK[HK - Health & Maintenance]
        FIN[FINANCE - Optional]
        LEG[LEGAL - Optional]
    end

    subgraph "Operational Fabric"
        TASKS[Task Capture]
        DELEG[Delegation State]
        WATCH[Watchdogs]
        OBS[Observability]
    end

    subgraph "Memory Fabric"
        T1[Tier 1 - Fast Recall]
        T2[Tier 2 - Graph Relationships]
        T3[Tier 3 - Timeline Memory]
        T4[Tier 4 - Synthesis]
        T5[Tier 5 - Repo Intelligence]
    end

    USER --> TG --> DOC
    DOC --> CODEX & PA & HK & FIN & LEG
    CODEX & PA & HK --> TASKS & DELEG & WATCH & OBS
    TASKS & DELEG & WATCH & OBS --> T1 --> T2 --> T3 --> T4 --> T5

Layer Breakdown

Layer	Purpose	Today In This Repo
User Interface	Entry points	config and connector templates
Orchestration	Coordination	default `DOC` pack and workspace boots
Specialists	Execution	`DOC`, `CODEX`, `PA`, `HK` plus optional `FINANCE` / `LEGAL`
Operational Fabric	State and flow	task, delegation, watchdog state plus validation CLI
Memory Fabric	Knowledge surfaces	Stage 1 `context-intel` core and the broader 5-tier model docs

🦸 Core Capabilities

Persistent Specialist Pack

HyperClaw-Max does not assume one assistant does everything. The default pack is:

DOC for orchestration
CODEX for code and infrastructure
PA for intake and routing
HK for health and maintenance

Optional overlays today:

FINANCE
LEGAL

Layered Memory Fabric

The product model is a 5-tier memory system:

Tier 1 for fast recall
Tier 2 for graph relationships
Tier 3 for timeline memory
Tier 4 for synthesis
Tier 5 for repo intelligence and technical comparison

The public repo ships the Stage 1 context-intel core today as the first public slice of this memory story and documents the broader model for future extraction. See docs/MEMORY-FABRIC.md for the tier-by-tier breakdown.

Operational Fabric Base

This repo already ships a public operational base for:

task state
delegation state
watchdog state
validation and summary commands

That means the public distro is not just prompt-in / answer-out. It already has explicit state and control surfaces for work tracking.

Local-First Model Routing

The public config template assumes a simple provider path first:

one primary model
one fallback model
clear env-var based credentials

Local and hybrid routing are part of the architecture and proven operating model, but they are not required for a clean public-core install.

Surgical Repo Intelligence

The long-term goal is controlled self-improvement:

inspect upstream
compare local vs external
import only what helps

Today the public repo ships the context-intel core and the repo-intel seam, not the full adapter implementation.

🔌 Optional Connectors And Adapters

A clean install must work with none of these enabled.

Surface	Status	What You Provide
Telegram	template shipped	your bot token and owner chat ID
HTTP hooks	template shipped	your hook token and mappings
Gmail / Calendar	example seam	your provider credentials and account mapping
Finance / Legal overlays	shipped	explicit opt-in during pack materialization
Voice / browser lane	not shipped yet	future adapter packaging
Repo-intel adapter	not shipped yet	future adapter packaging

This is intentional:

core install first
optional adapters second
private overlay never required for public contribution

🆚 Why Not Just Use OpenClaw?

OpenClaw is the open-source base framework that HyperClaw-Max builds upon.

Feature	Stock OpenClaw	HyperClaw-Max
Agents	single or ad-hoc	persistent specialist pack
Memory	basic	layered model plus public `context-intel` core
Operations	minimal	public operational-fabric base
Install	DIY	bootstrap, validation, and pack materialization surface
Discipline	flexible	role-based pack and install boundaries

HyperClaw-Max is not a fork for its own sake. It productizes a more opinionated operating model on top of OpenClaw:

persistent roles
staged install
public-core boundary
optional adapters instead of hidden private assumptions

🧭 Remaining Extraction Gaps

These lanes are documented as part of the product direction, but are not yet shipped as full public adapters:

richer connector automation
broader local / hybrid routing
voice and browser services
repo-intel adapter packaging
broader memory backend extraction
richer observability and dispatch wrappers beyond the public base

📚 Documentation

Doc	What It Covers
install/ONBOARDING.md	staged setup path for the public core
docs/CLI.md	command reference and install surfaces
docs/BOUNDARIES.md	public core vs optional adapters vs private overlay
install/connectors/README.md	connector templates and required inputs
install/systemd/README.md	public-safe gateway service templates
install/overlay/README.md	pack materialization over a clean base install
examples/README.md	sample outputs and reviewer-facing examples
examples/quickstart/README.md	quickstart example outputs
CHANGELOG.md	notable repo changes over time
CITATION.cff	citation metadata for research or academic reuse
docs/ARCHITECTURE.md	detailed system design
docs/MEMORY-FABRIC.md	layered memory model
docs/OPERATIONAL-FABRIC.md	public task / delegation / watchdog base
docs/HOSTING-AND-DEPENDENCIES.md	host baseline and dependencies
docs/PRIVACY-AND-SECRETS.md	secrets handling and privacy rules
docs/BOUNDARY-AUDIT.md	public-safety gate and audit scope
docs/ROADMAP.md	current roadmap
docs/EXTRACTION-MAP.md	copy / rewrite / exclude extraction map
agents/PACK-MANIFEST.yaml	required and optional agent pack

🔒 Privacy And Boundary

This repo is intentionally split into three zones:

Public core: installable and open to contribution by anyone
Optional adapters: useful but not required for a clean install
Private overlay: secrets, live state, personal data, and operator-specific doctrine

What is never shipped here:

real API keys or bot tokens
live sessions or copied runtime state
personal contacts, calendars, finance, or legal data
direct copies of private operator memory

For the public distro, the professional rule is simple:

use your own keys
enable only the adapters you need
keep private overlay data outside this repo

See:

🤝 Contributing

Contribution surfaces are open on the public core:

install and validation flow
docs and examples
pack materialization
operational-fabric base
connector templates and optional adapters

Practical contribution flow:

run the public-core checks documented above
keep docs, examples, and command surfaces aligned
open a PR against the public core without introducing private overlay data

Project policies:

📄 License

MIT License — use it, fork it, build on it.

📘 Architecture • ⚡ Quick Start • 🗺️ Roadmap • ⬆ Back to Top

Name		Name	Last commit message	Last commit date
Latest commit History 24 Commits
.github		.github
adapters/gitnexus		adapters/gitnexus
agents		agents
assets/landing		assets/landing
config		config
docs		docs
examples		examples
fixtures		fixtures
install		install
schemas/ops_fabric		schemas/ops_fabric
src/hyperclaw_max		src/hyperclaw_max
tests		tests
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CITATION.cff		CITATION.cff
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
pyproject.toml		pyproject.toml

Folders and files

Latest commit

History

Repository files navigation

⚡ HYPERCLAW-MAX ⚡

🚀 A Local-First Autonomous Company in a Box

🎯 What Is This?

🗝️ Key Terms

👥 Who Is This For?

✅ What You Get Today

Public Core Shipped In This Repo

Optional Adapters And Templates

Not Shipped Yet

⚡ Quick Start

A. Fastest Path From A Repo Checkout

B. Installed CLI Path

Optional Smoke Test

🛠️ Installation Today

Prerequisites

1. Clone And Install

2. Bootstrap A Clean Target Root

3. Configure The Required Inputs

4. Validate The Public Core

5. Add Optional Adapters When Needed

🧠 Architecture

Layer Breakdown

🦸 Core Capabilities

Persistent Specialist Pack

Layered Memory Fabric

Operational Fabric Base

Local-First Model Routing

Surgical Repo Intelligence

🔌 Optional Connectors And Adapters

🆚 Why Not Just Use OpenClaw?

🧭 Remaining Extraction Gaps

📚 Documentation

🔒 Privacy And Boundary

🤝 Contributing

📄 License

About

Topics

Resources

License

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Packages