Convergio — where AI agents and humans converge on data both can trust.
Open, local-first, EU-sovereign. The good Palantir, for places Palantir cannot go.

Convergio

Make machines prove it. Make data trustable. A local Rust daemon that refuses an AI agent's "done" when the evidence doesn't match the claim — and a typed ontology layer (in progress) so AI and humans share the same schema, the same history, and the same audit chain.

The 30-second pitch

You let an AI agent code for you, or read for you, or decide for you. It says "done". You check — TODOs, unwrap(), skipped tests, hardcoded strings, hallucinated rows, missing provenance. You redo it. Or worse, you don't notice.

Convergio fixes both loops:

• 🛑 Refuses unsafe done — server-side gates reject the transition with HTTP 409 when evidence contains debt markers, scaffolding tells, secrets, or a non-clean build.
• 📒 Tamper-evident audit — every refusal lands in a hash-chained log you can verify from outside the daemon.
• 🇪🇺 EU-sovereign by construction — local-first, no telemetry, no remote control plane, OSI-licensed under AGPL-3.0-or-later (see LICENSE, ADR-0074). Deployable in regulated public-sector, healthcare and civic contexts. See COMPLIANCE.md.
• 🔌 Vendor-agnostic — drives Claude Code, Copilot CLI, Qwen, Codex, Gemini, or your own runner. No API keys held, no SaaS.
• 🧱 Typed ontology (in progress) — schema registry, bitemporal store, provenance bundle, purpose registry, typed actions. The shared substrate AI and humans converge on. Status declared per primitive in COMPLIANCE.md.

100% local. SQLite-only. Try it in 60 seconds → Quickstart.

Convergio cannot make an agent truthful — but it raises the cost of lying, and makes every refusal non-falsifiable. See ADR-0073 (EU-sovereign pivot) and docs/vision.md for the full framing.

What Convergio is — and is not

Convergio is…	Convergio is not…
The convergence layer — typed ontology + gates + audit, where AI agents and humans operate on the same trustable substrate.	A model, a SaaS, a closed-source data platform.
The execution layer — plan → dispatch → audit → gate.	The strategic / planning layer.
The leash that decides which task runs on which model.	A model. Convergio never calls a raw API; it spawns the operator's own vendor CLI.
Local-first, single-user, SQLite-only, EU-sovereign by construction.	A SaaS. There is no Convergio cloud.
Vendor-agnostic — claude, copilot, qwen, codex, gemini.	Tied to a single vendor.
Composable — drives any framework that emits a plan.	An agent framework.
The good Palantir — open, auditable, operator-owned, deployable where Palantir cannot go (EU public sector, civic infrastructure, NGOs).	A Palantir clone. The closed, geopolitical, contractor-only model is exactly what Convergio refuses.

Composes with planners like gstack (strategic layer) and aligns technically with the ISE Engineering Fundamentals Playbook. See Composability and alignment below for the full picture.

Compliance posture (honest status)

Convergio aims at deployable use in EU regulated contexts (GDPR, EU AI Act, NIS2, DORA, EU Data Act, eIDAS). The COMPLIANCE.md matrix maps every requirement to a Convergio primitive with one of three honest statuses:

• ✅ enforced — implemented and CI-checked today (hash-chain audit, local-first binding, no telemetry, six sacred principles P1..P6).
• 🟡 partial — primitive exists, full enforcement pending (typed ontology runtime, bitemporal store, purpose registry — tracked under W15/W16/W17 in the EU-sovereign pivot plan).
• 🟠 planned — designed in ADR, not implemented yet (cross-tenant scenario branching, formal eIDAS signing path).

No EU-sovereignty claim is made without a verification command. See COMPLIANCE.md § "Verification".

Why Convergio

The hard failure mode for coding agents is not one bad completion. It is many agents working at once:

• overwriting the same files;
• diverging across worktrees;
• producing broken merges and noisy CI;
• losing process-local state;
• claiming "done" without evidence.

Convergio's design answer is:

1. durable task/evidence state;
2. hash-chained audit;
3. CRDT-aware multi-actor metadata;
4. workspace resource leases;
5. patch proposals and merge arbitration;
6. server-side gates that refuse unsafe submitted/done transitions.

All six are implemented in the local runtime. The current release line also includes signed local capability install/remove, a planner.solve capability action, a constrained local shell runner proof, shell, claude, and copilot runner kinds, the MCP bridge, the code graph, the executor loop, and the cvg dash terminal dashboard.

Since v0.3.29 the fleet abstraction (ADR-0038, F3 closed in ADR-0049) lets one daemon orchestrate multiple repos. The advisory-only surface today: cross-repo plans with per-repo task fan-out (POST /v1/fleet/plans + cvg fleet plan create), Thor-driven fleet validation (POST /v1/fleet/plans/:id/validate), derived fleet audit-chain walk (cvg audit verify --fleet <id>), semantic dead-code candidates with role-aware thresholds (GET /v1/fleet/rot), and semantic doc-vs-code drift via snapshot embeddings (GET /v1/fleet/doc-drift + POST /v1/fleet/doc-drift/snapshot). MCP fleet actions (fleet_plan_create, fleet_plan_show, fleet_plan_validate) expose the same operations over stdio. CLI verbs for fleet rot / fleet doc-drift are deferred until the convergio-cli split. Remote capability registry and ACP bridge remain roadmap work.

See docs/vision.md for the product vision.

Principles, and which ones are actually enforced today

The five principles below are the product's identity. Each one carries an explicit status — enforced, partial, or planned — so the README does not claim more than the code does.

1. P1 — Zero tolerance for technical debt, errors and warnings. enforced. NoDebtGate (7 languages), NoStubGate, and ZeroWarningsGate refuse submitted/done transitions when evidence contains debt markers, scaffolding tells, or non-clean build/lint/test signals.
2. P2 — Security first, local first. partial. Localhost-by-default bind, evidence-as-untrusted-input, NoSecretsGate (gitleaks pattern set), and PromptInjectionGate (eight LLM prompt-injection rule families over every evidence payload at submitted/done; see ADR-0050) are shipped. DepsAuditGate and HMAC middleware for non-loopback bind remain roadmap.
3. P3 — Accessibility first. enforced (phase 1). A11yGate ships built-in checks (heading order, image alt, descriptive link text, color-only emphasis, ANSI color-only signal, bidi spoofing) at every submitted/done transition; see ADR-0051. Phase 2 (capability a11y.axe, axe-core wrap) remains roadmap. The CLI remains screen-reader friendly without color by convention; the gate enforces the evidence side.
4. P4 — No scaffolding only. enforced. Two gates ship in default_pipeline(): NoStubGate refuses evidence that says it is a stub, placeholder, skeleton, or not wired; WireCheckGate (opt-in via a structured wire_check evidence row) verifies that every claimed HTTP route and CLI subcommand actually exists in the workspace tree. A future ClaimCheckGate (F55-B) will force the opt-in wire_check row to be present.
5. P5 — Internationalization first. enforced. CLI user-facing strings go through Fluent bundles with English and Italian shipped together; a coverage test refuses partial locales.

See CONSTITUTION.md for the full rule set, and docs/plans/v0.1.x-friction-log.md for the gaps the next release will close.

Quickstart

sh scripts/install-local.sh
cvg setup

convergio start

In another terminal:

cvg doctor
cvg health
cvg demo

Optional daemon service:

cvg service install
cvg service start

For agents:

cvg setup agent claude   # or cursor, cline, continue, qwen, shell, copilot-local
cvg mcp tail             # inspect bridge diagnostics

Agent hosts that support MCP should connect the stdio command convergio-mcp; it exposes only convergio.help and convergio.act. See docs/agents/README.md for host-specific setup snippets.

Release artifacts can be built locally with scripts/package-local.sh and signed/notarized on macOS with scripts/sign-macos-local.sh; see docs/release.md.

Defaults:

• SQLite database: ~/.convergio/v3/state.db
• HTTP bind: 127.0.0.1:8420
• No external services
• No account, tenant, or server setup

You can override the local database file when needed:

convergio start --db sqlite:///tmp/convergio.db?mode=rwc

Manual local loop

cvg plan create "ship one clean task" --project convergio-local
cvg status
cvg task list <plan_id>
cvg task transition <task_id> in-progress --agent-id local-agent
cvg evidence add <task_id> --kind code --payload '{"diff":"fn main() {}"}' --exit-code 0
cvg evidence add <task_id> --kind test --payload '{"warnings_count":0,"errors_count":0,"failures":[]}' --exit-code 0
cvg task transition <task_id> submitted --agent-id local-agent
cvg validate <plan_id>
cvg audit verify

Use cvg demo first: it creates one dirty task that gets refused by the gates, then one clean plan that validates and verifies the audit chain.

What you get

Convergio is organised like a city: a stable civil code in the lower layers, public infrastructure in the middle, and replaceable services at the edge. Each crate has one civic role, one owner boundary, and one reason to exist.

Crate	Civic role	What it does	Platform value	Principle alignment
convergio-db	Land registry	Opens the SQLite pool and runs per-crate migrations.	Gives every layer one local, durable substrate.	P2 local-first, P1 predictable schema.
convergio-durability	City hall + code enforcement	Owns plans, tasks, evidence, audit chain, gates, CRDT/workspace coordination, reaper and capability registry.	Makes work durable, reviewable and rejectable instead of conversational.	P1 gates, P2 audit/security, P4 no scaffolding, P5 evidence for localized surfaces.
convergio-bus	Postal service	Persists plan-scoped topic/direct messages and acknowledgements.	Lets agents coordinate without hidden process memory.	P2 durable local communication, P4 fully wired collaboration.
convergio-lifecycle	Workforce registry	Spawns agents, records heartbeats, watches process exit state.	Keeps agent work attached to real processes and recoverable leases.	P2 controlled local execution, P1 observable failures.
convergio-graph	Planning office map	Builds a code graph and produces task-scoped context packs.	Gives agents narrower, evidence-backed context instead of whole-repo flooding.	P1 less drift, P2 reduced prompt-injection surface, P4 wired context.
convergio-server	Public counter	Exposes the localhost HTTP API and wires the daemon loops.	One stable front door for CLI, MCP and custom runners.	P2 localhost by default, P4 routes cannot bypass gates.
convergio-cli	Clerk desk	Provides the cvg human/admin client over HTTP.	Lets operators inspect, drive and repair the local runtime.	P3 accessible terminal UX, P5 localized output where surfaced.
convergio-tui	Control room	Powers cvg dash, a read-only four-pane terminal dashboard.	Makes plans, tasks, agents and PRs visible without changing daemon state.	P3 terminal-first visibility, P2 read-only observer boundary.
convergio-i18n	Translation office	Loads Fluent bundles and tests locale coverage.	Keeps user-facing CLI strings English + Italian from day one.	P5 enforced.
convergio-api	Common legal language	Defines the stable agent action schema and schema version.	Keeps MCP/agent clients synchronized with daemon capabilities.	P1 contract tests, P4 no drift between protocol and implementation.
convergio-mcp	Embassy	Bridges MCP hosts to convergio.help and convergio.act.	Lets external agents use Convergio without learning every HTTP route.	P2 constrained tool surface, P4 action dispatch sync.
convergio-planner	Urban planner	Turns a mission into a structured plan.	Provides a reference planning flow on top of the core runtime.	P4 plans become executable tasks, not prose only.
convergio-executor	Dispatcher	Claims ready tasks and spawns configured agents; also runs as a daemon loop.	Moves ready work forward without manual polling while keeping cvg dispatch as a test seam.	P1 observable dispatch, P2 supervised execution, P4 fully wired Layer 4.
convergio-thor	Inspector	Validates submitted tasks and is the only component allowed to mark work done.	Separates "agent says done" from "system accepts done".	P1/P2/P4 final gatekeeping.

Layer 4 is intentionally replaceable. The product value is the local runtime and its gates; your own agent client can call the HTTP API directly or use the MCP bridge.

flowchart TB
    subgraph L4["Layer 4 - replaceable city services"]
        CLI["convergio-cli\ncvg clerk desk"]
        TUI["convergio-tui\ncvg dash control room"]
        PLANNER["convergio-planner\nurban planner"]
        EXECUTOR["convergio-executor\ndispatcher loop"]
        THOR["convergio-thor\ninspector"]
        API["convergio-api\ncommon legal language"]
        MCP["convergio-mcp\nagent embassy"]
    end

    subgraph SHELL["Daemon shell"]
        SERVER["convergio-server\nlocalhost public counter"]
    end

    subgraph L3["Layer 3 - workforce registry"]
        LIFE["convergio-lifecycle\nspawn heartbeat watcher"]
    end

    subgraph L2["Layer 2 - postal service"]
        BUS["convergio-bus\nmessages ack cursor"]
    end

    subgraph L1["Layer 1 - city hall and planning map"]
        DUR["convergio-durability\nplans tasks evidence gates audit"]
        GRAPH["convergio-graph\ncode graph context packs"]
    end

    DB["convergio-db\nSQLite land registry"]

    CLI --> SERVER
    TUI --> SERVER
    MCP --> API
    MCP --> SERVER
    PLANNER --> SERVER
    EXECUTOR --> DUR
    EXECUTOR --> LIFE
    THOR --> DUR
    SERVER --> DUR
    SERVER --> BUS
    SERVER --> LIFE
    SERVER --> GRAPH
    DUR --> DB
    BUS --> DB
    LIFE --> DB
    GRAPH --> DB

    classDef law fill:#eef6ff,stroke:#2f6fed,color:#111;
    classDef service fill:#f7f7f7,stroke:#888,color:#111;
    class DUR,GRAPH law;
    class CLI,TUI,PLANNER,EXECUTOR,THOR,API,MCP service;

Loading

Project status

Current scope - local-first SQLite runtime.

Current scope:

• SQLite-only local runtime
• localhost HTTP API
• cvg status snapshot dashboard for active plans and recently completed work
• cvg dash interactive TUI (4-pane htop-style: plans, active tasks, agents, PRs — ADR-0029)
• hash-chained audit verification
• server-side quality gates
• common local secret-leak refusal
• persistent local message bus
• task context packets and plan-scoped bus actions for MCP agents
• CRDT actor/op schema, deterministic import/merge and conflict surfacing
• workspace leases, patch proposals and merge queue arbitration
• process spawn/heartbeat/watcher
• vendor-CLI runners — claude, copilot built-in (ADR-0028, ADR-0032); qwen, codex, gemini and others via ~/.convergio/runners.toml registry, no recompile (ADR-0035)
• per-task runner_kind / profile / max_budget_usd (ADR-0034)
• least-privilege permission profiles standard / read_only / sandbox (ADR-0033)
• opus-backed planner (claude:opus in --permission-mode plan) with deterministic line-split fallback (ADR-0036)
• local capability registry, Ed25519 package signature verification, and signed local install-file/remove
• planner.solve as the first installed capability-gated action
• executor tick, Thor validator, guided demo
• English/Italian CLI messages for the localized surfaces
• cvg coherence suite — Tier-2 cross-checks for routes, ADRs, agents, fleet plans, handshakes, and plan-execution (ADR-0040)
• fleet abstraction — one daemon orchestrates multiple repos: cross-repo plans, semantic dead-code (cvg fleet rot), semantic doc-drift (cvg fleet doc-drift), fleet audit-chain walk (ADR-0038, ADR-0049 retrospective)
• compensating actions — cvg audit compensate <seq> [--apply] to invert any audit row that has a defined inverse (ADR-0048)
• generated action surface — cvg actions list and GET /v1/api/actions are byte-identical with MCP discovery (ADR-0047)
• gate preconditions introspection — cvg gates show / GET /v1/gates/preconditions to ask "what evidence does this gate need?" before bouncing off a refused submit

Recently shipped (v0.3.32 → v0.3.35):

• EU-sovereign layer — relicensed to AGPL-3.0-or-later (ADR-0074); convergio-provenance W3C PROV-JSON bundles for ontology objects (ADR-0075); convergio-gdpr data-subject-rights handlers (Art. 15/16/17/18/20/21/22) wired at POST /v1/gdpr/requests with an audit row per fulfilment (ADR-0076); purpose-binding middleware (every request carries an x-purpose-id)
• Ontology runtime — typed object / link / property storage, a bitemporal object event log, an actions base + registry with idempotency, SHACL + JSON-Schema export, semantic helpers and graph projection (convergio-ontology, ADR-0051)
• Hybrid retrieval — convergio-embed semantic search fused with structural code-graph hits (RRF / linear blend) on the graph search surface
• Platform features — report engine + ReportTemplate object type (convergio-reports), connector framework + reference SIS/Canvas connectors (convergio-connector), an LLM-gateway entry point, a public algorithm register, a unified search route, and tracker-only dispatch (--executor none / --no-dispatch) alongside cvg fleet dispatch per-repo worktree caps

Out of scope for this MVP:

• remote multi-user deployment
• account, tenant, or RBAC model
• hosted graphical UI
• hosted service
• agent marketplace

The workspace test suite covers the local runtime, gates, audit tamper detection, CLI smoke behavior, CRDT/workspace flows, MCP actions, and HTTP E2E workflows.

Documentation

• ARCHITECTURE.md - layers, API and request lifecycle
• CONSTITUTION.md - non-negotiable rules
• docs/vision.md - product vision and positioning
• docs/multi-agent-operating-model.md - how multiple agents coordinate through one daemon
• ROADMAP.md - focused local-first roadmap
• CONTRIBUTING.md - development workflow
• docs/adr/ - architecture decision records

Composability and alignment

Convergio is the machine that builds machines, safely. A typical full stack looks like:

Layer	Tool	What it owns
Strategic	gstack — preferred partner	/autoplan, /office-hours, /plan-eng-review, design + eng review.
Memory	gbrain (PGLite + Supabase, opt-in)	Long-term context, lessons, vault.
Execution	Convergio	Per-task runner routing, audit, gates, lifecycle, MCP / HTTP / CLI surface.

You can drive Convergio with gstack's /autoplan (recommended), with another planner, or by writing the plan yourself — it works with anything that produces a mission. gstack is the preferred partner: same author philosophy, same engineering-fundamentals framing, complementary scopes. Convergio works without it; the two are designed to compose. See ADR-0019 for the courtesy-notice obligations and the optional thinking-stack capability bundle.

Where Convergio sits in the engineering-fundamentals landscape: the ISE Engineering Fundamentals Playbook prescribes engineering practices in checklists; community projects like microsoft/hve-core transmit such practices to Copilot agents via prompts and skills. Convergio is the runtime enforcer of the principles ISE Engineering Fundamentals describes in checklists and hve-core transmits via Copilot prompts: gates that refuse with HTTP 409, an audit chain that proves the refusal, an OODA loop that lets agent and validator converge or escalate. See ADR-0017 for the mapping.

Why we exist: see docs/vision.md for the long-tail thesis and the urbanism frame (Convergio is an urban code, not a master plan — Le Corbusier modularity + Jane Jacobs emergence). See ROADMAP.md for the four waves that materialise it.

Notices and credits

Convergio is a personal open-source project. It is not a Microsoft product, not affiliated with Microsoft, and not endorsed by Microsoft. References to the ISE Engineering Fundamentals Playbook (CC BY 4.0) and to microsoft/hve-core (MIT) are use of those projects under their public licences and reflect the author's reading of public documentation, not any internal position of any organisation. References to garrytan/gstack (MIT) are likewise public-licence use, with a courtesy-notice obligation documented in ADR-0019.

License

GNU Affero General Public License v3.0 or later (AGPL-3.0-or-later), OSI-approved copyleft with network-use clause. See LICENSE for the full text and NOTICE for attribution.

Contributions are accepted under the project CLA — see CONTRIBUTING-CLA.md. The relicensing rationale is in docs/adr/0074-relicense-agplv3.md. The prior Convergio Community License v1.3 governs releases up to and including v0.x snapshots taken before 2026-05-27; AGPL-3.0-or-later applies to all subsequent commits.