KarvyLoop MCP server
Commit Nov 12, 2026A local-first multi-agent orchestration runtime that crystallizes repetitive tasks into reusable skills and decision preferences.
Also known as Caprista/KarvyLoop
- Stars
- 18
- Tools
- 7
- Downloads, 30 days
- β
- Latest version
- β
- Last commit
- Nov 12, 2026
- License
- MIT
What is KarvyLoop MCP?
KarvyLoop is a local-first multi-agent orchestration runtime that crystallizes repetitive tasks into reusable skills and decision preferences. It exposes 7 tools, such as run_command, read_file, write_file.
Summary generated from the project's README
About KarvyLoop MCP server
Developers looking to automate repetitive workflows can use KarvyLoop to build a local-first multi-agent orchestration runtime. Unlike frameworks that focus on single LLM calls, this system optimizes the entire execution cycle by turning completed tasks into reusable skills and decision preferences. It allows you to assemble teams of agents organized into domains, roles, and atoms, all orchestrated through plain language via the KarvyChat interface.
Running locally on your machine, the runtime ensures your data and learned behaviors remain private assets. You maintain control through a human-in-the-loop mechanism called H2A, where the AI proposes actions via decision cards for your approval. The system supports any Anthropic or OpenAI-compatible endpoint and integrates with MCP servers, whether they are local via stdio or remote via HTTP. To manage costs and safety, it includes a spend brake for token limits and sandboxed execution using bubblewrap or Seatbelt.
What you can do with it
- 1Automate recurring business reportsTransform a repetitive weekly summary task into a written-down method that runs with minimal token costs.
- 2Sync agent knowledge across devicesShare learned beliefs and crystallized skills between your desktop and laptop through an encrypted mesh.
- 3Control agent spending and safetySet hard limits on token usage to prevent runaway background workflows from exhausting your budget.
Written from the project's README. Every use case is checked against a quote from it.
KarvyLoop MCP tools 7
Detected from the READMErun_commandread_filewrite_fileedit_fileweb_searchweb_fetchcreate_atom
Automated checks
Ran Nov 14, 2026Full report βNot verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work Β· What to fix for more points
- Source repository linked and reachablecaprista/karvyloop is public and reachablegithub.com/caprista/karvyloop βPass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html βPass
- Commit or release in the last yearLast commit or release 2026-11-12github.com/caprista/karvyloop βPass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model7 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubKarvyLoop
π Language: English (current) Β· δΈζ
The 40th time your agents run a job, it's cheaper, better-verified, and more your-style than the 1st. That's the whole product.
AI agents Β· multi-agent orchestration Β· LLM runtime Β· loop engineering Β· local-first Β· human-in-the-loop Β· skill crystallization Β· MCP Β· sandboxed execution
Most agent frameworks optimize a call β and the 40th call costs exactly what the 1st did. KarvyLoop optimizes the loop around it: discover work β run β verify β crystallize β you decide β repeat. Every pass leaves something behind on your machine β a skill (the method, written down), a decision preference (how you call it), a belief (what it learned about your world). Value compounds; babysitting decays.
value
β β loop-native (KarvyLoop)
β β
β β
β β
β β
β βββββββββββββββββββββββββββββββββββββββ call-native (most frameworks)
ββββββββββββββββββββββββββββββββββββββββββ times you run the same job
1 10 20 40
Three bets we place against the industry
- Loop-native, not call-native. The unit of design isn't an LLM call β it's the self-running cycle that repeats. A repeated task doesn't cache its answer (stale answers are poison); it crystallizes its method into a readable
SKILL.mdand reruns it on fresh input β often with zero LLM calls. - You stay the decider β by construction, not by option. While the industry races toward maximum autonomy, KarvyLoop hard-codes H2A: the AI proposes on a decision card, you decide. And it earns silence instead of assuming it β only after a decision type clears a statistical bar (Wilson 95% lower bound β₯ 0.90 over 35+ cases) does it offer to handle that one quietly; you grant it explicitly, and a single miss revokes it.
- The image is copyable. Your instance is not. The code is MIT β clone it, fork it, ship it. But the skills, preferences and beliefs that grow on your machine from your use are a local asset nobody else can copy β and no platform can take away.
Receipts, not adjectives: repeated jobs hit a zero-token fast path; a real sandbox on all three platforms (bubblewrap / Seatbelt / restricted-token) with fail-closed capability tokens; 3,800+ tests including 25 adversarial attack-vector classes, in CI; and your agent's memory is inspectable and editable down to "which belief got superseded, when, by what, and why."
If you use AI for real work, you already know the tax: babysitting its output (surveys peg it at ~6.4 hours a week), re-explaining yourself to a tool that forgets you overnight, and a review pile that grows with everything you delegate. KarvyLoop is built to bend that curve the other way: the longer you use it, the fewer approvals it asks of you β and the more accurate they get.
What is KarvyLoop?
KarvyLoop is a runtime for AI agents that run on your own machine. You assemble a team: business domains (a "company" β say, Data Team) staffed by roles (agents with an identity and preferences β an Analyst, a Reviewer), each built from atoms (sub-agents that do one checkable thing, like fetch two CSVs and diff them). A built-in assistant, Karvy π¦«, orchestrates them from plain language. It runs your repetitive work and verifies its own output, and every use crystallizes into a version of you: repeated tasks become skills (the third time you ask for a weekly summary, it's a written-down method reused for pennies), and your choices become decision preferences shown beside future calls. A hard human-in-the-loop rule β H2A: the AI proposes, you decide β means nothing runs until you accept a decision card ("Hand the monthly report to the Analyst?" β you click accept, then it moves).


One 23-second loop: you accept a decision card, glance the 2Γ2 board, drop by the desk where your team works (day and night), and check the skill library's growth curve β more like you with every use.
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.
If you've used other agent tools
- AutoGen / CrewAI are good at making several agents cooperate inside one run. KarvyLoop's unit is the recurring loop across runs: the 40th monthly report should be cheaper, better verified, and more aligned with you than the 1st.
- LangGraph gives you precise control flow inside a task graph. KarvyLoop focuses on what happens around and between tasks β verify gates, decision cards, and the residue each run leaves behind (skills, preferences) that compounds.
- Manus and similar autonomous agents run the "give it a goal and it works" promise in the cloud. KarvyLoop runs it on your machine, keeps you the decider by construction, and everything it learns lands in a local instance that is yours.
In one line: they optimize a single call or a single orchestration; KarvyLoop optimizes the whole loop that repeats β and makes the repetition compound.
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. There's even a desktop view where your agents sit at pixel-art workstations (Karvy the capybara at the hearth, carrying cards to you) β the team as a place, not a config screen.
- π§ 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). Long workflows are interruptible β cancel a run mid-flight and a restart won't quietly resurrect the version that was going wrong.
- π 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 a version of you. Runs that pass a verify gate crystallize into reusable skills β and skills stop being lonely Top-1 hits: a matched skill now pulls in up to two supporting skills so the library gains interest, not just entries. Your accept/reject/edit choices crystallize into decision preferences that pre-align future proposals; roles sediment their own domain-scoped experience (an Analyst gets sharper at being your Analyst, not just globally); and your knowledge resolves its own conflicts β say you're vegetarian now, and last year's "loves steak" is superseded (kept in history, dropped from recall) instead of contradicting itself forever. Copyable code, un-copyable instance β your instance, your data.
- π¬ Decisions reach you β you don't chase them. Pending cards wait on the console, and with the optional email channel they travel to your inbox as a digest with signed one-tap replies (works behind any NAT, no third-party service); a weekly report card sums up what your team ran, spent and learned, every number traceable. Stale cards age visibly instead of silently rotting.
- π€« It's learning when to not ask you. The hit-rate on Karvy's predicted calls isn't just a mirror β per kind of decision, once it's been right enough for long enough (Wilson 95% lower bound β₯ 0.90 over β₯35 cases β a statistical gate, not a streak) it offers to handle that bucket quietly. You grant that silence explicitly (it's never auto-taken, high-risk actions are excluded, and a single miss revokes it) β so over time it starts earning the right to stop interrupting you on the calls it has already learned you'd make.
- π You stay in the driver's seat β even on long, unattended runs. A spend brake enforces hard token/cost limits right at the gateway: a runaway background workflow fail-stops at the ceiling (foreground work you're waiting on is never blocked β so you can hand it the key without fear). A domain's hard rules (deontic "never place a trade") are a deterministic gate on the tools and commands themselves, not a line in a prompt you hope the model obeys. And a built-in doctor (
karvyloop doctor --fix) repairs the safe, deterministic breakages itself and probes liveness (is the model endpoint actually reachable?), so a broken setup tells you why instead of failing mute. - π See why, not just what. As you type, related skills and knowledge surface unprompted (pure local matching β zero extra LLM calls); every skill has a lifecycle timeline (crystallized β revised β rerun) so "why did my skill change" always has an answer.
- π 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.
- π₯οΈ Your devices form one mesh. Same-owner devices share a causally-ordered log (hybrid logical clocks, gossip convergence β no central server): a belief learned on your desktop or a skill crystallized there shows up on your laptop, deletions carry tombstones instead of resurrecting, and a My Devices panel shows the roster β each device's capability fingerprint, presence, and an informed remove (if a device is the only one providing a capability, you're told exactly what your mesh would permanently lose before you confirm). Lost a device? The panel is shaped like an account-security page: one list of everything with access, and revoking asks you to type the device's name β it takes effect on that device's very next request. Cross-network sync goes through the relay (end-to-end encrypted; the relay only ever forwards ciphertext).
- π Multi-provider LLM gateway + MCP. Any Anthropic- or OpenAI-compatible endpoint; one gateway choke-point meters every token β and caches the stable prefix of every call (system + tools tail), so repeated runs read it back from provider cache and cut that slice of input cost by ~80β90% (it's cheaper to keep using). Plug in MCP servers and their tools reach every agent β local (stdio) or vendor-hosted remote (paste a streamable-HTTP URL + optional token, no local process to run).
- π 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 = your data & decisions stay yours β not "the LLM runs on your box". The runtime, your memory, skills and instance live on your machine (
~/.karvyloop/) and are never uploaded; the models are yours to pick β rent a cloud API or run one locally (Ollama). Local-first here means data sovereignty, not zero-cloud. 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 β a restricted-token sandbox (write isolation via WRITE_RESTRICTED token + per-directory ACL whitelist, resource limits via a Job Object) runs skill scripts when it's available; where it isn't (locked-down policy / AV interference), it falls back to a degraded mode that keeps first-party workspace read/write/exec working and fail-closes third-party skill scripts. Honest limits: no admin-free network gate on Windows yet, so a skill that needs network fail-closes here (run it on Linux/macOS); read isolation is relaxed (as on macOS); it defends against mistakes and ordinary untrusted scripts, not a determined escape. |
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, Windows uses a restricted-token + Job Object sandbox β same default-deny-write + network-gate contract (Linux/macOS network gate is full; Windows fail-closes network rather than pretend). macOS adversarially verified on Apple Silicon / macOS 26; Windows write isolation + resource limits adversarially verified on Win11 Home.
β οΈ 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 uses Linux + bubblewrap, macOS (built-in sandbox-exec), or Windows (built-in restricted-token + Job Object sandbox β no extra dependency); everything else is cross-platform. On Windows, skills that need network fail-close (no admin-free network gate yet); where the restricted-token sandbox can't initialize, it degrades to first-party-only with third-party skill scripts disabled.
# 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).
Your first 5 minutes
The whole loop, one pass β roughly a minute per step:
- Install & connect (Quickstart above). You should see: the console opens, verifies your key, and Karvy greets you.
- Say one small, concrete thing to Karvy in the private chat β e.g. "list the 5 largest files in my workspace." You should see: it runs and streams the result back. That's the execution loop.
- Give it something to route. Create a domain with one role from the left nav (30 seconds), then tell Karvy "hand the monthly report to the Analyst." You should see: Karvy doesn't act β a decision card appears under π€ with what it's about and on what basis.
- Decide. Accept as-is, or edit a line first ("β¦and keep it under 200 words"). You should see: the work runs, and your call lands in π³ Recent calls.
- Come back later. You should see: your edit has become a standard shown beside the next card, and the repeated task is on its way to becoming a skill. You get asked less, and more precisely β that's the point.
Want the same journey slower, with more of the why? See the guided first 15 minutes below.
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 β local stdio (command) or vendor-hosted remote over streamable HTTP (url + optional bearer token); tools are injected into every agent (keys prefixed mcp_<server>_) |
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 |
| relay | pip install -e ".[relay]" |
End-to-end encryption for the Karvy messenger relay: reach your console from anywhere via karvyloop console --relay + karvyloop relay-pair (the relay itself β karvyloop relay-serve β is stateless, blind-forwarding, and needs no extra) |
--relay / relay-pair refuse with a clear "pip install karvyloop[relay]" message |
| files | pip install -e ".[files]" |
Real attachment parsing: PDF / Word (.docx) / Excel (.xlsx) are extracted to text for the files-panel preview and for agents analyzing them (CSV/plain text need nothing extra); corrupted or mislabeled files are refused with a clear error β never binary garbage | Previewing/reading those formats returns a clear "pip install karvyloop[files]" message |
| asr | pip install -e ".[asr]" |
Local audio transcription (faster-whisper, MIT): meeting recordings / voice memos (mp3/wav/m4a) become text on your machine β same attachment pipeline as PDFs, so the files panel previews them and roles (e.g. meeting-notes) consume the transcript. First use downloads a speech model (default small, β480 MB; KARVYLOOP_ASR_MODEL picks another); CPU is enough, nothing is uploaded |
Audio files return a clear "pip install karvyloop[asr]" message β never fabricated transcripts |
| 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.
You don't need to memorize this table: the console has an "Unlock more capabilities" panel (Skill Library β π, also linked from Diagnose and at the end of the first-10-minutes journey) that detects each capability's live status β ready / not set up / needs install β and shows exactly what each one is worth and how to get it, including where to find MCP servers (the official registry and community directories like PulseMCP and Glama).
Optional: connect your own external AI runtime (BYO)
Installing KarvyLoop is one command (the Quickstart above). Connecting an external AI runtime is a separate, on-demand step β and it's entirely optional.
Beyond its own agents, KarvyLoop can treat a third-party headless CLI agent you already run (any of the various headless CLI agents out there) as a channel participant: you @ it for work and see it run. That external runtime is software you bring yourself β KarvyLoop does not bundle, host, download, or ship it. You install it from its own official source, on your own terms; we only point you there.
By design, an external runtime stays an opaque, untrusted executor: its output is untrusted data, it never takes a decision seat, and it never touches your memory or crystallized skills (those are the moat). You manage connected runtimes from the console's External Runtimes panel (π in the left nav) β each shows a distinct external badge so it's never mistaken for a native role, plus a live status light, a direct-chat button, and a remove button. The Diagnose panel and that same panel detect whether a compatible runtime is installed and, if not, walk you through connecting one from its official docs.
- What we ship: the bridge, adapters, and management UI to connect one β and honest guidance on where to get it.
- What we don't ship: the runtime itself. No vendoring, no hosting, no
git cloneof anyone's code.
KarvyLoop MCP questions
What tools does KarvyLoop MCP provide?
It exposes 7 tools, including run_command, read_file, write_file, edit_file, web_search.
How does KarvyLoop handle repetitive tasks?
It crystallizes repeated tasks into reusable skills (written-down methods) and decision preferences, allowing subsequent runs to be cheaper and more aligned with your style.
Is my data and learned behavior private?
Yes, the runtime is local-first, meaning the skills, preferences, and beliefs that grow on your machine are local assets that cannot be copied by others.
Can I use my own LLM providers?
Yes, it supports any Anthropic- or OpenAI-compatible endpoint and includes a gateway to meter tokens and cache stable prefixes to reduce costs.
How secure is the execution of third-party skills?
Third-party skills run in a sandboxed environment (bubblewrap on Linux or Seatbelt on macOS) with integrity locking to prevent tampering.