README
¶
GizClaw
GizClaw is an out-of-the-box agent runtime and edge-server platform for GizClaw devices. It currently supports authoritative servers and single-upstream edge ingress; a self-organizing multi-server mesh remains future work.
It provides the server, CLI, WebRTC transport, Admin/RPC APIs, workflow-backed agent runtime, device telemetry, state monitoring, OTA firmware delivery, digital content distribution, social graph, gameplay services, and shared SDK contracts for connected devices, desktop clients, browser integrations, and test harnesses.
GizClaw is designed for both developers and end users. Developers can build devices, services, and browser integrations on top of the shared API contracts, while desktop users can run a local server, use the UI directly, and customize their own agents through workspace runtimes.
Features
- Out-of-the-box server and CLI for local or deployed GizClaw nodes.
- Workspace-based agent runtime where each workspace is an instantiated agent environment backed by a workflow configuration.
- Workflow drivers for runtime behavior such as Flowcraft agents, chatroom workflows, Doubao AST translation, and Doubao realtime flows.
- WebRTC transport, signaling, and service streams for GizClaw node and client connectivity.
- Edge-node ingress and optional TURN relay with authoritative-server forwarding over Giznet/WebRTC service streams.
- Device registration, configuration, telemetry intake, runtime state monitoring, and policy-controlled access.
- Admin and peer RPC APIs generated from shared OpenAPI/RPC schemas.
- Firmware catalog, channel-based OTA metadata, artifact upload, and authorized firmware file download.
- Social workspace resources for contact, friend, and chatroom-style interactions.
- Gameplay rulesets, point accounts, reward grants, pet adoption, drive actions, pet workspaces, game results, badge progression, and pixa asset delivery.
- Generated API packages and SDK surfaces for Go, JavaScript, Dart/Flutter, C-facing clients, CLI, and e2e harnesses.
Roadmap
- Production-ready Admin UI and Play UI.
- Other workflow, agent, and realtime conversation engines:
- OpenAI Realtime
- Coze
- Eino
- Generalized gameplay reward entry points beyond
pet.drive, including built-in tool exposure for agent-driven reward grants. - Pet-readable gameplay event writes into pet workspace memory/history after care actions and game results.
- Self-organizing server mesh where devices attach to one node and requests can route through other nodes to the node that owns the target device data.
- Stabilize the Flutter SDK and mobile client for broader end-user and platform coverage.
- Third-party digital content federation with joint authorization and access from agent runtimes.
- Expanded digital content delivery for gameplay content beyond current pet and badge pixa resources.
- Additional process-wide
slogsinks beyond stderr and Volc TLS. - Refresh repository-local agent skills for current CLI, admin, server, firmware, gear, workspace, and Play workflows.
Repository Layout
cmd/gizclaw/: CLI entrypoint for server, context, admin, and play commands.cmd/internal/: command-layer server wiring, storage setup, logging, and HTTP service helpers.pkgs/gizclaw/: core GizClaw server, peer services, generated API packages, CLI client helpers, and domain services.pkgs/giznet/: WebRTC transport, HTTP-over-service streams, and transport contracts.pkgs/gizedge/: single-upstream edge ingress, forwarding, and optional TURN relay runtime.pkgs/store/: key-value, object, SQL-backed, metrics, vector, graph, and identity store primitives.pkgs/agent/: agent memory, recall, embedding, and local runtime support.pkgs/genx/: model and generation abstractions used by workflows and agents.pkgs/audio/: audio codecs, resampling, raw Opus packet helpers, playback, and voiceprint helpers.api/: source OpenAPI and RPC schemas. Generated Go and TypeScript code is derived from these files.sdk/: Go, JavaScript/TypeScript, Dart/Flutter, and C-facing SDK surfaces.js/: shared JavaScript packages and browser/runtime tooling.apps/wails/: desktop shell and frontend.apps/gizclaw-app/: Flutter mobile client for iOS and Android.guides/: localized development, review, coding, usage, and Reference documentation.skills/: project-level Agent Skills installable withnpx skills.examples/: runnable examples for GenX, WebRTC SFU, audio, songs, and voiceprint workflows.tests/: unit, integration, and Docker-backed e2e test projects.
Development
Run the default Go validation:
go test ./...
For focused server and API work, these packages are often the fastest first check:
go test ./cmd/... ./pkgs/... -count=1
Regenerate API code after changing files under api/:
go generate ./pkgs/gizclaw/api/...
npm --prefix sdk/js run gen:sdk
Docker-backed GizClaw e2e requires provider credentials in
tests/gizclaw-e2e/.env:
cp tests/gizclaw-e2e/.env.example tests/gizclaw-e2e/.env
bash tests/gizclaw-e2e/run_tests.sh
Documentation
The hosted Project Guide selects English or Simplified Chinese from the browser language. Direct locale entrypoints are English and 简体中文.
- Development Guide: architecture, API design, package boundaries, CLI, applications, and SDK development.
- Review Guide: review workflow, review items, self-review, PR Agent review, and issue review.
- Coding Conventions: Go, JavaScript/TypeScript, Dart/Flutter, C/cgo, and documentation conventions.
- Usage Guide: CLI, Wails, Flutter, and SDK usage.
- References: Go references plus local Flutter Dartdoc and TypeScript TypeDoc generation.
- API Design: HTTP, Protobuf/RPC, schema ownership, and generated-surface boundaries.
Documentation sources remain under guides/, and source API
contracts remain under api/. Start and validate the Guide
locally with:
npm ci --prefix guides
npm --prefix guides run dev
npm --prefix guides run build:site
build:site checks that every Chinese Markdown route has an English counterpart
before building the production site.
Agent Skills
The repository includes project-level Agent Skills for CLI, server, context, Admin, firmware, workspace, and Play workflows. Install a skill from the repository root with:
npx skills add . --skill gizclaw-cli
See the Agent Skills catalog for the full list and global installation commands.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
gizclaw
command
|
|
|
internal/storage
Package storage provides a configuration-driven registry for physical storage backends.
|
Package storage provides a configuration-driven registry for physical storage backends. |
|
internal/stores
Package stores provides a configuration-driven registry for logical stores.
|
Package stores provides a configuration-driven registry for logical stores. |
|
pkgs
|
|
|
agent/embed
Package embed provides a text embedding interface and remote API implementations.
|
Package embed provides a text embedding interface and remote API implementations. |
|
agent/memory
Package memory provides a personal memory system for AI personas.
|
Package memory provides a personal memory system for AI personas. |
|
agent/ncnn
Package ncnn provides Go bindings for the ncnn neural network inference framework via CGo static linking on supported Linux and macOS targets.
|
Package ncnn provides Go bindings for the ncnn neural network inference framework via CGo static linking on supported Linux and macOS targets. |
|
agent/recall
Package recall provides a bottom-level search engine combining segment storage, entity-relation graphs, vector similarity search, and keyword matching into a unified search space.
|
Package recall provides a bottom-level search engine combining segment storage, entity-relation graphs, vector similarity search, and keyword matching into a unified search space. |
|
audio/pcm
Package pcm provides types and utilities for working with PCM (Pulse Code Modulation) audio data.
|
Package pcm provides types and utilities for working with PCM (Pulse Code Modulation) audio data. |
|
audio/portaudio
Package portaudio provides device IO abstraction backed by PortAudio.
|
Package portaudio provides device IO abstraction backed by PortAudio. |
|
audio/resampler
Package resampler provides audio resampling using a pure Go implementation.
|
Package resampler provides audio resampling using a pure Go implementation. |
|
audio/songs
Package songs provides built-in melodies for testing audio playback.
|
Package songs provides built-in melodies for testing audio playback. |
|
buffer
Package buffer provides thread-safe buffer implementations for streaming data processing.
|
Package buffer provides thread-safe buffer implementations for streaming data processing. |
|
encoding/base32
Package base32 implements unpadded Crockford Base32 encoding.
|
Package base32 implements unpadded Crockford Base32 encoding. |
|
encoding/base58
Package base58 implements Bitcoin Base58 encoding.
|
Package base58 implements Bitcoin Base58 encoding. |
|
genx
Package genx provides a unified streaming framework for multi-modal AI.
|
Package genx provides a unified streaming framework for multi-modal AI. |
|
genx/agentkit/audiodock
Package audiodock composes optional streaming ASR and TTS around a text-oriented GenX Transformer.
|
Package audiodock composes optional streaming ASR and TTS around a text-oriented GenX Transformer. |
|
genx/generators
Package generators provides a multiplexer for genx.Generator routing.
|
Package generators provides a multiplexer for genx.Generator routing. |
|
genx/internal/streamkit
Package streamkit provides provider-neutral streaming lifecycle primitives for GenX Transformers.
|
Package streamkit provides provider-neutral streaming lifecycle primitives for GenX Transformers. |
|
genx/internal/toolrun
Package toolrun owns invocation-local ToolCall identity and limits for GenX Transformers.
|
Package toolrun owns invocation-local ToolCall identity and limits for GenX Transformers. |
|
genx/labelers
Package labelers provides query-time label selection for memory recall.
|
Package labelers provides query-time label selection for memory recall. |
|
genx/profilers
Package profilers provides entity profile management.
|
Package profilers provides entity profile management. |
|
genx/segmentors
Package segmentors provides conversation segmentation.
|
Package segmentors provides conversation segmentation. |
|
genx/transformers
Package transformers provides stream transformer framework and mux helpers.
|
Package transformers provides stream transformer framework and mux helpers. |
|
genx/transformers/audiostream
Package audiostream provides audio-byte stream processing shared by GenX Transformers and their stream consumers.
|
Package audiostream provides audio-byte stream processing shared by GenX Transformers and their stream consumers. |
|
genx/transformers/dashscoperealtime
Package dashscoperealtime provides the DashScope realtime transformer.
|
Package dashscoperealtime provides the DashScope realtime transformer. |
|
genx/transformers/doubaoasr
Package doubaoasr adapts Doubao streaming ASR to the GenX Transformer contract.
|
Package doubaoasr adapts Doubao streaming ASR to the GenX Transformer contract. |
|
genx/transformers/doubaoast
Package doubaoast provides the Doubao AST stream transformer.
|
Package doubaoast provides the Doubao AST stream transformer. |
|
genx/transformers/doubaorealtime
Package doubaorealtime provides the Doubao realtime dialogue transformer.
|
Package doubaorealtime provides the Doubao realtime dialogue transformer. |
|
genx/transformers/doubaorealtimeduplex
Package doubaorealtimeduplex provides the Doubao realtime Duplex transformer.
|
Package doubaorealtimeduplex provides the Doubao realtime Duplex transformer. |
|
genx/transformers/doubaotts
Package doubaotts adapts Doubao Seed and voice-clone TTS services to the GenX Transformer contract.
|
Package doubaotts adapts Doubao Seed and voice-clone TTS services to the GenX Transformer contract. |
|
genx/transformers/eino
Package eino provides a configurable CloudWeGo Eino Graph as a reusable GenX Transformer.
|
Package eino provides a configurable CloudWeGo Eino Graph as a reusable GenX Transformer. |
|
genx/transformers/flowcraft
Package flowcraft adapts a Flowcraft graph runtime to a GenX Transformer.
|
Package flowcraft adapts a Flowcraft graph runtime to a GenX Transformer. |
|
genx/transformers/minimaxtts
Package minimaxtts adapts MiniMax TTS to the GenX Transformer contract.
|
Package minimaxtts adapts MiniMax TTS to the GenX Transformer contract. |
|
gizclaw/api/adminhttp
Package adminhttp provides primitives to interact with the openapi HTTP API.
|
Package adminhttp provides primitives to interact with the openapi HTTP API. |
|
gizclaw/api/apitypes
Package apitypes provides primitives to interact with the openapi HTTP API.
|
Package apitypes provides primitives to interact with the openapi HTTP API. |
|
gizclaw/api/eventproto
Package eventpb contains generated Peer Event Protobuf messages.
|
Package eventpb contains generated Peer Event Protobuf messages. |
|
gizclaw/api/openaihttp
Package openaihttp provides primitives to interact with the openapi HTTP API.
|
Package openaihttp provides primitives to interact with the openapi HTTP API. |
|
gizclaw/api/peerhttp
Package peerhttp provides primitives to interact with the openapi HTTP API.
|
Package peerhttp provides primitives to interact with the openapi HTTP API. |
|
gizclaw/api/rpcapi
Package rpcapi provides protobuf-backed Peer RPC helper types.
|
Package rpcapi provides protobuf-backed Peer RPC helper types. |
|
gizclaw/services/ai/memorylayout
Package memorylayout owns the persisted, connection-free MemoryLayout resources consumed by RuntimeProfile memory bindings.
|
Package memorylayout owns the persisted, connection-free MemoryLayout resources consumed by RuntimeProfile memory bindings. |
|
gizclaw/services/ai/workflow/einoconfig
Package einoconfig maps and validates the public Eino Workflow contract.
|
Package einoconfig maps and validates the public Eino Workflow contract. |
|
gizclaw/services/runtime/memorystore
Package memorystore constructs one Workspace-owned provider-neutral Memory Store from a RuntimeProfile binding and its connection-free MemoryLayout.
|
Package memorystore constructs one Workspace-owned provider-neutral Memory Store from a RuntimeProfile binding and its connection-free MemoryLayout. |
|
gizclaw/services/runtime/peertelemetry
Package peertelemetry decodes peer telemetry packets and projects them into metrics plus the fixed runtime peer status snapshot.
|
Package peertelemetry decodes peer telemetry packets and projects them into metrics plus the fixed runtime peer status snapshot. |
|
gizclaw/services/runtime/toolkit
Package toolkit defines the runtime Tool and ToolKit model used by agents.
|
Package toolkit defines the runtime Tool and ToolKit model used by agents. |
|
gizclaw/services/system/ownership
Package ownership carries the authenticated owner through internal service calls.
|
Package ownership carries the authenticated owner through internal service calls. |
|
gizclaw/services/system/pendingdeletion
Package pendingdeletion defines the durable handoff written when deletion is requested for an active resource.
|
Package pendingdeletion defines the durable handoff written when deletion is requested for an active resource. |
|
gizmetrics
Package gizmetrics provides process-wide, best-effort instrumentation backed by a metrics store installed by the host process.
|
Package gizmetrics provides process-wide, best-effort instrumentation backed by a metrics store installed by the host process. |
|
gizmetrics/httpmetrics
Package httpmetrics provides reusable net/http server instrumentation backed by the process-wide gizmetrics recorder.
|
Package httpmetrics provides reusable net/http server instrumentation backed by the process-wide gizmetrics recorder. |
|
giznet/giztunnel
Package giztunnel multiplexes logical Giznet connections over reliable streams while keeping loss-tolerant packets on a separate packet lane.
|
Package giztunnel multiplexes logical Giznet connections over reliable streams while keeping loss-tolerant packets on a separate packet lane. |
|
giztools
Package giztools provides stateless execution helpers for Tool backends.
|
Package giztools provides stateless execution helpers for Tool backends. |
|
store/graph
Package graph provides an entity-relation graph interface and a KV-backed implementation.
|
Package graph provides an entity-relation graph interface and a KV-backed implementation. |
|
store/kv
Package kv provides a key-value store interface with hierarchical path-based keys.
|
Package kv provides a key-value store interface with hierarchical path-based keys. |
|
store/logstore
Package logstore defines business-neutral searchable record stores.
|
Package logstore defines business-neutral searchable record stores. |
|
store/memory
Package memory defines the provider-neutral long-term memory contract.
|
Package memory defines the provider-neutral long-term memory contract. |
|
store/metrics
Package metrics defines a business-neutral store for numeric time series samples.
|
Package metrics defines a business-neutral store for numeric time series samples. |
|
store/objectstore
Package objectstore defines a generic object storage abstraction.
|
Package objectstore defines a generic object storage abstraction. |
|
store/vecid
Package vecid assigns stable string IDs to embedding vectors via online nearest-centroid matching and offline DBSCAN re-clustering.
|
Package vecid assigns stable string IDs to embedding vectors via online nearest-centroid matching and offline DBSCAN re-clustering. |
|
store/vecstore
Package vecstore provides a vector approximate nearest-neighbor (ANN) search interface and implementations.
|
Package vecstore provides a vector approximate nearest-neighbor (ANN) search interface and implementations. |
|
trie
Package trie provides a generic trie data structure for efficient path-based storage and retrieval.
|
Package trie provides a generic trie data structure for efficient path-based storage and retrieval. |
|
sdk
|
|
|
tests
|
|
|
gizclaw-e2e/cmd/serverrpcprobe
command
|
|
|
gizclaw-e2e/docker/turnserver
command
|
|
|
giznet-e2e/gateway
command
Command gateway-load exercises logical GizClaw sessions through one or more Edge gateways and writes a machine-readable capacity artifact.
|
Command gateway-load exercises logical GizClaw sessions through one or more Edge gateways and writes a machine-readable capacity artifact. |
|
tools
|
|
|
quality
command
Command quality runs repository-wide quality checks on tracked handwritten source.
|
Command quality runs repository-wide quality checks on tracked handwritten source. |
Click to show internal directories.
Click to hide internal directories.