Mission

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 may be limited by the willingness of organizations and companies to continue to run and host them - such as in the case of Google’s Civic Information API, which was shut down earlier this year. 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 the building and use of 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 OpenStates’ data on state and federal legislation, as well as example applications.

What We Offer

The main Govbot dataset currently includes legislative updates from bills in the U.S. House & Senate, all 50 states, territories like Guam, and the city of Chicago, as .json files organized using the Project Open Data catalog format. The Govbot scrapers update regularly, appending new logs, and then running them through Claude to provide topic-based tagging and summaries. This data can then be analyzed using SQL, via an interface built with DuckDB, or plugged into applications like our example website, WindyCivi, and a test BlueSky bot built in collaboration with U.S. Representative Hoan Huynh. (https://bsky.app/profile/test-hoan-huynh.bsky.social).

How Do I Use It?

1. Install

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

2. Run govbot

govbot

That’s it. If no govbot.yml exists, an interactive wizard walks you through setup:

Sources - Choose all 47 states or pick specific ones
Tags - Start with an example tag, or get an AI prompt you can copy-paste to create your own
Publishing - RSS feeds configured automatically

The wizard creates govbot.yml, .gitignore, and a GitHub Actions workflow.

3. Run the pipeline

Once set up, running govbot again 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 database
govbot delete all          # remove all downloaded data
govbot update              # update govbot to latest version
govbot --help              # see all commands and options

Dataset Key:

🆕: the locale’s data received updates since your last cloning
✅: the data you’ve cloned is up-to-date with the most current version
🔄: the data is currently being updated
❌: the data is not currently accessible

Querying in SQL using DuckDB

You can query the data using SQL, via DuckDB, which creates a simiulated database from the .json log files. See DUCKDB.md for more details.

Running Queries in the Command Line

-- Load JSON extension
INSTALL json;
LOAD json;

-- Query all bill metadata
SELECT * 
FROM read_json_auto('~/.govbot/repos/**/bills/*/metadata.json')
LIMIT 10;

Additional Commands, and Querying via the Web UI

Additional examples of commands, and setup for the web UI, can be found below:

# Load all data into a database (default: govbot.duckdb)
govbot load

# Or specify a custom database file
govbot load --database my-bills.duckdb

# With memory limit and thread settings
govbot load --memory-limit 32GB --threads 8

# Open in DuckDB UI (opens in your browser)
duckdb --ui govbot.duckdb

Helper Scripts

# Run example queries
./duckdb-query.sh examples/duckdb-example.sql

Contributing & Testing

Prerequisites

Folks looking to contirbute should have knowledge of Rust: just. just setup to start, and then just govbot ... to develop the cli.

The following should also be installed:

Rust & Cargo: Install the Rust Toolchain
Just: Install the task runner: cargo install just

Development Workflow

Use just govbot ... as your cli “dev” environment.

Other Useful Commands

just - See all available tasks
just test - Run all tests
just review - Review snapshot test changes
just mocks [LOCALES...] - Update mock data for testing

We build snapshots off examples. Add examples to make a test.

Advanced

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

Project History

The Govbot project began in 2022, with a vision to create a destination for simplified, summarized updates on legislative action, with the ability to follow or filter for certain legislative topics. The result was the initial Windy Civi app, and website, launched in beta in 2024.

While building the solution, the team began to consider the limitations of a centrally-managed data source and platform, versus one that could be decentralized, that was open-source, and that allowed for exploration and use of the data in ways beyond initial designs.

Our vision now has pivoted to building that data set, as well as building sample applications and solutions to ensure that government accountability can be accessible to all.

govbot