overview/politiclaw

overview · v0.0.16 · openclaw plugin

politiclaw

Holds your representatives accountable to the values you declare. Generated reference where accuracy matters. Short guides where judgment matters.

PolitiClaw is a local-first civic copilot — an OpenClaw plugin that learns the stances you care about, watches federal legislation and your reps' roll-call votes (House and Senate) for you, and flags when their actions align (or don't) with those stances. It drafts letters you send yourself; it never speaks on your behalf and never tells you how to vote. The docs split into a narrative guide you read end-to-end and a reference generated from the current implementation.

get started →browse by task browse reference

v0.0.16 · local-firstopenclaw pluginus federal · google civic ballots

01 · task

see how my reps align

The accountability spine — measure your federal delegation against the stances you declared, with cited votes and honest coverage gaps.

→

02 · start

getting started

Read the two-pass layout of the site and the shortest path from a fresh install to a real answer.

→

03 · task

track bills & votes

Use the bill search and scoring path when the main question is what changed and why it matters.

→

what is politiclaw?

PolitiClaw is a local-first civic copilot that holds your representatives accountable to the values you declare. It learns the stances you care about, watches federal legislation and federal roll-call votes (House and Senate) on your behalf, and flags when your reps' actions align — or don't — with those stances. Ballot prep, candidate finance research, and draft-only outreach all build on the same stance-driven loop. Your queries never touch a third-party political platform.

Everything structured lives in plugin-owned storage on your machine. Outbound network calls happen only when a tool needs a provider-backed answer, and the source coverage page is explicit about which providers are wired today versus not yet implemented.

honest scope

Outreach is draft-only — PolitiClaw never sends mail, posts on your behalf, or routes your message through a political platform, so accountability stays in your hands instead of a vendor's. Coverage today is federal: bills and House roll-call votes through api.congress.gov, Senate roll-call votes through voteview.com, ballots through Google Civic. State legislation and local races are not yet wired and are tracked as roadmap entries on the plugin README; the docs distinguish wired providers from optional upgrades and transport-pending adapters. For the goal-indexed scope boundaries, see current coverage.

how it works

The plugin registers three things with your OpenClaw gateway: a pool of provider adapters (api.data.gov for federal bills, House votes, and FEC finance; voteview.com for Senate votes; Google Civic for ballots; Geocodio as an optional rep-lookup upgrade), a tool bundle the agent can call (politiclaw_doctor, politiclaw_configure, politiclaw_issue_stances, politiclaw_get_my_reps, politiclaw_election_brief, …), and a set of cron templates the gateway schedules for monitoring.

providers: external network sources reached only when a tool needs a provider-backed answer (api.congress.gov, voteview.com, Google Civic, Geocodio, FEC). local storage: plugin-owned files on your machine (SQLite database for structured records; cached shapefiles for the zero-key reps-by-address path).

For the exact runtime wiring, read the architecture notes and the source coverage matrix.

what ships today

representative accountability

Per-rep and per-issue alignment scoring against your declared stances, driven by deterministic matching of House and Senate roll-call votes to the bills you have signal on. Confidence floor preserves "insufficient data" honesty; state/local accountability is not claimed.

federal bills & congressional votes

The evidence base. Bills, House roll-call votes, and committee schedules through the shared api.data.gov key against api.congress.gov; Senate roll-call votes through voteview.com (zero-key).

rep finder

Reps-by-address with a zero-key local shapefile path, or the Geocodio API path when you configure that key. Needed before any accountability score can be computed.

ballot & election prep

Contest-by-contest prep for upcoming elections via Google Civic — the only wired ballot source today.

recurring monitoring

Plugin-owned cron templates plus a saved cadence that controls which default jobs stay enabled. Feeds the weekly digest and monthly rep report — see recurring monitoring for what the jobs do over time.

candidate finance research

FEC OpenFEC lookups through the same api.data.gov key, scoped for candidate and committee research.

draft-only outreach

Drafts letters, public comments, and testimony grounded in the bill text and your own saved stance — you send them yourself.

first successful run

01install

install the plugin from ClawHub

Install into a running OpenClaw gateway, then reload the gateway (or restart the OpenClaw app) so the new tools register.

openclaw plugins install clawhub:@politiclaw/politiclaw

Prefer npm? openclaw plugins install @politiclaw/politiclaw works too.

02verify

check the runtime

From inside OpenClaw, confirm the plugin registered and storage looks healthy:

/politiclaw-version
/politiclaw-doctor

03seed

start setup, then verify reps

Use the setup slash command for the next prompt, then ask the agent to call the setup tool with your address.

/politiclaw-setup
# ask the agent to call politiclaw_configure with your address
politiclaw_get_my_reps   # optional agent-tool verification

Need the long version? See installation & verification and configuration.

sources & trust

Runtime-backed reference pages — tools, config schema, source coverage, cron jobs, skills, storage schema — are generated from the current implementation. Prose guides stay short and practical because the exact facts live in the generated pages next door.

not legal

PolitiClaw is not legal advice. It helps you find, read, and act on public-record civic information. For legal interpretation, talk to a lawyer; for voting rules, trust your Secretary of State over the bot.

privacy

Structured state stays in plugin-owned local storage. External calls happen only when a tool needs a provider-backed answer. See privacy & storage for the full boundary.

start here

01 · task

see how my reps align

The accountability spine — find your delegation, score each rep against your declared stances, and read the per-issue breakdown with cited votes.

→

02 · task

understand my ballot

Fold accountability context into the next ballot. Start with the highest-value ballot workflow instead of piecing it together yourself.

→

03 · task

research candidates

Start from the single-candidate workflow before opening the more detailed race-comparison path.

→

04 · task

draft outreach

Turn accountability findings, bill research, or ballot prep into a draft the user can send themselves.

→

07 · experience

recurring monitoring

What the recurring monitoring jobs actually produce — when they speak, when they stay silent, what each one watches.

→

08 · experience

how accountability works

The loop from declared stances through scored reps to a draft letter you send yourself. Includes the dissenting-view rule.

→

09 · experience

example alerts

What a well-formed rep-vote hit, weekly digest, and quiet-window silence look like — and what a bad alert would look like.

→

10 · task

manage monitoring

Use cadence as the main control for the weekly digest and the monthly rep accountability report.

→

11 · config

configuration

The three wired keys (apiDataGov, googleCivic, geocodio) and the gateway-restart contract.

→

12 · reference

runtime reference

Drop to the generated reference when you need exact tool schemas, config keys, or source coverage facts.

→