overview/politiclaw

overview · v0.0.16 · openclaw plugin

politiclaw

Holds your representatives accountable to the values you declare. Guides for the common tasks. Reference pages generated from the live plugin when you need exact schemas.

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

Check how your House and Senate reps voted against the stances you saved — with citations, and clear gaps when data is thin.

→

02 · start

getting started

Install, sanity-check, then get your first real answer in a few steps.

→

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?

In practice: save the stances you care about, then use ballot prep, candidate finance research, and draft-only outreach against that same stance list. Drafts stay on your machine until you send them — PolitiClaw never posts or mails for you.

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 tools and slash commands with your OpenClaw gateway (plus a local dashboard route). Under the hood, those tools talk to provider adapters (api.congress.gov for federal bills, House votes, and committee schedules — key from api.data.gov; voteview.com for Senate votes; Google Civic for ballots; optional Geocodio for reps-by-address; FEC OpenFEC via the same api.data.gov key). The agent can call tools like politiclaw_doctor, politiclaw_configure, politiclaw_issue_stances, politiclaw_get_my_reps, politiclaw_election_brief, and more. Cron templates install when you finish setup/politiclaw_configure, and the gateway runs them on your chosen cadence.

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. It matches their roll-call votes to bills you've already weighed in on — no guessed positions. If there aren't enough matching votes, it says so instead of inventing a score. 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 — look up a federal candidate, or compare filed challengers for your stored reps.

draft-only outreach

Drafts letters and short call scripts grounded in the bill text and your saved stance — you send or dial yourself. There is no send path.

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

Check how your House and Senate reps voted against the stances you saved — with citations, and clear gaps when data is thin.

→

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 you send yourself.

→

05 · experience

recurring monitoring

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

→

06 · experience

how accountability works

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

→

07 · 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.

→

08 · task

manage monitoring

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

→

09 · config

configuration

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

→

10 · reference

runtime reference

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

→