Civic Accord · documentation

How It Works

Everything about how Civic Accord works, in plain language: what it does, where its information comes from, how votes are counted, what AI does and doesn't do, and how it's kept secure. If something here is unclear or wrong, please tell us.

An early example. Civic Accord uses sample votes today. This page describes both what works now and what still has to be built before real use. Each section says which is which.

What it is

Civic Accord is a free, nonpartisan tool for a two-way relationship between residents and their governments. It shows what your governments have open for public input. It lets verified voters talk an issue through, finds where people with different views agree, shows what each choice would cost, and sends the result to the office that represents them. The office is asked to answer in public.

It works for any U.S. address and every level of government: federal, state, county, city or town, and school district. It is advisory. It doesn't replace voting or elections, and it doesn't make laws.

Proposals come only from voters (planned). Once real deliberations run, a proposed bill or policy will go to an office only as the result of verified voters in that place talking it through together. Civic Accord itself never takes a side on any bill. When you use it to write to an official about a bill, the view is yours.

One exception, said openly. Civic Accord does ask for one thing: that offices offer residents a public, checkable way to work with them, like this tool or any tool meeting the same standards. The sample "Ask your representatives" page and the sample national deliberation are about that. Until a neutral host runs Civic Accord and its lawyers review it, the Ask page isn't linked from the menus. Because Civic Accord benefits if offices say yes, this is a conflict of interest, and we say so here. The sample's result is an office policy, a practice an office can adopt on its own, not a bill.

The six steps

  1. Learn. Everyone reads the same short facts. Every fact links to its source.
  2. Weigh in. Verified voters agree, disagree, or pass on short statements, and can add their own. There's no reply button, so no one can pile on. Votes count only after you press Submit, and you get a receipt (sample, in this example).
  3. Common ground. The tool shows what people with different views agree on, and where they split.
  4. Weigh costs. Each option shows its total cost, its cost per resident, and how the estimate was made. You can turn options on and off and see the total change.
  5. Draft. A starting bill is drafted from the common ground. In this example, simple code assembles it; in the live version, AI would help write it. Ideas that divide people are flagged, not hidden.
  6. Hand off. The package goes to the office. You can follow what happens next on a public timeline.

Who can take part

Verified voters only. Only registered voters can vote or add statements in a deliberation, so every voice is a real, verified voter. Anyone can read everything, see what's open for public input, comment through official channels, and write to their representatives.

Two checks. First, that an active voter record exists for you in the district. Second, that you're really that voter: a code is mailed to the home address on your voter record (not one you type), or staff at a library or election office compare your ID with the record. An instant yes-or-no check by your state election office, and state digital IDs where law allows, are planned. Each state's rules on voter records decide what may be used. In this example, no real check happens.

Planned: faster ways to prove you're you. A mailed code takes a week or more. Beside it and the in-person check, the plan is to offer faster options, in this order of preference: a state digital ID (a mobile driver's license or state ID app) that can confirm your name and address without showing anything else; a commercial identity service, such as ID.me, only if the host approves it after review, and only as a choice beside the free options, never the only way; and Login.gov, which federal law limits to government agencies, so it can be used only through a state election office that adopts it for its own voter check. In every case the identity service tells Civic Accord only that the name and address matched. The match to an active voter record is still done by the host or the election office, your identity stays separate from your votes, and no address is stored. Votes made before a check is finished are labeled pending and counted only once it succeeds.

North Dakota has no voter registration, so there's no voter record to check there. The check would follow North Dakota's own rules for proving who can vote; that is still to be worked out in the state's legal review.

Only your own governments. You can respond only where you're a voter: federal items from anywhere, your state's items only if you're a voter in that state, and local items only in your own county, city, town, or township. You can still read everything from everywhere.

Today, this uses the state or address you chose on the home page or My representatives, which stays on your device. A state alone is enough to respond to that state's bills; an address adds your local governments. Nothing checks it yet. Planned: once real voter checks exist, it will use your checked districts.

Not a voter yet? Civic Accord Learn is a separate space for young people and anyone who can't vote. It uses real issues and points to real actions anyone can take. You can tap the topics you care about or search, using the same open word lists as Issues, and your picks stay on your device. Nothing there is counted in deliberations.

Your privacy

How votes are counted

In the live version, votes go into a public record that can be added to but never quietly changed. Simple code that anyone can read does the counting, so anyone can download the record and recount it.

Two questions are still open for the independent security review before launch:

The plan is to use established, open methods rather than inventing new ones: sealing and receipt codes like Microsoft's ElectionGuard (its code is open for anyone to read), plus a separate, checkable shuffle.

Each voter record can be claimed by only one verified person. Before a package goes to an office, voter status is checked again against the current list.

Protecting your voter record (planned). In about half the states, anyone can get a copy of the voter list, and others limit it to campaigns, parties, or officials (each state's rules). People also move. So the mailed code is protected in several ways:

Today: the example uses sample votes, and receipts are generated on your device to show how they would work.

How common ground is found

Participants are sorted into groups by how similarly they vote. The live version will use the open method from Pol.is, which Taiwan's vTaiwan process uses. In the example, the groups come with the sample data. Each statement is then labeled with these exact rules:

LabelRule
Common groundAt least 70% of every group with at least 10 votes agrees.
Divides groupsAt least 70% of one group agrees, and under 50% of another does.
Still formingAnything else, or fewer than two groups with at least 10 votes each on that statement.

A group only counts toward a label once at least 10 of its members have voted on that statement. That way, a few people can't speak for a whole group. A "pass" counts as not agreeing.

Guarding against small, organized groups. Common ground means agreement among the people who took part, not the whole district. So:

Citizen panels. A randomly chosen panel, balanced to match the district by age and area, votes too. Its result is shown beside the open results, using these rules: the panel agrees at 70% or more, is divided at 40 to 69%, and disagrees under 40%. When the panel and the open group differ, the tool says so. A table shows who took part compared with the district.

Rules for statements, and who reviews deliberations

These rules are planned for the live version. They're about behavior, never about which side someone is on. Any view on the issue is welcome, including strong criticism of officials or of Civic Accord. When in doubt, a statement stays up. The final wording will be checked in the host's legal review, so it follows free-speech law.

What a statement can't include. A moderator holds back a statement that:

How moderation works.

Who reviews a deliberation before it opens. Anyone can set one up with the builder, so each one is checked first:

Today: the sample shows new statements right away, on your device only. None of this review exists yet. It needs a host.

How costs are shown

Every option shows how much, times the cost of each unit, equals the total. For example: 12 inspectors × $85,000 = $1.02 million a year. It also shows the cost per resident, using the official population figure. Every estimate says how it was made and links to its source. Yearly and one-time costs are kept separate. Fees and fines that could pay for it are subtracted only when there's a reliable estimate. Anything that can't be estimated is shown as "not yet estimated," never guessed.

What AI does and doesn't do

AI mayAI never
Draft a starting bill from the common groundCounts votes, or touches the vote record
Help organize and summarizeChecks voter status
Help write issue packs, which a person then reviewsWrites or frames the items on Issues, which come straight from official sources
Write a plain-language version of an item, on request (below)Changes the parts you weigh in on, or anything sent to an office; those come only from the official text
Point out possible repeats or rule problems to a human moderatorRemoves, edits, or approves a statement
Decides anything. People decide, and the office decides whether to act.

Every AI summary links to the votes behind it, so you don't have to take it on trust.

The plain-language version (works now, opt-in)

Official summaries are hard to read. On any issue page you can open Read a plain-language version. The first time anyone asks for it, an AI program writes one from the official text on that page, at most about 110 words, and it's saved, so everyone sees the same version; if the official text changes, a new one is written. The box is closed until you open it, and a setting on your device can open it automatically. It is an aid for reading, not the item: it can be wrong or leave things out, so each one says which program wrote it and when, links to the official text it came from, and asks whether it was accurate (your answer stays on your device for now). What you weigh in on, and anything sent to an office, comes only from the official text. The exact instructions given to the AI are public: say only what the text says, take no side, name no party, and say so if the text is unclear. New versions are capped per day to keep costs steady; saved ones always show. This was a change to the trust rules, decided by the convener on October 21, 2026 and recorded in the decision log.

The office, not the person

The conversation is with an office (a seat), not an individual politician. In the live version, responses will be signed by the office and give the role of the person who approved them (for example, chief of staff), not their name. When someone new is elected, every open package, request, and past response passes to them. Offices answer publicly with a reason. They can ask for changes, which residents then weigh in on, and they report each step: introduced, heard, voted. Offices can also ask their district to deliberate, through a neutral host. There's no party branding, no campaign use, and no ratings of officials.

How an office proves it's really the office (planned). A fake reply from an office would do real harm, so posting for an office is locked down:

Issues: where items come from

Issues (once called Open Now) lists what your governments have open for public input. It comes straight from these sources, with no AI involved, and refreshes every few hours:

WhatSource
Proposed federal rules open for public commentFederal Register
Recently active bills in CongressCongress.gov. The 100 most recently updated bills. Bills that became law, were vetoed, or failed are left out, and so are resolutions that have been fully agreed to.
Bills still moving in your state legislatureOpen States. Shown only while the legislature is in session. Lists are downloaded on a schedule (about every 3 hours while a legislature is in session, about once a day otherwise) and saved, and every download shares one daily limit so Civic Accord stays within Open States' free use. Each list holds up to the 60 most recently active bills, or fewer (as few as 20) when many legislatures are in session at once; the page says how many there are in all. A saved list more than 36 hours old isn't shown, because bills on it may have been signed or vetoed since. Bills that were signed, vetoed, failed, or withdrawn are left out. A bill isn't left out just because an amendment or motion on it failed.
Local council meetings in the next 30 daysEach government's own public agenda system (Legistar, Granicus agenda feeds, or a CivicPlus Agenda Center). Connected so far, as pilots: the Maui County Council (Hawaiʻi) and the Oakland City Council (California), including their committees and other public meetings. They were picked because their agenda systems offer public data with no key needed, and to test one county and one city. Most governments using the same agenda system can be added with one entry in the open registry (how to connect your government). Each list is downloaded on a schedule (about every 3 hours) and saved, so adding more governments never slows a visit; a list more than a day and a half old isn't shown. Shown when you pick that government's state.
Other city, county, and school board agendasComing as more governments are added

Each source shows when its list was fetched, and says so if a refresh just failed and an older list is being shown. Deadlines are checked against today's date every time the list is drawn, so an item never shows as open after its deadline, even from a saved copy. Official deadlines usually give only a date, so on the last day an item says "Closes today" and points to the notice for the exact time. Dates follow your device's time zone; federal comment deadlines are usually the end of the day Eastern time, so check the notice if you're farther west.

Each item links to the official text and the government's own comment channel. Some proposed rules have no online comment form. For those, the button says "How to comment (in the notice)" and opens the notice, which explains how to comment, often by email or mail.

Finding what you care about

There can be hundreds of items open at once. On your first visit, Issues asks you to pick up to five topics, like housing, schools, or farms and food. Then it shows what's open on those topics, with the soonest deadlines at the top, ten at a time. Meetings of your own county, city, or town are always included, since meeting titles rarely name a topic. Once you've chosen your state, federal items whose official title names one other state (an air plan for North Carolina, say) come after your own state's items and nationwide rules, and are labeled with that state; nothing is hidden. This reads only the title, with a plain list of state names, not AI. You can switch topics, see everything, or search everything at any time. When an agency posts many near-identical rules at once (for example, dozens of aircraft safety notices), they're folded into one line you can open.

Your next step on each item

Every item shows a short path: read it, say where you stand, speak up, and go further. The next step is always clearly marked. "Read what it says" opens the item's own page, built from the official summary, with the full official text one link away. For a proposed rule, speaking up means the official comment to the agency, because the agency must consider the official comments. For a bill, it means writing to the people who represent you. Going further means talking it through: weighing in on each part, copied word for word from the official summary (how that works). Today your votes there are practice, kept on your device. You can also build your own deliberation, which neighbors can join once a host reviews and opens it. The last step, having verified voters' views counted in a public record, is planned and marked that way. A step is marked done only when you say so, for example "Yes, I sent it," which also offers to keep a record of what you sent (how records work). Your steps are kept only on your device, as a reminder for you. They aren't counted or sent anywhere.

Items are sorted into topics by a published list of words, not by AI. For example, an item that mentions "tenant" or "landlord" goes under Housing. The title and the office are checked first. The longer summary is checked only if those match nothing. Each item shows which word put it there, so you can see why it's showing. Anyone can read the word lists (lib/topics.js) and suggest a fix. A word list can miss things or file something in the wrong place, so "Everything" and search always show every item. Your topic picks stay on your device and are never sent anywhere.

Weigh in on any bill or proposed rule, part by part

Every item listed on Issues has its own page where you can weigh in on it: bills in Congress, bills in your state legislature during its session, proposed federal rules, and connected local council meetings. For a local meeting, the parts are the agenda items with legislation attached, by their official titles. These pages are built automatically, only from official material, so no one has to write them and nothing is reworded:

When the official text changes. Each practice vote is saved with the exact words it was cast on. If a summary is updated, your votes on unchanged parts stay, and votes on parts that changed or were removed are never moved onto the new text. The page tells you what changed so you can vote again.

A part can mix several things. Official summaries sometimes describe a change, the reason for it, and how things work today in one paragraph. If a part mixes things you'd answer differently, choose Pass and add your own statement. Answers on a mixed part aren't a precise view of each piece.

Today: these pages and their official content are live. Your votes and statements are practice: they stay on your device and aren't counted. Counting starts once real voter checks exist and a host runs it.

Issue pages, Following, and your own records

Each item on Issues has one permanent issue page. At the top it says what the item is, who can act on it, where it stands in the official record, and the most useful thing you can do next. Every part of the page is labeled Live, Practice, Sample, or Planned.

Today: issue pages, official developments, Following, and your own records are live. A sample issue page, with a fictional office and invented numbers, shows counted results, delivery, and an office's response, all marked Sample.

Contacting your representatives

On any item, you can choose Support, Oppose, or Unsure, add your own words, and Civic Accord writes a short message to the right offices. State legislators' published emails come from Open States. Email opens in your own email app. Members of Congress don't publish email addresses, so one button copies the message as it opens their official contact form, and you paste it there. Your name and town are remembered on your device as you type them, so later messages show "Signed as" with a Change link. For proposed rules, the official comment to the agency is what counts, so that comes first. The sample "Ask your representatives" page asks offices to adopt a tool like this one; it asks for your name each time and uses a separate copy button.

About the "Ask" page. It asks each office to change how it hears from residents. It doesn't ask anyone to support a particular bill or spending, and it says so in the message. It asks you to add a sentence in your own words, because offices often give more weight to messages in a person's own words, and the message says it started from a suggestion on Civic Accord. Until a host runs Civic Accord, this page is a sample that isn't being promoted. Before a host promotes it widely, the host's lawyers will check it against the rules for nonprofits, which limit how much they may try to influence legislation.

Today: reactions stay on your device. In the live version, verified voters' reactions would be counted in the public record.

Finding your governments (My representatives)

The My representatives page asks for your address only after explaining why. Your browser sends it straight to the U.S. Census Bureau; it never reaches Civic Accord. Only your districts and the names of your governments are kept, in your browser, so you don't have to enter the address again and Issues knows which items are yours. It lists members of Congress and your state legislators with the contact details they publish, and says clearly where local officeholders aren't covered yet. Opened from an issue page, it offers a link back to that issue.

In 2025 Google shut down a free service that many apps used to find elected officials. Civic Accord's open replacement works like this:

  1. The U.S. Census Bureau's free address lookup turns your address into districts: congressional, state house and senate, county, city or town, and school district.
  2. An open registry describes each office: its branch, how it's chosen, and whether it can receive proposals. It covers all 50 states and D.C., including special cases like Nebraska's one-chamber legislature, D.C. and territories, independent cities, and states without county governments.
  3. Towns and townships are shown when the Census Bureau lists them as working governments. That includes New England towns, New Jersey and Pennsylvania townships, and places where an address is inside both a town or township and a village or city, as in New York, Michigan, and Ohio. Both are shown then, since each has its own elected officials. What each one handles depends on state law. Where a town only repeats a city or borough, it's shown once.
  4. Names of members of Congress come from the public-domain congress-legislators data. State legislators come from Open States. Party is never shown.

Special districts (water, fire, transit) aren't in the Census data yet. Local hosts can add them.

What's covered today

GovernmentDistricts foundOfficeholder namesHow to contactOpen items
U.S. CongressYesYesOfficial contact form and phoneBills and proposed federal rules
State legislatureYesYes, on My representatives, issue pages, and the Ask pageEmail where published, or official pageBills during the session
Other statewide offices (governor and others)YesNot yetNot yetNo
CountyYesNot yetNot yetMaui County Council meetings only
City, town, or townshipYesNot yetNot yetOakland City Council meetings only
School districtYesNot yetNot yetNo
Special districtsNot yetNot yetNot yetNo

No office has joined Civic Accord yet. Labels like "Could receive proposals" describe what kind of office it is, not a commitment from that office.

Rules come from law

Every rule the tool applies comes from that government's own law or chamber rules, with the source shown. Examples are the limits on official mass communications before elections, and what voter-list information may be used. Where no law applies, the tool adds no rule of its own. Rules not yet confirmed are labeled. Legal review happens in two layers: law that's the same everywhere is reviewed once by the host's lawyer, and each state's rules are reviewed by local experts, such as a law school clinic, before launch and each election cycle.

Security

No single test proves a system secure. Civic Accord is checked in layers, and the most important is a design where the public can check results even if part of the system is attacked.

Today: the site sends strict security headers, and its pages run only their own script files, never code mixed into the page. The Census Bureau's address lookup runs in a separate, sealed-off frame that can't reach the rest of the site, your saved settings, or anything you type elsewhere. Five data functions run on the server. Four answer visitors and only read public data. The fifth runs on a schedule, only the hosting service's scheduler can start it, and it saves public state bill lists, shared call counts, and nothing personal to a private store. Their keys are stored as secrets. No real votes or identities are collected.

Using it as an app

First visit. The first time a browser opens Civic Accord, the home page shows a short welcome card (three things to know) and the first issue page shows a full note on where its information comes from. After that, the card stays hidden and the note shrinks to a line. See the welcome card again. "Forget me on this device" also brings it back.

Civic Accord can be added to a phone's home screen and opens full screen, like an app. It's the same website, so it's always current, and there's no app store in between. Pages you've opened work without a signal. Live information, like Issues and the lookup, always comes fresh from its source and is never shown from an old saved copy. App-store versions may come later, once there's a host to own those accounts.

Every page has the same four main places: Home, Issues, My representatives, and Following. On a phone they sit in a menu at the bottom of the screen. How it works and Learn are at the top of each page and in its footer.

What's real today

Works nowStill to be built before real use
Address lookup for every U.S. government, with names and contact details for members of Congress and state legislators
Issue pages, Following, and your own records of what you sent (kept in your browser)
Issues with live federal rules and bills in Congress and state legislatures
Emailing or contacting your representatives
The six steps, with sample votes
The office inbox, with sample responses
Building a deliberation (saved in your browser; opening one needs a host and review)
The real vote record and receipts
Mailed voter-check codes and library checks
Official voter-status matching
Public counts of reactions
Named stewards and a second account administrator (the charter is published; stewards aren't named yet)
A neutral host, legal review in each state, and independent security audits

Who runs it

Civic Accord was started by a resident acting as a convener, not an owner. The goal is for a neutral university or nonpartisan nonprofit to host and run it, with the convener in an advisory role. Before real use, each deliberation pack will be checked by two reviewers, published, and open to public objection for 7 days before it opens (how reviews work). Every change to the code and data is already kept in the public history.

The charter. A short public charter says who holds the keys and what can't change without a process (read it). Today the convener holds the domain and accounts in trust. Planned: three to five stewards from different organizations, and any change to the accounts, the core design, or the host needs two of them to agree. When a host takes over, everything transfers to it at no cost. There is no company, membership, token, or treasury behind the project, and nothing is for sale.

The decision log. Every governance decision is written down with its date, reason, and who agreed, and entries are never removed (read the log).

Conflicts of interest. Anyone deciding something for the project discloses any stake and steps aside from that decision. The convener has disclosed stakes in short-term rentals and farming and takes no part in reviewing packs on housing or agriculture.

Open code and data

Anyone can read, use, and change the code. If someone runs a changed copy as a public website, the license requires them to share their changed code too, so anyone can check what it does (GNU AGPL 3.0). Anyone can reuse the registry and pack data if they credit Civic Accord (CC BY 4.0). The licenses don't cover the name: a copy shouldn't present itself as the official Civic Accord. The official site is civicaccord.org.