AceClaw

A Java agent runtime with a visual agent harness for long-running work

AceClaw is runtime-level governance for enterprise-grade agent systems — stable, controllable, observable, built for environments where compliance and predictability matter as much as capability.

The runtime is a Java daemon that runs the agent loop and gates tool use against per-session permission policy. A live dashboard renders the same event stream as a navigable trace — operators see exactly what the engine evaluated, and the same record drives the audit trail.

Java agent runtime

A persistent JVM daemon that runs the ReAct + Plan/Replan loop, tools, permissions, memory, and self-learning. Every capability use — tool execution, memory write, sub-agent spawn — flows through one policy in one place. Pure Java 21, zero AI framework. The CLI talks to it over a Unix Domain Socket; the optional dashboard uses a loopback-only WebSocket bridge with an explicit allowed-origins list.

Read the design philosophy → — why Java, why no AI framework, what drives the architecture.  ·  Runtime-level governance → — where AceClaw fits vs. protocol- and connector-level governance, and what's still missing.

Visual agent harness

A React dashboard that talks to the same daemon over the loopback-only WebSocket bridge — runtime state visualization for a long-running agent, so you can watch and intervene in real time. The ReAct loop is laid out as a live, navigable tree: every thinking block, tool call, and observation appears as its own node. Permission requests surface as inline panels you can Approve or Deny from the browser; sidebar status dots show at a glance which session needs you.

Visual Agent Harness → — the agent runtime's observability and control plane: watch what's happening, intervene when it matters.

Highlights

• Runtime-level governance — capabilities decided in the agent loop, not at the protocol or connector layer. One pipeline for every adapter (in progress). (details)
• Visual agent harness — live execution tree, inline permission Approve/Deny from the browser. (details)
• Plan → Execute → Replan — explicit task plan layered on top of ReAct, with per-step budgets and inline replan on failure. (details)
• Self-learning — zero-cost detectors turn behavior into typed, confidence-scored insights that survive across sessions. (details)
• Long-term memory — 8-tier hierarchy, HMAC-signed entries, hybrid search, automated consolidation. (details)
• Context engineering — budgeted 8-tier prompt assembly, 3-phase compaction, request-time pruning. (details)
• Security — UDS for CLI, loopback-only WebSocket for the dashboard with origin allowlist, sealed 4-level permissions, signed memory. (details)

Quick Start

One-Line Install

curl -fsSL https://raw.githubusercontent.com/xinhuagu/AceClaw/main/install.sh | sh

Downloads the latest pre-built release, extracts to ~/.aceclaw/, and adds commands to your PATH. Only requires Java 21 runtime (no build tools).

Configure & Run

export ANTHROPIC_API_KEY="sk-ant-api03-..."
aceclaw                # Start AceClaw (auto-starts daemon)

Or use OAuth (auto-discovered from Claude CLI credentials):

claude                 # Login via Claude CLI first
aceclaw                # Token auto-refreshes from Keychain

Commands

All commands installed by install.sh. Every command that accepts [provider] switches the LLM backend for that session.

Command	What it does
aceclaw	Start AceClaw TUI (auto-starts daemon if not running)
aceclaw dashboard	Open the browser dashboard (auto-starts daemon, opens default browser)
aceclaw-tui [provider]	Open another TUI window — never restarts daemon, safe for multi-session
aceclaw-restart [provider]	Stop daemon + restart with fresh build (warns if sessions active)
aceclaw-update	Update to latest release (refuses if sessions active)

Supported providers: anthropic (default), copilot, openai, openai-codex, ollama, groq, together, mistral

Daemon Management

The daemon is a persistent JVM process that runs in the background. It auto-starts when you run aceclaw, but can be managed directly:

aceclaw daemon start              # Start daemon in background
aceclaw daemon start -p copilot   # Start background daemon with provider override
aceclaw daemon start --foreground # Start daemon in foreground (for debugging)
aceclaw daemon stop     # Gracefully stop daemon
aceclaw daemon status   # Show health, version, model, active sessions

Switching Providers

Pass the provider name as an argument to any launch command:

# Release install (symlinked commands)
aceclaw-restart copilot       # Restart daemon with GitHub Copilot
aceclaw-tui ollama            # Open TUI against local Ollama (no daemon restart)
aceclaw-restart anthropic     # Switch back to Anthropic Claude

# Or via environment variable (works with any command)
ACECLAW_PROVIDER=groq aceclaw

Provider Authentication

# Anthropic — API key or OAuth
export ANTHROPIC_API_KEY="sk-ant-api03-..."     # API key in env
# Or add to ~/.aceclaw/config.json: {"apiKey": "sk-ant-api03-..."}
# Or login via Claude CLI for OAuth token auto-refresh

# GitHub Copilot — uses your existing subscription
aceclaw-restart copilot                         # No extra key needed

# OpenAI / OpenAI Codex
export OPENAI_API_KEY="sk-..."
aceclaw-restart openai
# Or OAuth for Codex:
aceclaw models auth login --provider openai-codex
aceclaw-restart openai-codex

# Ollama (local, offline, no key needed)
aceclaw-restart ollama

# Groq / Together / Mistral
export OPENAI_API_KEY="gsk_..."                 # Provider-specific key
aceclaw-restart groq

See Provider Configuration for full setup details.

Build from Source (Developers)

git clone https://github.com/xinhuagu/AceClaw.git && cd AceClaw
./gradlew clean build && ./gradlew :aceclaw-cli:installDist
./aceclaw-cli/build/install/aceclaw-cli/bin/aceclaw-cli

The full build also bundles the dashboard via npm — Node 20 LTS must be on PATH. Backend-only contributors without Node can pass -Pno-dashboard to skip the dashboard build (aceclaw dashboard will then return a friendly 404; the daemon and CLI still build).

For dashboard development with hot reload: cd aceclaw-dashboard && npm run dev (Vite serves on http://localhost:5173; add that origin to webSocket.allowedOrigins in ~/.aceclaw/config.json so the daemon's WS bridge accepts the cross-origin handshake).

Development scripts (from git checkout only — same provider argument support):

Script	What it does
./dev.sh [provider]	Rebuild + restart daemon + auto-benchmark on feature branches
./restart.sh [provider]	Rebuild + restart daemon (no benchmarks, fastest restart)
./tui.sh [provider]	Open TUI window (no restart, no rebuild if binary exists)

./dev.sh                    # Default: anthropic, with benchmarks on feature branches
./dev.sh --no-bench copilot # Copilot, skip benchmarks
./restart.sh ollama         # Quick restart with Ollama
./tui.sh                    # Attach to running daemon

See Multi-Session Model for details on running multiple TUI windows.

Platform Support

Platform	Status	IPC	CI Gate
Linux	Fully supported	AF_UNIX	pre-merge-check — full test suite (required)
macOS	Fully supported	AF_UNIX	platform-smoke — build + cross-platform tests (required)
Windows 10 1803+	Experimental	AF_UNIX (JEP 380)	platform-smoke — build + cross-platform tests (required)

All three platform checks are required for merging to main. Windows requires Java 21 runtime and Windows 10 version 1803 or later (for AF_UNIX socket support). See Windows UDS Spike for technical details.

Tech Stack

Runtime (daemon + CLI): Java 21 (preview features) · Gradle 8.14 · Picocli 4.7.6 · JLine3 3.27.1 · Jackson 2.18.2 · Javalin 6 (WebSocket bridge) · GraalVM Native Image · JUnit 5

Dashboard: React 19 · TypeScript 5 · Vite 6 · Tailwind 4 · framer-motion · dagre · Vitest

License

Apache License 2.0