@kaleidorg/mind) is a local-first, agentic reasoning and tool-calling engine for a multi-L2 Bitcoin wallet. It is a pure library, an Engine for the agentic loop, a ToolRegistry with pluggable ToolSources, a SkillRegistry, and an injected LLMProvider, that runs identically on a phone and a laptop.
The design starts from a hard constraint: small on-device models are slow and unreliable at multi-step planning. KaleidoMind avoids asking them to do that work.
KaleidoMind does not run by itself, it is a library embedded by a host: the Rate mobile wallet (React Native, fully on-device QVAC), the Desktop App’s Tauri sidecar, or an eval and benchmark harness. KaleidoAgent does not currently use this library, it has its own separate agent loop. See Relationship to KaleidoAgent below.
The Tiered Funnel
Most requests never reach the model at all.- T0, fast path. Deterministic pattern match, no inference. Balance checks, addresses, spot prices.
- T2, recipe engine. A skill carries the ordered plan (resolve, price, convert, confirm, send); the model only fills the slots. That makes multi-step flows reliable even on a ~0.6B parameter model, instead of asking the model to plan the whole chain itself.
- T1, full agentic loop. Everything else, scoped to the skill’s own tool list so a small model never has to reason over the entire tool surface at once. Discovery flows (for example merchant-finder) intentionally lean more on the model for natural-language understanding.
One Tool Contract, Many Transports
The model sees identical tool names and schemas everywhere, only how a tool executes differs by surface:
The canonical tool contract lives in core as
ToolDef[], with a spend flag that maps to requiresConfirmation: true. Every fund-moving tool carries this flag, the Engine pauses and calls the host’s onConfirm before executing, so the model can never bypass a spend gate. The confirmation sheet gets a deterministic, voice-first readback (for example “Send 4,800 sats to bob over Spark. Confirm?”) built from the resolved call, not generated by the model, so a wrong unit or recipient surfaces where it can be caught.
Per-Layer Wallet Tools
Plus cross-cutting router tools:
get_balances(layer?), resolve_contact(name), get_price(asset?, fiat?), fiat_to_sats(amount, currency), get_swap_quote/execute_swap, the unified send_payment(asset, amount, to, layer?) that picks the rail automatically, and its receive counterpart create_invoice(asset?, amount?, layer?).
KaleidoSwap Trading & LSPS1
Separate contracts for DEX trading (kaleidoswap_get_quote, kaleidoswap_place_order, kaleidoswap_atomic_init/execute/status) and LSP-agnostic channel orders (lsp_get_info, lsp_get_network_info, lsp_estimate_fees, lsp_create_order, lsp_get_order). The atomic swap chain runs as a single confirm-gated recipe (kaleidoswapAtomicRecipe): quote, then after one confirmation init on the maker, read the node’s pubkey, whitelist the HTLC as taker, and execute.
Skills
Skills are Agent-Skills-spec playbooks (SKILL.md plus progressive disclosure) that scope which tools are visible and, for the agentic tier, carry the playbook itself. Bundled skills include per-wallet playbooks (spark-wallet, rgb-lightning-node), trading and channels (kaleido-trading, kaleido-lsps, flashnet-swaps, channel-manager, liquidity-optimizer), portfolio automation (portfolio-manager, dca), spending and data (bitrefill, paid-data, wallet-assistant), and a more model-leveraging merchant-discovery skill (merchant-finder, location plus BTC Map via pluggable embedding selectors). Payment and receive flows ship as T2 recipes rather than skills.
QVAC: On-Device Inference
LLM, embedding, speech-to-text, and text-to-speech inference all run through the QVAC SDK, locally on-device by default, or delegated to an explicitly paired, user-controlled desktop for heavier work. Published as the@kaleidorg/mind/qvac subpath so the SDK stays a peer dependency rather than a hard requirement of core. Memory and RAG (long-term recall, wallet-history retrieval, merchant discovery) also route through QVAC’s embeddings, with near-duplicate consolidation to keep memory from bloating.
Where It Runs
The fastest way to try it is the Desktop App. Download the latest release and follow the installation guide.
Relationship to KaleidoAgent
KaleidoAgent is a separate, always-on Node.js server (Nanobot runtime, scheduling, Telegram) that predates KaleidoMind’sEngine and has not been migrated onto it, it runs its own agent loop against Anthropic or OpenAI directly. The two are conceptually the same idea (an agentic loop over a tool registry with a confirm gate) implemented twice. Converging them, having KaleidoAgent host KaleidoMind’s Engine instead of its own loop, is a known, not-yet-started integration path; until then, treat them as independent systems that both consume kaleido-mcp.
Publishing & Subpaths
Published frompackages/core as @kaleidorg/mind, with subpaths: ./mcp (MCP tool source helpers), ./skills (skill loader), ./logger, and ./qvac (the on-device inference adapter). Also on npm: apps/provider as @kaleidorg/mind-provider, the Tauri desktop sidecar that the Desktop App embeds. The CLI in apps/cli is for terminal and eval use from the repository and is not published.