⚡ Caphlon

Unified AI Agent Platform — Qualixar OS + Open Design + MiMo Code.

A community-powered, decentralized AI development system built around Hive Intelligence (Kovan Zekası). A collective platform aiming to push open-source AI models to their peak — without needing massive hardware or budgets.

"Together we learn, together we grow stronger." – Hive Intelligence Manifesto

For a tour of the interface (welcome screen + model picker), see: docs/UI.md

---

Getting Started

npm install -g caphlon   # the CLI
caphlon setup            # downloads + builds the platform (real tools) — idempotent
caphlon connect          # bind a model provider + API key (once)
caphlon                  # talk

caphlon setup clones the platform into ~/.caphlon/platform (override with CAPHLON_PLATFORM) and fetches the real vendored tools from their upstreams (OpenCode, Aider, Qualixar, MiMo, Open Design; add the experimental layer with caphlon setup --all). Re-running it is safe — it only fills gaps.

From source instead (contributors)

git clone https://github.com/demiralpdev/Caphlon.git && cd Caphlon
bash scripts/setup-cores.sh        # fetch tools + build (idempotent)
node packages/caphlon/bin/caphlon.js doctor
cd packages/caphlon && npm link    # optional: `caphlon` from anywhere

Staying current

caphlon checks for a new release at most once a day and asks before doing anything — there is no silent auto-update. Answer E and it runs npm i -g caphlon@latest; answer anything else and that version won't be offered again. Disable entirely with CAPHLON_NO_UPDATE_CHECK=1. Running from a source checkout? It tells you to git pull instead of touching your global install.

Platform support (measured, not assumed)

Platform	Status
macOS (Apple Silicon)	✅ Developed here; full fresh-install e2e green (doctor 21/21)
Linux (Ubuntu 24.04)	✅ Clean-container fresh-install e2e green (doctor 21/21)
Windows	❌ Untested — use WSL2 (Ubuntu) and follow the Linux path

No subcommands to memorize: just run caphlon and talk. Inside the chat, a design request ("build me a Reddit-like landing page") auto-engages Open Design, and heavy multi-file code changes auto-engage the real Aider (the agent calls the aider_edit tool itself). Subcommands below remain for direct access.

Architecture

┌──────────────────────────────────────────────────────────────────┐
│  CAPHLON CLI (caphlon/caph)                                     │
│  Single command — access to every component                     │
└──────────────────────────┬───────────────────────────────────────┘
                           │
┌──────────────────────────▼───────────────────────────────────────┐
│  ORCHESTRATOR: Qualixar OS                                      │
│  - Judge pipeline (consensus)                                   │
│  - Forge AI (task dispatch + compose workflow)                  │
│  - Dashboard (24 tabs)                                          │
│  - OPEN DESIGN BRIDGE (design/UI/creative pipeline)             │
│  - MIMO BRIDGE (memory + compose + self-improvement)            │
└──────────────────────┬───────────────────────────────────────────┘
                       │
┌──────────────────────▼───────────────────────────────────────────┐
│  DESIGN LAYER: Open Design                                       │
│  - 100+ skills (prototype, deck, image, video, dashboard)       │
│  - 150 brand-grade DESIGN.md systems (Linear, Stripe, Apple)    │
│  - 261 plugins (scenario, template, migration)                  │
│  - HyperFrames HTML→MP4 motion graphics                        │
└──────────────────────┬───────────────────────────────────────────┘
                       │
┌──────────────────────▼───────────────────────────────────────────┐
│  MEMORY/WORKFLOW LAYER: MiMo Code (fork of OpenCode)            │
│  - Persistent memory (MEMORY.md + SQLite FTS5)                  │
│  - Compose mode (specs-driven development)                      │
│  - Dream/Distill (self-improvement loop)                        │
│  - Goal/Stop condition (judge-gated, prevents premature stop)   │
└──────────────────────┬───────────────────────────────────────────┘
                       │
┌──────────────────────▼───────────────────────────────────────────┐
│  VBS AGENT: Hermes Agent                                         │
│  - Self-improving learning loop                                 │
│  - Batch trajectory generation (training data)                  │
│  - Multi-platform (Telegram/Discord/CLI)                        │
└──────────────────────┬───────────────────────────────────────────┘
                       │
┌──────────────────────▼───────────────────────────────────────────┐
│  FEDERATED: Flower (SuperLink/SuperNode)                        │
│  FINE-TUNING: SmolLM-135M + LoRA (CPU-capable)                   │
│  TOKEN OPT.: tokenless + token-pilot                             │
│  SECURITY: Validator + Reputation + Honeypot                    │
└──────────────────────────────────────────────────────────────────┘

CLI Commands

caphlon connect      # Bind a model provider + API key (OpenCode-style)
caphlon model        # Show / list / switch the active model
caphlon ui           # Launch the OpenCode interface (the real OpenCode TUI)
caphlon code         # AI pair-programming (via real Aider)
caphlon dev          # Start agent + dashboard
caphlon run "..."    # Run a task
caphlon design       # Design pipeline
caphlon compose      # Compose workflow (8 stages; runs/resume: crash-safe continuation)
caphlon skill        # Skill store: list/add/search/show/learn/evolve/sync
caphlon vault        # Knowledge vault: cheap index + on-demand notes (token-efficient)
caphlon forge "..."  # Evidence-gated code: N candidates, real tests eliminate, judge picks
caphlon max          # Blind verification: generate N candidates, a SEPARATE judge model picks the winner
caphlon serve        # LiteLLM proxy — expose the connected model as an OpenAI-compatible endpoint
caphlon tools        # Connect external agent CLIs (e.g. Claude Code) to Caphlon
caphlon hive         # Hive intelligence: multi-sample consensus
caphlon hermes       # Hermes Agent (Experimental — see Components table)
caphlon flower       # Federated learning (Experimental)
caphlon tokenless    # Token compression (Experimental)
caphlon disconnect   # Remove a provider's key
caphlon cache        # Token-saving pool: stats + sync push/pull (Git-Merkez)
caphlon setup        # Install/repair the platform (real tools)
caphlon status       # System status
caphlon doctor       # Diagnostics (--fix: repairs the setup)
caphlon init         # Initialize a project

🗂 Vault — Obsidian-style knowledge, without Obsidian

People install Obsidian to keep AI context cheap: small linked notes instead of one giant document, so the agent reads a map first and opens only what it needs. Caphlon ships that system natively — plain markdown, [[wiki-links]], no app to install (open the folder in Obsidian anyway if you like, it's the same format).

caphlon vault index    # the one-line-per-note map the agent sees
caphlon vault stats    # measured: index tokens vs whole-vault tokens

In chat it's automatic: the agent calls vault_index (cheap map) → picks → vault_read (only that note; follow_links to pull its neighbours) → and writes durable decisions back with vault_write. Project notes live in .caphlon/vault/, machine-wide ones in ~/.caphlon/vault/.

Measured on a 3-note vault: index ~42 tokens vs whole vault ~115 tokens (63% cheaper) — and the gap widens fast, because the index grows by one line per note while the notes themselves grow without limit.

Works alongside your OpenCode setup. Caphlon adds its profile to OpenCode's config chain instead of replacing it — measured: an oh-my-opencode install (its MCP servers, agents and plugin) loads together with Caphlon's tools and instructions in one merged session.

⚒️ Forge — evidence-gated code (the part no other CLI does)

Every coding CLI writes code and hands it to you; quality control is either the model's own opinion or you running the tests afterwards. Forge inverts the order — "does it work?" is answered by your project's own tests, before "is it good?" is asked at all:

caphlon connect groq --judge          # independent judge (recommended)
caphlon forge "make slugify keep Turkish characters" -n 3

1. Recall — the solution cache and matching skills are injected into the task
2. Generate — N candidates, each in its own isolated git worktree, written by the real Aider
3. Prove — your project's real verify commands run in each (npm test, pytest, cargo test, …)
4. Eliminate — a candidate that fails an essential check is out; no model opinion can save it
5. Choose — an independent judge picks among the proven-working candidates only (falls back to a deterministic rule: fewer warnings, then smaller diff — simplicity wins)
6. Learn — the winning solution goes into the cache for next time

Honest guardrails: if the project has no test/build command, Forge stops instead of guessing; if no candidate passes, it refuses to hand you unproven code; the winner is applied to your working tree without committing, so you review the diff.

Measured run (demo repo with a failing Turkish-slug test): 3 candidates → 1 eliminated by the real test suite → judge picked between the 2 survivors → applied → suite green.

Blind verification: the producer can't grade its own work. Connect a separate judge model and use max: caphlon connect groq --judge → caphlon max "task".

Token-saving cache: before solving any technical problem, the agent calls cache_borrow — a hit returns a previously verified solution instead of regenerating it (~80-90% tokens saved per hit, measured model). Every borrow closes with cache_report (worked / failed + correction), so broken knowledge can't poison the pool. Personal notes never leave the machine; shared entries pass two gates: a secret scan (no keys/tokens) and a safety scan (no malicious content, no destructive commands like rm -rf / curl|sh; risky-but-legit ones surface as warnings instead of silent application). Share across machines/teammates with zero servers: caphlon cache sync push <owner/repo> mirrors the technical pool to a git repo (JSONL; corrections propagate by version) and pull merges it back — the proven skill-sync pattern. Alternatively point at a live Hive coordinator with caphlon hive hub <url> for instant swarm sharing. See caphlon status → Cache panel.

Every component binds to a single model: connect once with caphlon connect and Qualixar OS / Aider / the orchestrator all use the same one. Details: docs/integration/BEST_OF_BREED.md

🐝 Hive Intelligence — the more people use it, the stronger it gets

Even with weak hardware (2GB RAM / 3rd-gen i5) and a weak model, get closer to strong-model quality through crowd + consensus + shared memory. It takes participation, not money. Details: docs/HIVE.md

# Single machine, today — sample the connected model N times, strengthen with consensus
caphlon hive solve "What's the bug in this function?" --samples 5

# Proof: more nodes → more power (simulation)
caphlon hive demo

# Set up a swarm (thousands-of-users scenario)
caphlon hive serve                         # coordinator (or: docker compose up -d hive)
caphlon hive join --id n1                  # each user joins with their own node (n1, n2, ...)
caphlon hive ask "what is 2+2?"            # hive consensus answer

# Accumulated power: submit a local LoRA contribution / pull the current shared adapter
caphlon hive submit-delta --id n1 --delta delta.json
caphlon hive pull --out adapter.json

Power layers: self-ensemble (single user, instant) · swarm consensus (multi-user, instant) · shared solution cache (N users = N× memory) · federated LoRA (accumulated). Security: validator + reputation + honeypot + anomaly filtering. Privacy: raw data never leaves the machine — only weight deltas are shared.

Living Marketplace — learned lessons get shared: caphlon skill evolve extracts a candidate skill from a task trace → an independent judge approves it → the approved lesson is written to learned/. caphlon skill sync push <owner/repo> pushes these lessons to a git repo; another user pulls the same lessons with caphlon skill sync pull without running anything unapproved (it's a git shell-out — we have no distribution protocol of our own). Publishing always requires a separate human approval; even --yes doesn't auto-push.

⚖️ Honest evaluation — real measurements

This project's claims were measured against real models (not marketing, but measurement):

Scenario	SOLO	HIVE	Δ	Why
Strong model (deepseek-v4-flash, 12 hard tasks)	100%	100%	0	ceiling — no room to lift
Weak model (qwen 0.5b, self-ensemble)	50%	50%	0	errors are correlated (always the same mistake)

Bottom line: pure consensus makes no difference when nodes run the same model — because a single model's (or its copies') errors aren't independent, they're systematic (the Condorcet jury theorem requires independence). Real gains require:

• Model diversity (different models → independent errors → consensus corrects them), or
• Shared memory (cache: whoever solves it once, everyone else gets it free — the most solid win), or
• Federated accumulation (with a fail-safe + eval gate).

So "thousands of identical weak nodes → strong model" doesn't work on its own; the correct version of the thesis is diversity + accumulated memory. This is documented by measurement, not assumption.

Components

Layer	Tool	Status	License	Docs
CLI	Caphlon	Core	MIT	README
Interface (TUI)	OpenCode (integrated)	Core	MIT	docs/integration/BEST_OF_BREED.md
Pair-Programming	Aider (integrated)	Core	Apache 2.0	docs/integration/BEST_OF_BREED.md
Orchestrator	Qualixar OS	Conditional	FSL-1.1-ALv2	—
Design/UI Pipeline	Open Design (integrated)	Conditional	Apache 2.0	docs/integration/OPEN_DESIGN_INTEGRATION.md
Memory/Workflow	MiMo Code (integrated)	Conditional	MIT	docs/integration/MIMO_CODE_INTEGRATION.md
Security	Custom (Validator + Reputation + Honeypot)	Conditional	MIT	—
VBS Agent	Hermes Agent	Experimental	MIT	—
Federated	Flower	Experimental	Apache 2.0	—
Fine-Tuning	SmolLM + LoRA (TRL/PEFT)	Experimental	Apache 2.0	—
Token Opt.	tokenless	Experimental	Apache 2.0	—

Core / Conditional / Experimental — an honest label

• Core — where the daily value comes from: the OpenCode TUI, Aider, and Caphlon's own ideas (connect's single-key distribution, the skill layer + blind verification, doctor/status). Without these, Caphlon has no reason to exist.
• Conditional — valuable if you actually use that workflow: Open Design if you do design work, Qualixar if you run multi-agent tasks, MiMo if you use the MEMORY.md/compose patterns. If you don't, it's just disk weight.
• Experimental — wired and working, but has not YET proven end-to-end value: the Hermes→Flower federated training pipeline has never actually been run, tokenless's used surface is narrow, and the Hive's multi-machine federation is speculative on a single machine. "Works" and "needed" are different things.

Rule: if an Experimental piece goes untouched for a few weeks of real use, its copy stays but it drops out of the mental overhead (doctor expectations, setup steps, doc priority). The promote/retire decision comes from usage, not a desk discussion.

Requirements

• Node.js 22 LTS — the Caphlon CLI works with 22+, but Qualixar OS specifically needs 22: 24+ breaks the native better-sqlite3 build (setup-cores.sh looks for a compatible Node 22 via brew/nvm on its own)
• Python 3.11+ (fine-tuning)
• Rust 1.89+ (tokenless)
• 2GB+ RAM (runs CPU-only)