Skip to content

CivicOS

AI-enabled infrastructure for local self-organization and governance.

CivicOS indexes public civic data — meetings, agendas, decisions, budgets, legislation, community issues — and makes it searchable, understandable, and actionable through a browser extension, MCP server, and REST API.

Pilot city: San Rafael, CA

How It Works

A resident installs the browser extension. It shows them what's happening in their city: upcoming meetings, recent decisions, budget breakdowns, community issues on a map, and relevant state/federal legislation. They can express a stance on agenda items (support, oppose, watching), draft public comments with AI assistance, and track how officials vote.

Identity is local-first, built on Nostr (secp256k1 Schnorr signatures). Private keys never leave the device.

Surfaces

Surface What it does Who it's for
Browser extension Primary UI — civic dashboard, voice, identity Residents
MCP server Civic data tools for AI assistants (v2 query interface) Claude, ChatGPT users
REST API Programmatic access to civic data Developers

Architecture

Browser Extension (Svelte 5)
    ├── civicos-components (Svelte UI)
    └── civicos-client (TypeScript)
              |
    ┌─────────┼─────────┐
    v         v         v
REST API  MCP Server  Relay API
(FastAPI) (JSON-RPC)  (FastAPI)
    |         |         |
    v         v         v
    CivicOS (core)   civicos-relay
    (Python query)   (coordination)
         |                |
         v                v
    PostgreSQL        Relay DB
    + pgvector        (Supabase)
    (Supabase)
         ^
         |
    civicos-extraction
    (platform parsers)

Federation

Operators can independently run an MCP server (read-only civic data), a relay (bidirectional coordination), or both. Multiple operators per jurisdiction peer via the relay protocol and are discoverable through a central registry.

       Operator A (Government)       Operator B (Civic Org)
    ┌──────────┬──────────┐     ┌──────────┬──────────┐
    │MCP Server│  Relay   │◄───►│  Relay   │MCP Server│
    │(civic    │(voices,  │peer │(community│(mirrors  │
    │ data)    │ actions) │sync │ voices)  │ data)    │
    └──────────┴──────────┘     └──────────┴──────────┘

Packages:

Package Purpose
civicos Core data access — storage backends, vector search, jurisdiction config
civicos-services REST API server — v2 query interface (5 verbs), legacy endpoints
civicos-relay Coordination — voice casting, subscriptions, relay sync
civicos-signer Portable attestation signing — lets organizations hold their own issuer keys
civicos-extraction Platform parsers — Legistar, CivicClerk, ProudCity, Granicus, SeeClickFix, LegiScan, and more
civicos-client TypeScript client — API wrapper, identity, AI provider management
civicos-components Svelte UI components — meetings, decisions, budgets, maps

Data (San Rafael Pilot, as of March 2026)

Corpus Records Source
Meetings ~98 ProudCity (city website)
Decisions ~44 Minutes extraction
Transcripts ~19 YouTube + AssemblyAI
Agenda packets (PDF chunks) ~5,084 City agenda PDFs
Municipal code ~16,175 Municode
Community issues ~1,730 SeeClickFix (311)
Budget items ~58 FY25-26 budget PDF
Legislation ~17,719 LegiScan (CA + federal)

All data is semantically indexed (~16,786 vector embeddings) for natural language search.

Quick Start (Developers)

# Query via v2 REST API
BASE=https://san-rafael.civicosproject.org
curl -X POST "$BASE/api/v2/civic/search" \
  -H "Content-Type: application/json" \
  -d '{"query": "housing", "corpus": ["decisions", "meetings"]}'

# Browser extension
cd apps/civicos-extension
npm install && npm run dev
# Load unpacked from dist/ in chrome://extensions (developer mode)

Sustainability

CivicOS is currently a solo after-hours project, foundation-funded. The goal is self-sustainability without VC or acquisition pressure.

Civic information access is free. Search, meetings, decisions, legislation, representation — these are public records, not products. This is non-negotiable.

Revenue comes from professional users who derive commercial value from civic data: journalists, advocacy organizations, law firms, and developers via paid API tiers. Per-city infrastructure costs ~$1,000/year, so the revenue threshold for sustainability is low.

Privacy is a billing constraint, not an afterthought. Resident AI features use a privacy-preserving architecture where the system that knows "who paid" never sees "what they asked."

For the full economic model — cost structures, revenue tiers, why previous civic tech failed, and what must never be monetized — see Module 5: Economic Model and Sustainability.