Project overview and demo

🏛️ 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.

By the numbers

56	jurisdictions covered — all 50 states + Federal + DC + 4 territories
14,474	distinct federal (Congress) bills, and counting
< 1 min	to clone every dataset
$0	cost to tag bills — models run locally on free CI

Table of Contents

• Example Projects
• Quick Start
• Legislation Data Catalogs
  • Data Structure
  • Read it from an AI assistant (no install)
• Contribute

Example Projects

Point govbot at a topic and it publishes a live feed for it. Two running today:

• Transportation Legislation Bluesky bot — transportation bills across all jurisdictions, posted as they move.
• Data Center & AI Legislation Bluesky bot — tracks AI and data-center bills nationwide.

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:

1. Asks what data sources you want (all 56 jurisdictions or specific ones)
2. Guides you through creating tags for topics you care about
3. 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:

1. Clones/updates legislation repositories
2. Tags bills based on your tag definitions
3. 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

🏛️ Govbot Legislation Data Catalogs

Formatted legislation data for all 56 jurisdictions is available at github.com/govbot-data.

• All 50 US states
• Federal (USA)
• DC, Puerto Rico, Guam, US Virgin Islands, Northern Mariana Islands

Data Structure

Each jurisdiction has its own repo. The root of that repo IS the dataset — no wrapper folders:

{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)
    ├── sessions.json                  # Session id -> name/dates
    ├── bill_session_mapping.json      # Bill-to-session mappings
    ├── latest_timestamp_seen.txt      # Incremental-processing cursor
    └── errors/                        # Text-extraction failures, missing-session bills, orphan tracking

Federal and state jurisdictions share one path pattern (state:usa for federal), so downstream tooling doesn't need special-casing.

See actions/format/docs/DATA_STRUCTURES.md for the full schema reference (bill metadata, logs, events, error tracking).

Read it from an AI assistant (no install)

You don't need the CLI to explore the catalogs. Two files let any AI assistant (Claude, ChatGPT, etc.) read the data directly from GitHub — great from a phone:

• llms.txt — a plain-language guide an AI reads first: the filing rule that turns a jurisdiction + bill number into a fetchable URL, the bill fields, discovery recipes, and guardrails (cite official sources, read the timeline, don't invent bills).
• catalog.json — a machine-readable directory of every jurisdiction data repo plus the bill path pattern.

Try it: paste this into Claude or ChatGPT on your phone —

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 lookup-by-reading path is best for specific questions ("what is IL SB0813", "what did this sponsor introduce"). For big cross-state number-crunching, use the CLI + DuckDB above.

Contribute

Folder Structure

This repo is a monorepo, with actions being self contained. actions as a name is because it's what Github expects.

Requirements For Each Action

• Be a runnable as basic scripts in python, bash, rust, or typescript which can run as shell scripts with args.
• Have an action.yml file to run as a runner, most likely in GitHub Actions.
• Have a schemas folder that uses JSON schema to define types.
  • This allow other actions to import your schema for validation.
• Have __snapshots__ that contain real file/folder outputs. This serves two purposes: (1) they show expected results and (2) they can be directly used as inputs for downstream snapshot tests.
  • Each action manages its own snapshot rendering through a render_snapshots.sh script.
  • Validation occurs via .github/validate-snapshots.yml for each specific module.