About Govbot

Govbot is an open-source project of Chi Hack Night that turns every U.S. legislature's activity into open data anyone can clone, query and build on. Know Your Ballot ↗ is a free, nonpartisan voter guide built on Govbot.

Every U.S. legislature, as data you can clone. govbot is a terminal-native toolkit that turns government updates into git repositories you can analyze, query, and build on — no scraper to maintain, no data platform to pay for.

📥 Clone the legislation of 56 jurisdictions in under a minute — every dataset is just a git repo.
🔒 Tag and summarize bills with private, local models — optimized to run for free on GitHub Actions. No API keys, no per-token bill.
🔎 Analyze it your way — stream it as JSON Lines through Unix pipes, or load it into DuckDB for SQL across every state at once.

▶ Project overview and demo (video)

By the numbers


56	jurisdictions covered — all 50 states + Federal + DC + 4 territories
19,186	distinct federal bills in the 119th Congress (as of Sept 30, 2026), and counting
< 1 min	to clone every dataset
$0	cost to tag bills — models run locally on free CI

What you can do with it

The dataset covers 56 jurisdictions — all 50 states, the U.S. House & Senate (Federal), DC, and the territories of Puerto Rico, Guam, the U.S. Virgin Islands, and the Northern Mariana Islands — as .json files, one git repo per jurisdiction.

The scrapers update regularly, appending new logs. New bills are tagged and scored on-device by a private sentence-transformer model (ONNX) with a keyword fallback — small enough to run for free on GitHub Actions, so no bill text leaves your pipeline and there's no per-token cost.

Projects built on it:

Legislation dashboard — every jurisdiction's bills by place, topic, sponsor and status.
Hearings & public comment — upcoming hearings and how to weigh in.
Illinois elections — every race and candidate on your ballot.
Transportation Legislation Bluesky bot — transportation bills across all jurisdictions, posted as they move.
Data Center & AI Legislation Bluesky bot — AI and data-center bills nationwide.

Why govbot?

Why don't we pay attention to our representatives between elections?

Legislative data is hard to parse, track, and organize. Activists, concerned citizens, and the curious may not have the time, resources, or expertise to build out duplicative tech stacks. Existing solutions depend on the organizations and companies willing to keep running them — Google's Civic Information API representatives lookup, for example, was shut down in 2025. What would a decentralized, open-source legislative data solution look like?

The Govbot team's goal is to bridge this gap — building the framework for federated, open-source, non-profit legislative data. Built as a Chi Hack Night Breakout Group, the project includes an open-source, simplified, and expanded version of Open States' data on state and federal legislation, plus the example applications above.

Quick start

1. Install

sh -c "$(curl -fsSL https://raw.githubusercontent.com/chihacknight/govbot/main/actions/govbot/scripts/install-nightly.sh)"

2. Set up your project

govbot

Running govbot with no config file launches an interactive setup wizard that:

Asks what data sources you want (all 56 jurisdictions or specific ones)
Guides you through creating tags for topics you care about
Creates govbot.yml, .gitignore, and a GitHub Actions workflow

3. Run the pipeline

govbot

With a govbot.yml in your directory, running govbot executes the full pipeline:

Clones/updates legislation repositories
Tags bills based on your tag definitions
Generates RSS feeds in the docs/ directory

Other commands

govbot clone all           # download all state legislation datasets
govbot clone il ca ny      # download specific states
govbot logs                # stream legislative activity as JSON Lines
govbot logs | govbot tag   # process and tag data
govbot build               # generate RSS feeds
govbot load                # load bill metadata into DuckDB
govbot delete all          # remove all downloaded data
govbot update              # update govbot to latest version
govbot --help              # see all commands and options

Querying with SQL (DuckDB)

govbot load reads every cloned metadata.json into a DuckDB database (default ./govbot_data/govbot.duckdb — data lives under ./govbot_data/ in the folder you run govbot from, or $GOVBOT_DIR). The DuckDB CLI must be installed. See DUCKDB.md for the schema and example queries.

govbot load                                  # load all data into the default database
govbot load --database my-bills.duckdb       # or choose a database file
govbot load --memory-limit 32GB --threads 8  # for large datasets
duckdb --ui govbot_data/govbot.duckdb        # open it in DuckDB's browser UI

Or query the JSON directly:

INSTALL json;
LOAD json;

SELECT *
FROM read_json_auto('govbot_data/repos/**/bills/*/metadata.json')
LIMIT 10;

The data catalogs

Formatted legislation data for all 56 jurisdictions lives at github.com/govbot-data — one repo per jurisdiction (govbot-data/{code}-legislation). The root of each repo is the dataset:

{state}-legislation/
├── country:us/
│   └── state:{code}/                  # state:usa (federal), state:il, state:tx, etc.
│       └── sessions/{session_id}/
│           ├── bills/{bill_id}/
│           │   ├── metadata.json      # Bill metadata + _processing timestamps
│           │   ├── logs/              # Action/vote-event logs
│           │   └── files/             # Bill text: original .pdf/.xml/.html + *_extracted.txt
│           └── events/                # Committee hearings, etc.
└── .windycivi/                        # Pipeline metadata (committed & reused)

Federal and state jurisdictions share one path pattern (state:usa for federal). See DATA_STRUCTURES.md for the full schema reference.

Read it from an AI assistant (no install)

Two files let any AI assistant (Claude, ChatGPT, etc.) read the data straight from GitHub — great from a phone:

llms.txt — a plain-language guide the AI reads first (also on GitHub).
catalog.json — a machine-readable directory of every jurisdiction repo plus the bill path pattern.

Try it: paste this into Claude or ChatGPT —

Read this guide, then follow it to answer my question: https://raw.githubusercontent.com/chihacknight/govbot/main/llms.txt

Question: What's the status of Wyoming HB0001 in the 2025 session, who sponsored it, and what's the official source link?

This works best for specific questions. For big cross-state number-crunching, use the CLI + DuckDB above.

Contribute

The repo is a monorepo; everything under actions/ is a self-contained module that runs as a plain script and as a GitHub Action. Each action:

Runs as a basic script (Python, Bash, Rust or TypeScript) with args.
Has an action.yml.
Defines its types with JSON Schema (in schemas/), so other actions can validate against them.
Keeps real outputs in __snapshots__/ as its tests (rendered by its render_snapshots.sh, validated in CI).

The govbot CLI

Contributors need Rust & Cargo and the just task runner (cargo install just). Then, in actions/govbot:

just setup — install the toolchain and dependencies
just govbot ... — run the CLI in dev mode
just test — run all tests
just review — review snapshot test changes
just mocks [LOCALES...] — update mock data for testing

Advanced

Point govbot at your own data repos:

GOVBOT_REPO_URL_TEMPLATE="https://gitsite.com/org/{locale}.git" govbot ...

Project history

Govbot began in 2022 with a simple goal: a place for simplified, summarized updates on legislative action that you could follow or filter by topic.

2022 — Socratic Center: find who represents you. The project then joined Chi Hack Night as a breakout group.
2023 — Civi Social: Chicago residents talk directly with their elected officials.
2024 — Windy Civi: the app and website, launched in beta — local, state and federal bills with AI summaries and topics.
2025 — Decentralize: building it showed the limits of a centrally managed platform. The vision pivoted to an open, decentralized dataset anyone can run — plus sample applications so government accountability is accessible to all.
2026 — today: 56 open datasets and the civic tools built on them.

FAQs

Can I see the code?

Yes. The toolkit, the pipelines and this site are at chihacknight/govbot. The data lives in one repo per jurisdiction at govbot-data.

How is the data structured?

Each bill is a folder with its metadata, action logs and bill text — see The data catalogs above and DATA_STRUCTURES.md.

How do I get the data?

No coding: open Explore Legislation → Download the data for every bill as a spreadsheet (CSV, opens in Excel or Google Sheets), one state at a time or all at once — or download exactly the bills you've searched for from a state's bills list. The same panel links the JSON files (dashboard/data.json, dashboard/bills/<code>.json) and a manifest.json for scripts. This data is licensed CC BY 4.0 — please credit "Govbot (Chi Hack Night)".

Full records: run govbot clone il (or govbot clone all), or browse and git clone any repo at govbot-data.

To add a new jurisdiction, each one is scraped by a GitHub Actions template explained in the caller-repo README template; to run many pipelines, see the pipeline manager.

How can I stay updated, or get in touch?

Join our channel on the Chi Hack Night Slack, follow along at Chi Hack Night and on GitHub, or follow us on Bluesky, X and Instagram.