KarvyLoop

KarvyLoop

> 🌐 Language: English (current) · [中文](README.zh-CN.md)

A local-first, loop-native AI agent runtime — build a team of AI agents that run your work, verify themselves, and compound into skills that are yours, while you stay the one who decides.

AI agents · multi-agent orchestration · LLM runtime · loop engineering · local-first · human-in-the-loop · skill crystallization · MCP · sandboxed execution

---

What is KarvyLoop?

KarvyLoop is a runtime for AI agents that run on your own machine. You assemble a team — business domains (like companies) staffed by roles (agents with an identity and preferences), each built from atoms (single-responsibility sub-agents) — and a built-in assistant, Karvy 🦫, orchestrates them from plain language. It runs your repetitive work, verifies its own output, and crystallizes every use into a version of you (skills, knowledge, decision preferences) — all while a hard human-in-the-loop rule (the AI proposes, you decide) keeps you in the driver's seat.

Where most agent frameworks make a single LLM call more reliable, KarvyLoop is loop-native: the unit of design is the whole self-running cycle — discover work → run it → verify → compound → (you decide) → repeat. The companion chat surface is KarvyChat.

> Most AI tools sideline you, burn tokens, and feel the same for everyone. KarvyLoop keeps you in the driver's seat, stays affordable, and turns every use into a version of you that can't be copied.

Features

• 🤖 A team of AI agents, locally. Create domains (companies) with roles (agents) composed of reusable atoms (sub-agents) — an OS-like L0→L4 entity ladder.
• 🧭 Plain-language orchestration, you approve. Tell Karvy "get a few people in Product to analyze the competitor" — it plans a single hand-off, a roundtable (agents think in parallel, then converge), a workflow (multi-step pipeline), or an ops check, and returns a decision card. Nothing runs until you confirm (H2A).
• 🔁 Loop-native design. Two loops with opposite natures — the execution loop (an atom does a job, self-verifies; fully automated) and the decision loop (role ↔ you; deliberately not automated). The role/atom split is that cut.
• 🧠 Everything compounds into you. Runs that pass a verify gate crystallize into reusable skills; your accept/reject/edit choices crystallize into decision preferences that pre-align future proposals. This is the moat — copyable code, un-copyable instance.
• 📚 Personal knowledge base + cognition graph. Feed it links or notes; it distills them into searchable beliefs on a mesh graph (grep + concept overlap, no vector DB), browsable in the console.
• 🔌 Multi-provider LLM gateway + MCP. Any Anthropic- or OpenAI-compatible endpoint; one gateway choke-point meters every token. Plug in MCP servers and their tools reach every agent.
• 🔒 Safe by construction. Every task carries a capability token; file/network/process access is checked against it; third-party skills run in a bubblewrap (Linux) / Seatbelt (macOS) sandbox and are integrity-locked (a tampered skill directory is refused at both index and execution). The console rejects cross-origin browser requests (same-origin gate on HTTP + WebSocket) on top of the access token for non-local devices. Audit the whole surface in one table via the Capability overview card in the Skills panel. It sits below the agent's trust boundary — it can't be bypassed.
• 🏠 Local-first & private. Runs on localhost; your data lives in ~/.karvyloop/, never uploaded. MIT-licensed; ships by version and never upgrades itself without your click.

Supported platforms

| OS | Status | |----|--------| | Linux | ✅ First-class — full security sandbox (bubblewrap). | | macOS | ✅ Supported — built-in Seatbelt sandbox (sandbox-exec), same fail-closed contract as Linux; newer, so rougher. | | Windows | ✅ Supported (degraded) — runs fully; third-party skill scripts disabled (no sandbox yet); Linux/macOS get the full sandbox. |

KarvyLoop is a cross-platform user-space runtime (pure Python; it doesn't ride on the Linux kernel). The only platform-specific piece is the sandbox: Linux uses bubblewrap, macOS uses the built-in sandbox-exec — same write-isolation + network-gate behavior (macOS adversarially verified on Apple Silicon / macOS 26).

> ⚠️ Early and under active development. KarvyLoop is pre-1.0 and moving fast. Many features aren't fully tested yet and rough edges are expected — we're opening it up early to sharpen it together. Bug reports are gold. 🙏

---

Quickstart

Requirements: Python 3.11+. Sandboxed skill execution needs Linux + bubblewrap or macOS (built-in sandbox-exec); everything else is cross-platform — Windows runs in degraded mode (third-party skill scripts disabled, all else works).

# 1) Install — puts `karvyloop` on your PATH, isolated (safe on PEP 668 / "externally managed" distros)
curl -fsSL https://raw.githubusercontent.com/Caprista/KarvyLoop/main/scripts/install.sh | bash
#    Windows (PowerShell):  irm https://raw.githubusercontent.com/Caprista/KarvyLoop/main/scripts/install.ps1 | iex
#    (developing against a clone instead?  pip install -e .  — but see "karvyloop not found?" below)

# 2) Configure a model (keys live OUTSIDE the repo)
mkdir -p ~/.karvyloop
$EDITOR ~/.karvyloop/config.yaml   # see "Minimal config" below

# 3) Run the local console (web UI)
karvyloop console --host 127.0.0.1 --port 8766
# open http://127.0.0.1:8766

Minimal ~/.karvyloop/config.yaml (replace ${ANTHROPIC_KEY} with an env var or literal key — never commit a real key):

lang: en
models:
  providers:
    anthropic:
      base_url: https://api.anthropic.com
      auth_header: x-api-key
      messages_path: /v1/messages
      api_key: ${ANTHROPIC_KEY}
      models:
        - id: anthropic/claude
          name: Claude
          api: anthropic-messages
          context_window: 200000
          max_tokens: 8192
agents:
  defaults:
    model: anthropic/claude
embedding:
  model: anthropic/claude

> You can also manage models in the console (left nav 🤖 Models). Any Anthropic-compatible endpoint works; OpenAI-compatible endpoints use api: openai-completions. > Just want to see the UI without a model? karvyloop console --no-llm (read-only, no key needed).

Optional features (extras)

The base install runs the whole product. A few capabilities need an extra package — all of them degrade gracefully when absent (Karvy keeps working, you just don't get that one feature, and where you try to use it you get a clear "install X" message — never a crash). Install only what you need:

| Extra | Install | Unlocks | Without it | |---|---|---|---| | mcp | pip install -e ".[mcp]" (+ pip install uv for uvx) | Connect any MCP server; its tools are injected into every agent (keys prefixed mcp__) | MCP tools unavailable; using one returns a clear "install mcp" error | | web | pip install -e ".[web]" then playwright install chromium | Real runtime verification of web output (karvyloop verify-web) — actually loads the page | Falls back to syntax-only checks; honestly tells you runtime wasn't verified | | redis | pip install -e ".[redis]" | Cross-process / cross-machine agent collaboration (Redis A2A transport) | Auto-falls back to in-process transport — fine for a single process | | dev | pip install -e ".[dev]" | Run the test suite (pytest, respx, …) | — (only needed to develop/test KarvyLoop) |

Combine them: pip install -e ".[mcp,web]". None of these gate the core loop — chat, domains/roles, decisions, skills, and token accounting all work on the base install.

Your first 15 minutes

No need to understand agents — here's the whole loop, end to end:

1. Start & connect a model (~5 min). karvyloop console → the setup screen asks where your AI comes from; pick a provider, it shows a "get a key (30s)" link, paste the key, it verifies it works. (Prefer running locally? Pick the local option and follow the install hint.) Your key lives in ~/.karvyloop/config.yaml, never in any repo.
2. Talk to Karvy. In the private chat, ask for something small and concrete. It runs it and returns — that's the execution loop.
3. Make a team. Left nav → create a business domain (like a company) and give it a few roles (e.g. domain "Data", roles "Analyst" and "Reviewer").
4. Hand off work. Back in the private chat with Karvy, say something like "hand the monthly report to the Analyst." Karvy doesn't barge into the domain — it proposes routing it, and a decision card appears under 🤝.
5. Decide. The card tells you, in your terms, what it's about and on what basis; it shows a verified region (✓/✗) separate from Karvy's narration; your own standards are pre-aligned beside it. Accept / edit a criterion / reject — your call. It then shows up in 🗳 Recent calls so you can look back.
6. It compounds. Your accept/reject/edit choices crystallize into decision preferences that pre-align future proposals (you're asked less, re-explain yourself less); repeated tasks crystallize into skills a "fast brain" reuses — cheaper and more you each time.

---

The idea — why "loop-native"

> This section is the why. If you just want to run it, everything above is enough — come back when you're curious what makes it different.

The industry climbed a ladder of paradigms: prompt engineering → context engineering → harness engineering. Each rung made a single LLM call more reliable. Today's agent runtimes are harness-native: they wrap one call in scaffolding — tools, ReAct, retries, guardrails — to make one agent dependable.

KarvyLoop is loop-native. The unit of design isn't a call or an agent — it's the whole self-running cycle that finds work, runs it, checks itself, and compounds:

discover work → run it → verify independently → COMPOUND (crystallize) → (you decide) → repeat
        ▲                                                                      │
        └──────────────── the loop gets cheaper & more "you" each turn ────────┘

That shift sounds incremental. It isn't — because of one uncomfortable fact about loops:

> The same loop, in two people's hands, produces opposite outcomes. For one it compounds into leverage. For the other it quietly takes over their judgment, one accepted suggestion at a time, until they can no longer tell whether the output is right — they've been automated out of their own work without noticing. A loop is not neutral. What decides which outcome you get is whether you stay the engineer of the loop or slide into being its spectator.

Everything below is how KarvyLoop is built so you stay the engineer.

> Everyone is building agents that need you less. KarvyLoop builds the agent that learns how you decide — and proves it by never deciding for you.

Two loops, not one

Look closely and a running loop is really two loops with opposite natures:

• The execution loop — how to do X. An atom (L1) does one job and can write a verify gate for its own output. This loop is fully automatable, and it's becoming a commodity — everyone's execution loop converges to roughly the same thing.
• The decision loop — whether, and on whose terms. This runs between a role (L2) and you. It can't be automated, because automating it is the failure mode above. It's where your intent, taste, and accountability live.

How do you tell which loop something belongs to? One knife, and it never wavers: "does it carry your responsibility?" Direction, trade-offs, sign-off → decision loop, stays with you. Purely getting the work out → execution loop, goes to the machine.

So KarvyLoop automates the execution loop hard (cheap, fast, self-verifying) and refuses to automate the decision loop. The role/atom split in the architecture is this cut. H2A (the AI proposes, you decide) isn't a setting you can switch off — it's the structural guarantee that the decision loop stays yours.

One more consequence of taking the decision loop seriously: if you ever have to ask "how's that task going?", the decision loop has already collapsed — you've become the system's heartbeat monitor. Roles here work under a resourceful subordinate contract: hit a wall, exhaust self-help first (swap plan, swap atom, find or forge a skill); come back only when it's genuinely infeasible — with evidence ("tried these three routes, stuck here, need you to decide this"), never a silent hang, never a bare "failed". Blocked work surfaces itself; your attention is spent on deciding, not checking up.

Staying the decider takes more than a yes/no button

A veto you can't exercise intelligently is theater. To really keep the wheel you have to understand the decision — but understanding can't mean "go read the tool logs." The distance between what the system did and what you can tell from its output is what Don Norman called the Gulf of Evaluation, and the obvious fixes make it worse:

• The overtrust trap. A large review of AI explanations (Microsoft, ~60 studies) found that more explanation increases reliance regardless of whether the answer is correct — a fluent rationale earns trust it hasn't deserved. "Just explain more" doesn't keep you in control; it lulls you out of it.
• Over-judgment = no judgment. Ask for a decision too often and the human either kills the loop or rubber-stamps everything — both are surrender. There's a narrow band between asking too little (silent autopilot) and too much (decision fatigue).

KarvyLoop's answer is a translation layer with two hard rules:

1. Grounded, not trust-inducing. What the loop claims to have solved may be shown as solved only when it passed a deterministic verify gate. Everything else is presented as Karvy's narration and visibly marked "not verified." Your phone isn't "slow because storage is full" — you're told what was actually checked, and what wasn't.
2. Decision-forcing, not explanation-dumping. The interface doesn't try to make you trust it; it makes you judge. It surfaces rarely (pure verified success doesn't interrupt you), and when it does it puts your own prior standards next to the call, asks you to keep / edit / drop the criteria, and won't let a high-stakes accept be rubber-stamped.

Concretely, this is the decision card: the problem and approach in your terms; a verified region (✓ / ✗, traceable to the gate) kept visibly separate from Karvy's narration; your own crystallized standards pre-aligned beside it; and a gate that stops a high-stakes "accept" you were about to wave through. That — not a checkbox — is what "you stay the decider" is actually made of.

> The verified ✓ region appears for a step that passed an automatic verify gate; many steps have nothing to auto-verify, so they show honestly as narration marked "not verified" rather than a fake ✓. That region lights up for more of your work as verify gates get wired into more flows — we'd rather show you less green than green you can't trust.

The compounding wedge: two loops, two crystallizations

The two loops don't just run — each one sediments, and each sediments a different thing:

• The execution loop crystallizes into skills — how you work. Every run is observed; once it passes a verify gate and is used enough, it crystallizes into a persistent skill. Next time a "fast brain" hits it directly: cheaper, and shaped to you.

And a rule we consider load-bearing: a skill stores the method, never the answer. Caching last quarter's competitor list and replaying it six months later isn't memory — it's **poisoning your

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Caprista
• Source: Caprista/KarvyLoop
• License: MIT

Install and usage instructions live in the source repository linked above.