harmoniis/harmonia

Harmonia Agent — Agent Skill

Binary: harmonia | Install: curl --proto '=https' --tlsv1.2 -sSf https://harmoniis.com/harmonia/install | sh | Windows: iwr https://harmoniis.com/harmonia/install.ps1 -UseB | iex

Distributed evolutionary homoiconic self-improving agent. SBCL Common Lisp core + modular Rust tool ecosystem via CFFI.

Install

macOS / Linux / FreeBSD:

curl --proto '=https' --tlsv1.2 -sSf https://harmoniis.com/harmonia/install | sh

Windows (PowerShell):

iwr https://harmoniis.com/harmonia/install.ps1 -UseB | iex

Binary-first install with source-build fallback. Optional overrides:

HARMONIA_INSTALL_MODE=source curl -sSf https://harmoniis.com/harmonia/install | sh   # force source build
HARMONIA_WITH_SOURCE=1 curl -sSf https://harmoniis.com/harmonia/install | sh          # binary + local source for self-rewrite

Prerequisites

| Dependency | Why | Install | |---|---|---| | Rust 1.89+ | Builds tool crates | rustup.rs | | SBCL | Agent runtime | brew install sbcl / apt install sbcl | | Quicklisp | Lisp packages | Auto-installed by harmonia setup |

Setup

harmonia setup    # interactive wizard
harmonia start    # start agent
harmonia upgrade  # update to latest release
harmonia uninstall

Setup Wizard Steps

1. Creates system workspace at ~/.harmoniis/harmonia/
2. Asks for user workspace directory (default: ~/workspace)
3. Verifies SBCL + Quicklisp
4. Bootstraps vault keys from harmoniis-wallet
5. Select LLM providers and store API keys in encrypted vault (OpenRouter recommended)
6. Choose evolution profile: binary-only | source-rewrite | distributed participant
7. Git fork URL + optional GitHub PAT (stored in vault)
8. Optional S3 credentials for binary backups (stored in vault)
9. Select frontends to enable + collect frontend credentials (stored in vault)
10. Build and configure everything

No model selection required. The backend owns a built-in model pool with pricing. Model selection is automatic via harmonic scoring and evolves over time.

Configuration

Workspace: ~/.harmoniis/harmonia/ (user data only)

~/.harmoniis/harmonia/
├── vault.db          # encrypted secrets (SQLite, AES-256-GCM)
├── config.db         # non-secret configuration (SQLite, config-store v2)
├── metrics.db        # model performance metrics (SQLite, auto-created)
├── config/
│   ├── workspace.sexp
│   └── gateway-frontends.sexp
├── genesis/          # evolution knowledge
├── state/            # runtime state, sockets, caches
└── frontends/        # frontend state and attachments

Installed application assets:

• macOS / Linux / FreeBSD: ~/.local/bin/harmonia, ~/.local/lib/harmonia/, ~/.local/share/harmonia/
• Windows: %LOCALAPPDATA%\Harmonia\bin\, %LOCALAPPDATA%\Harmonia\lib\, %LOCALAPPDATA%\Harmonia\share\

Key config files (S-expressions):

• harmony-policy.sexp — security, evolution, harmonic routing
• model-policy.sexp — harmonic scoring weights for model evolution
• baseband.sexp — frontend registry + mesh transport
• tools.sexp — tool availability
• swarm.sexp — parallel agent orchestration

Secrets

Vault (vault.db) — secrets only (API keys, tokens, passwords). AES-256-GCM encryption, component-scoped access policies. Each module reads only its own secrets.

Config-store (config.db) — all non-secret configuration (URLs, timeouts, paths, modes, feature flags). SQLite-backed with in-memory cache. Component-scoped read/write policies mirror vault's model. Fallback chain: cache → DB → legacy env alias → canonical HARMONIA_{SCOPE}_{KEY} → default.

No raw environment variables at runtime except bootstrap paths (HARMONIA_STATE_ROOT, HARMONIA_LIB_DIR). Setup writes everything directly to vault and config-store.

Architecture

SBCL Common Lisp (Conductor + Memory + Self-Rewrite/Ouroboros)
         │ CFFI
Rust .so Libraries (Core + Tools + Backend + Frontends)

Core Crates

phoenix (hot-reload/recovery), ouroboros (self-rewrite), vault (encrypted secrets), memory (persistent + compression), http, s3, git-ops, rust-forge (runtime compilation), cron-scheduler, push (webhooks), recovery, fs, parallel-agents, harmonic-matrix, config-store, tailnet, gateway.

Backend — Model Pool Protocol

Each LLM provider is a separate backend crate implementing the standardised provider protocol (harmonia-provider-protocol):

| Backend | Crate | API Style | |---|---|---| | OpenRouter | harmonia-openrouter | OpenAI-compatible gateway (routes all) | | OpenAI | harmonia-openai | OpenAI native | | Anthropic | harmonia-anthropic | Anthropic Messages API | | xAI (Grok) | harmonia-xai | OpenAI-compatible + reasoning | | Google AI Studio | harmonia-google-ai-studio | Google Generative AI REST | | Google Vertex AI | harmonia-google-vertex | Vertex AI REST + Bearer token | | Amazon Bedrock | harmonia-amazon-bedrock | AWS CLI bedrock-runtime converse | | Groq | harmonia-groq | OpenAI-compatible | | Alibaba (Qwen) | harmonia-alibaba | OpenAI-compatible (DashScope) |

The backend exposes a standardised model offerings protocol via FFI:

| FFI Function | Returns | Purpose | |---|---|---| | harmonia_openrouter_list_models() | JSON array | All available models with pricing, quality, speed, tags | | harmonia_openrouter_select_model(task_hint) | Model ID | Best model for task category via pool scoring | | harmonia_openrouter_complete(prompt, model) | Text | Complete with explicit model (or empty for auto-select) | | harmonia_openrouter_complete_for_task(prompt, task_hint) | Text | Complete with task-aware model selection |

Initial model pool (bootstrap tier — cheapest/fastest):

| Model | Tier | USD/1K in | USD/1K out | Tags | |---|---|---|---|---| | google/gemini-3.1-flash-lite-preview | micro | 0.00025 | 0.0015 | fast, memory-ops, casual | | deepseek/deepseek-chat-v3.1:free | free | 0.0 | 0.0 | reasoning, casual | | qwen/qwen3-coder:free | free | 0.0 | 0.0 | coding, execution | | qwen/qwen3.5-flash-02-23 | lite | 0.0 | 0.0 | fast, coding, execution, reasoning | | minimax/minimax-m2.5 | lite | 0.0003 | 0.0012 | balanced, memory-ops, casual | | amazon/nova-micro-v1 | micro | 0.000035 | 0.00014 | fast, routing |

Higher tiers (orchestration, software-dev) available via harmonia_openrouter_select_model("orchestration").

Task hints: orchestration, execution, memory-ops, coding, reasoning, casual, software-dev.

Performance is measured per-request (latency, success) and written to the SQLite metrics.db database (resolved via config-store global/state-root). Four tables:

• models — full model catalogue (290+ models synced from OpenRouter API + hardcoded), with per-token pricing, context length, modality
• llm_perf — every LLM backend call (backend, model, latency_ms, success, pricing)
• parallel_tasks — parallel-agent task completions (cost, verification)
• tmux_events — tmux CLI agent lifecycle events (spawn, input, approve, deny, kill) with cost_usd and duration_ms tracking

On init, the OpenRouter backend syncs the full model catalogue from https://openrouter.ai/api/v1/models (background thread). All hardcoded backend offerings are also registered. The models table is the agent's single source of truth for what models exist and what they cost.

Metrics Query FFI

The orchestrator queries the metrics database via FFI. The agent can run arbitrary SELECT SQL for maximum flexibility:

| FFI Function | Returns | Purpose | |---|---|---| | harmonia_metrics_query_json(sql) | JSON array | Run any SELECT query, get results as JSON | | harmonia_metrics_query_sexp(sql) | S-expression | Run any SELECT query, get results as s-expression plists | | harmonia_metrics_sync_models(api_key) | Count or -1 | Sync model catalogue from OpenRouter API | | harmonia_metrics_model_stats(model) | S-expression | Per-model stats: count, success-rate, avg-latency, pricing | | harmonia_metrics_best_models(backend, limit) | S-expression list | Top-performing models ranked by success rate + speed | | harmonia_metrics_llm_report() | S-expression | Full LLM backend performance report | | harmonia_metrics_tmux_report() | S-expression | Tmux agent event summary | | harmonia_metrics_telemetry_digest() | S-expression | Combined digest for harmonic orchestration decisions | | harmonia_metrics_bridge_routes(since_ts) | S-expression | Recent LLM perf as route entries for harmonic matrix |

Example SQL queries the agent can run:

-- Cheapest models with >8K context
SELECT id, name, usd_per_tok_in, usd_per_tok_out, context_length
FROM models WHERE context_length > 8000 ORDER BY usd_per_tok_in ASC LIMIT 20

-- Best performing models in last hour
SELECT model, COUNT(*) n, AVG(CAST(success AS REAL)) sr, AVG(latency_ms) lat
FROM llm_perf WHERE ts > unixepoch()-3600 GROUP BY model ORDER BY sr DESC, lat ASC

-- Cost analysis by provider
SELECT provider, COUNT(*) models, MIN(usd_per_tok_in) cheapest_in, MIN(usd_per_tok_out) cheapest_out
FROM models WHERE usd_per_tok_in > 0 GROUP BY provider ORDER BY cheapest_in ASC

Tools

browser (Chrome CDP with stealth anti-detection), search-exa (neural), search-brave, hfetch (secure HTTP), zoom (meeting automation).

Voice Backends

voice-router dispatches to: whisper (STT via Groq/OpenAI), elevenlabs (TTS).

Frontends (hot-pluggable via dlopen)

TUI (always on), MQTT, Telegram, Slack, Discord, Signal (signal-cli bridge), WhatsApp, iMessage (BlueBubbles), Mattermost, Nostr, Email (IMAP/SMTP), Tailscale mesh.

Security

Two-layer model:

1. Security Kernel (deterministic, non-bypassable) — typed signal dispatch, policy gate for privileged ops, taint propagation, safe parsers.
2. Adaptive Security Shell — dissonance scoring (18 injection patterns), harmonic routing, component-scoped vault policies.

Policy gate blocks privileged ops if signal has external taint or lacks :owner/:authenticated label.

Evolution Profiles

• binary-only — use released binaries, no self-modification
• source-rewrite — agent can edit and recompile its own source
• distributed participant — participate in cross-instance evolution

LLM Model Routing

14 model profiles from micro (nova-micro) to frontier (claude-opus-4.6, gpt-5). No "default model" — model selection is task-aware and score-based:

• Different models for orchestration, coding, memory-ops, casual
• Round-robin through pool initially to gather performance data
• Harmonic-matrix evolves selection based on measured latency, success rate, and cost
• Scoring weights: completion 30%, correctness 20%, speed 12%, price 12%, token-efficiency 10%, orchestration-efficiency 10%, experience 6%

Platforms

macOS (Apple Silicon / Intel), Linux (x86_64 / aarch64), FreeBSD, Windows.

License

Harmonia Community License 1.0 (HCL-1.0). Free for all use — individuals, freelancers, companies. Only restriction: hosting Harmonia as a managed service for third parties requires a commercial license. Contact [email protected].

Build from Source

git clone https://github.com/harmoniis/harmonia.git && cd harmonia
bazel build //...   # or: cargo build --release
bazel test //...    # or: cargo test --workspace

Source: https://github.com/harmoniis/harmonia Docs: https://harmoniis.com/docs/harmonia/overview Marketplace: https://harmoniis.com/skill.md