pigeongov_

Documentation

Everything you need to know about PigeonGov — from your first npx pigeongov to building custom workflow plugins.

Quick start

Getting Started

PigeonGov is a local-first CLI for US government workflows. Install it, run a workflow, get a validated bundle. No accounts, no cloud, no nonsense.

Install

install
$ npm install -g pigeongov # or run without installing: $ npx pigeongov

Your first workflow

getting started
# List all 36 workflows $ npx pigeongov workflows list # Fill a federal tax return interactively $ npx pigeongov fill tax/1040 # Fill with JSON input/output $ npx pigeongov fill immigration/family-visa-intake --json --data ./input.json # Check your environment $ npx pigeongov doctor --json

JSON mode

Every command supports --json for structured machine output. Exit codes are deterministic across 11 values (0–10) — see the full exit code table in the agent integration section.

json mode
# Get structured output from any workflow $ npx pigeongov fill tax/1040 --json --data ./return.json # Validate an existing bundle $ npx pigeongov validate ./1040-bundle.json --json # Review with structured summary $ npx pigeongov review ./1040-bundle.json --json

Bubble Tea TUI

The full-screen Go terminal workspace supports multi-workflow navigation, evidence tracking, and local packet assembly.

tui workspace
# Launch the TUI workspace $ npx pigeongov tui # Open directly to a workflow $ npx pigeongov tui unemployment/claim-intake

Commands

CLI Reference

All commands support --json for structured output and --help for usage details.

cli reference
Core Workflow Commands pigeongov workflows list List all available workflows with domain, status, and audience. pigeongov workflows describe <id> Show detailed workflow description with sections, fields, and starter data. pigeongov fill <workflow-id> Interactive guided fill for a workflow. Supports --json and --data <file>. pigeongov validate <file> Validate a saved bundle JSON against workflow rules. pigeongov review <file> Print a human-readable review summary with flagged fields. pigeongov extract <pdf> Extract structured data from source PDFs (W-2, 1099, etc.). pigeongov merge <files...> Merge multiple workflow bundles into a combined packet. pigeongov start <workflow-id> Get starter data JSON for a workflow (useful for piping into other tools). Intelligence & Advisory pigeongov screen Universal eligibility screener. Interactive cross-program screening. pigeongov life-event <event-id> Get a prioritized action plan for a life event with deadlines and workflow mapping. pigeongov deadlines [workflow-id] Show filing deadlines and key dates for a workflow or all workflows. pigeongov fees <workflow-id> Show filing fees, processing times, and cost breakdowns. pigeongov glossary <term> Look up government terminology with official definitions and sources. pigeongov dependencies <workflow-id> Show cross-agency dependency graph for a workflow. pigeongov cliff --income <n> --household <n> Calculate benefits cliff points and safe raise targets. pigeongov cost <workflow-id> Estimate DIY vs. attorney costs for a workflow. pigeongov track <receipt-number> Track USCIS case status with processing time estimates. pigeongov guide Print the agent integration guide with pipeline steps. pigeongov example <workflow-id> Show a complete example bundle for a workflow. pigeongov student-loans transition SAVE plan transition advisor. Compare RAP, IBR, ICR, and Standard plans. pigeongov student-loans pslf Track PSLF progress with employer risk assessment. pigeongov student-loans compare Side-by-side repayment plan comparison table. pigeongov state-tax <code> State tax info and calculation for a supported state. pigeongov state-tax list List all supported state tax calculators. Workspace & Data pigeongov tui [workflow-id] Launch the full-screen Bubble Tea TUI workspace. pigeongov drafts list | delete | cleanup Manage workflow drafts in local storage. pigeongov vault add | list | get | link Encrypted local credential storage for sensitive fields. pigeongov profile show | set | import Manage reusable identity profiles across workflows. pigeongov stats Show usage statistics: workflows filled, bundles validated, drafts saved. pigeongov completions <shell> Generate shell completions for bash, zsh, or fish. Server & Integration pigeongov serve Start the MCP server for agent integration. Add --http for REST. pigeongov doctor Check environment setup, dependencies, and configuration. pigeongov machine <command> Machine-mode wrapper for deterministic exit codes and JSON output. pigeongov list Legacy alias for workflows list. Developer & Extension pigeongov scaffold <name> Generate a new workflow plugin scaffold with schema, builder, and tests. pigeongov plugins list | install | remove Manage workflow plugins in the local plugin directory. pigeongov testdata <workflow-id> Generate synthetic test data for a workflow. pigeongov schemas list List available form schemas by tax year.

Catalog

Workflows by Domain

PigeonGov includes 36 workflows across 13 government domains. All workflows share the same bundle contract, so the CLI, TUI, site, and MCP all inherit each workflow automatically.

Tax 1 workflow

tax/1040 Federal individual return with Schedule 1, C, B, D, and Form 8949.

Immigration 5 workflows

immigration/family-visa-intake Family visa packet checklist and evidence organizer.
immigration/naturalization N-400 eligibility with residence, physical presence, and civics.
immigration/green-card-renewal I-90 filing organizer for renewal or replacement.
immigration/daca-renewal DACA renewal eligibility and timeline tracking.
immigration/work-authorization I-765 EAD application organizer with category tracking.

Healthcare 2 workflows

healthcare/aca-enrollment ACA marketplace enrollment planner with FPL and subsidy estimation.
healthcare/medicare-enrollment Medicare eligibility with IRMAA and late enrollment penalty estimation.

Benefits 8 workflows

benefits/snap SNAP eligibility with FPL income tests and benefit estimation.
benefits/section8 Section 8 Housing Choice Voucher eligibility assessment.
benefits/wic WIC eligibility for women, infants, and children.
benefits/liheap LIHEAP home energy assistance eligibility.
benefits/medicaid MAGI-based Medicaid eligibility review.
benefits/ssdi-application SSDI intake with SGA check and five-step evaluation.
benefits/ssi SSI eligibility for aged 65+, blind, or disabled with asset tests and state supplements.
benefits/tanf TANF cash assistance with state-specific benefits and categorical eligibility chains.

Education 3 workflows

education/fafsa FAFSA readiness with dependency status and income documentation.
education/student-loan-repayment IDR comparison: SAVE, PAYE, IBR, ICR estimates.
education/529-planner 529 plan growth projection and state tax deductions.

Veterans 3 workflows

veterans/disability-claim VA disability claim with combined rating estimation.
veterans/gi-bill Post-9/11 GI Bill entitlement and housing allowance estimation.
veterans/va-healthcare VA healthcare priority group and copay estimation.

Identity 4 workflows

identity/passport Passport application readiness with document checklist.
identity/name-change Name change planning with cascading document updates.
identity/voter-registration Voter registration readiness with state deadlines.
identity/real-id REAL ID document readiness checker.

Legal 3 workflows

legal/small-claims Small claims case preparation with fee and statute of limitations.
legal/expungement Expungement eligibility with waiting period estimation.
legal/child-support-modification Modification threshold assessment with income change analysis.

Estate 3 workflows

estate/basic-will Will planning with assets, beneficiaries, and executor selection.
estate/power-of-attorney POA planning with agent selection and power scope.
estate/advance-directive Healthcare directive with preferences and agent selection.

Retirement 1 workflow

retirement/ssa-estimator Social Security benefit estimation at ages 62, 67, 70.

Unemployment 1 workflow

unemployment/claim-intake Claimant identity, separation facts, and wage evidence organizer.

Business 1 workflow

business/license-starter License, zoning, and entity-registration planner. (preview)

Permits 1 workflow

permits/local-permit-planner Local permit scoping and evidence collection. (preview)

Calculation

Tax Engine

Calculation pipeline

The tax engine is a pure, deterministic pipeline: gross income, adjustments, deductions (standard or itemized), taxable income, progressive bracket application, credits, withholding reconciliation. All math is side-effect-free.

tax calculation
$ npx pigeongov fill tax/1040 --json --data ./return.json Tax Calculation Pipeline Gross Income: $142,800.00 Adjustments: -$6,500.00 (HSA, IRA) AGI: $136,300.00 Deduction: -$29,200.00 (standard) Taxable Income: $107,100.00 Federal: $16,290.00 (progressive brackets) State (CA): $5,847.00 SE Tax: $2,119.00 Credits: -$4,000.00 (child tax credit x2) Bundle saved to ./1040-bundle.json

Supported forms

  • Form 1040 (core federal return)
  • Schedule 1 (additional income and adjustments)
  • Schedule B (interest and dividends)
  • Schedule C (self-employment)
  • Schedule D (capital gains and losses)
  • Form 8949 (sales and dispositions of capital assets)
  • W-2 intake and extraction
  • 1099-NEC intake
  • 1099-INT intake

State taxes

10 state calculators with progressive bracket support:

  • Full calculators: CA, NY, IL, PA, NC, MI, GA, VA, NJ, OH
  • No income tax: AK, FL, NV, NH, SD, TN, TX, WA, WY (returns $0)

Crypto & equity compensation

Form 8949 and Schedule D support capital gains/losses for crypto and equity transactions. Cost basis tracking, wash sale awareness, and short-term/long-term classification.

Decision support tools

  • What-if scenarios: Compare filing statuses, deduction strategies, and income levels
  • Audit risk scorer: IRS DIF-inspired heuristics for return anomaly detection
  • Missed deduction detector: Identify commonly overlooked deductions based on your profile
  • Contribution optimizer: Optimal 401k, IRA, and HSA contribution strategy
  • Multi-year carryforward: Track and apply carryforward items across tax years

Advisory

Intelligence Features

Life Event Engine

20 life events mapped to prioritized workflow sequences with deadlines. "I just lost my job" triggers unemployment, health insurance, benefits screening, and tax impact analysis in the right order.

life-event — job-loss
$ npx pigeongov life-event job-loss Life Event: Job loss Generating prioritized action plan... Action Plan (6 workflows) --- Phase 1: Immediate (this week) --- > unemployment/claim-intake (!) [DEADLINE: 7 days] File unemployment claim immediately > healthcare/aca-enrollment (!) [DEADLINE: 60 days] Enroll in ACA marketplace — loss of coverage is a qualifying event --- Phase 2: This month --- > benefits/snap Income drop may qualify your household for food assistance > benefits/medicaid Income-based Medicaid eligibility — check before marketplace --- Phase 3: When ready --- > tax/1040 Adjust withholding & estimated payments for changed income > retirement/ssa-estimator Recalculate projected benefits with updated work history Done. Run pigeongov fill <workflow-id> to start any workflow.
more life events
# Other supported life events: $ npx pigeongov life-event marriage $ npx pigeongov life-event retirement $ npx pigeongov life-event new-baby $ npx pigeongov life-event divorce $ npx pigeongov life-event death-in-family

Eligibility Screener

Cross-program eligibility screening for benefits workflows. Uses Federal Poverty Level calculations, household size, income tests, and program-specific rules. The screen command is a universal screener — run it without arguments for interactive cross-program screening, or pass --json for structured results.

universal screener
# Universal screener (checks all benefits programs) $ npx pigeongov screen Universal Eligibility Screener Checking 8 benefits programs... LIKELY ELIGIBLE benefits/snap est. $459/mo LIKELY ELIGIBLE benefits/medicaid MAGI-based LIKELY ELIGIBLE benefits/wic if applicable MAYBE ELIGIBLE benefits/liheap seasonal NOT ELIGIBLE benefits/section8 income above limit NOT ELIGIBLE benefits/ssdi SGA threshold not met # Get structured output for agents $ npx pigeongov screen --json

Cross-Agency Dependency Graph

Government workflows don't exist in isolation. Naturalization triggers voter registration, passport eligibility, tax filing changes, and benefits waiting period removal. The dependency graph maps these connections so you never miss a downstream action.

dependencies
$ npx pigeongov dependencies immigration/naturalization → identity/voter-registration Naturalized citizens become eligible to vote → identity/passport Can apply for US passport → tax/1040 Changes tax filing requirements ~ benefits/snap Removes 5-year waiting period Legend: → triggers ~ may affect

Benefits Cliff Calculator

A raise can cost you money. The cliff calculator shows exactly where your benefits drop off and calculates the "safe raise target" — the income level where you come out ahead even after losing benefits. Uses current FPL thresholds and program-specific phase-out rules.

benefits cliff
$ npx pigeongov cliff --income 28000 --household 4 Current Benefits: ● SNAP $345/mo ● Medicaid $600/mo ● WIC $75/mo Cliff Points: ! At $32,150 → lose SNAP (-$4,140/yr) ! At $34,279 → lose Medicaid (-$7,200/yr) Safe raise target: $42,000 # JSON output for agents $ npx pigeongov cliff --income 28000 --household 4 --json

USCIS Case Tracker

Track any USCIS case by receipt number. Returns current status and processing time estimates at the 50th, 75th, and 90th percentiles for the relevant service center. Note: This is the only PigeonGov command that makes a network call. It queries USCIS public APIs — no PII is sent, only the receipt number.

case tracker
$ npx pigeongov track WAC2590123456 Receipt: WAC2590123456 Status: Case Was Approved Processing Time Estimates: 50%: 6.5 months 75%: 9.0 months 90%: 12.0 months

Cost Estimator

Compare DIY costs (filing fees, biometrics, postage) against typical attorney fees for any workflow. Helps users make informed decisions about when professional help is worth it and when PigeonGov can save thousands.

cost estimator
$ npx pigeongov cost immigration/naturalization DIY (with PigeonGov): $770 - $790 With attorney: $2,270 - $8,290 You save: ~$4,500

Deduction Optimizer

Identifies missed deductions based on your income profile, employment type, and life circumstances. Compares standard vs. itemized deduction outcomes.

Contribution Optimizer

Calculates optimal retirement and tax-advantaged contributions across 401(k), traditional IRA, Roth IRA, and HSA accounts given your income and filing status.

v0.4.0

OBBB Act (2025 Tax Changes)

PigeonGov v0.4.0 implements the One Big Beautiful Bill Act tax changes:

  • Child Tax Credit: $2,200 per qualifying child (up from $2,000)
  • SALT Cap: $40,000 for MFJ/Single/HoH ($20,000 MFS)
  • Tip Income Deduction: 100% of W-2 tips up to $25,000 (AGI under $160K)
  • Overtime Deduction: 100% of overtime pay up to $10,000 (AGI under $160K)
  • Auto Loan Interest: Up to $10,000 for US-manufactured vehicles
  • Senior Deduction: Additional $2,000 (single) or $1,600/person (married) for age 65+
obbb act fields
$ npx pigeongov fill tax/1040 --json --data ./return.json OBBB Act Deductions Applied Tip Income Deduction: -$18,500.00 (W-2 tips, AGI qualifies) Overtime Deduction: -$8,200.00 (overtime pay, AGI qualifies) Auto Loan Interest: -$4,800.00 (US-manufactured vehicle) Senior Deduction: -$2,000.00 (age 65+, single filer) SALT (capped): -$40,000.00 (MFJ cap applied) Credits Child Tax Credit: -$6,600.00 ($2,200 x 3 qualifying children) Bundle saved to ./1040-bundle.json

v0.4.0

Capital Gains & Investment Income

Schedule D and Form 8949 are now fully wired to the tax calculator:

  • Long-term capital gains at 0%, 15%, or 20% preferential rates
  • Net Investment Income Tax (NIIT) at 3.8% for high earners
  • Capital loss netting with $3,000 annual deduction limit
  • Loss carryforward tracking
  • Qualified dividends at LTCG rates
capital gains
$ npx pigeongov fill tax/1040 --json --data ./investments.json Schedule D — Capital Gains Summary Short-term gains: $12,400.00 (8 transactions) Short-term losses: -$3,200.00 (2 transactions) Long-term gains: $45,800.00 (5 transactions) Long-term losses: -$8,100.00 (1 transaction) Tax Treatment Net ST gain: $9,200.00 → taxed at ordinary rates Net LT gain: $37,700.00 → taxed at 15% preferential rate NIIT (3.8%): $1,782.60 (MAGI above $250K threshold) Qualified dividends: $2,100.00 → taxed at LTCG rate Bundle saved to ./1040-bundle.json

v0.4.0

State Income Tax

10 state tax calculators integrated: CA, NY, IL, PA, OH, GA, MI, NC, NJ, VA. Plus recognition of 9 no-income-tax states.

state tax list
$ npx pigeongov state-tax list Supported State Tax Calculators Full calculators (10): CA California progressive, 1%–13.3% NY New York progressive, 4%–10.9% NJ New Jersey progressive, 1.4%–10.75% IL Illinois flat, 4.95% PA Pennsylvania flat, 3.07% OH Ohio progressive, 0%–3.75% GA Georgia progressive, 1%–5.49% MI Michigan flat, 4.25% NC North Carolina flat, 4.5% VA Virginia progressive, 2%–5.75% No income tax (9): AK, FL, NV, NH, SD, TN, TX, WA, WY
state tax calculation
$ npx pigeongov state-tax CA --income 95000 --status single California Income Tax Taxable income: $95,000.00 Filing status: Single Bracket Breakdown 1.00% on first $10,412 $104.12 2.00% on $10,413–$24,684 $285.44 4.00% on $24,685–$38,959 $570.96 6.00% on $38,960–$54,081 $907.26 8.00% on $54,082–$68,350 $1,141.44 9.30% on $68,351–$95,000 $2,478.44 Total CA tax: $5,487.66

v0.4.0

Student Loan Crisis Tools

The SAVE plan ended March 10, 2026. 7.5 million borrowers need to transition. PigeonGov helps:

  • pigeongov student-loans transition — Compare RAP, IBR, ICR, and Standard plans
  • pigeongov student-loans pslf — Track PSLF progress with employer risk assessment
  • pigeongov student-loans compare — Side-by-side plan comparison table

Critical deadline: Consolidate Parent PLUS loans before July 1, 2026.

student loan transition
$ npx pigeongov student-loans transition SAVE Plan Transition Advisor SAVE ended March 10, 2026. Comparing available plans... Loan balance: $48,200.00 Monthly income: $4,800.00 Plan Comparison RAP $285/mo 20 yr forgiveness total: $68,400 IBR $312/mo 25 yr forgiveness total: $93,600 ICR $408/mo 25 yr forgiveness total: $122,400 Standard $502/mo 10 yr payoff total: $60,240 Recommended: RAP — lowest monthly payment with forgiveness (!) Parent PLUS: consolidate before July 1, 2026
pslf tracker
$ npx pigeongov student-loans pslf PSLF Progress Tracker Qualifying payments: 87 / 120 Remaining: 33 payments (2 yr 9 mo) Employer: State University Medical Center Employer status: Verified 501(c)(3) Risk Assessment ● Employer qualifies as public service ● Payment plan is IDR-eligible ● Verify employment certification is current (last: 8 mo ago)

v0.4.0

New Benefits Workflows

Two new workflows join the benefits domain:

  • SSI (Supplemental Security Income) — Asset-based eligibility for aged 65+, blind, or disabled. Income exclusion math, state supplements for 10 states.
  • TANF (Temporary Assistance for Needy Families) — Cash assistance for families with children. State-specific benefits, categorical eligibility chains (TANF → auto-qualifies SNAP/Medicaid).
ssi eligibility
$ npx pigeongov fill benefits/ssi --json SSI Eligibility Assessment Category: Age 65+ Countable income: $482/mo (after $20 general + $65 earned exclusions) Resources: $1,850 (limit: $2,000 individual) LIKELY ELIGIBLE Federal benefit: $943/mo (2025 FBR) State supplement: +$160/mo (California SSP) Estimated total: $1,103/mo Categorical eligibility: SSI → auto-qualifies Medicaid in most states
tanf screening
$ npx pigeongov fill benefits/tanf --json TANF Eligibility Assessment State: Texas Household: 1 adult, 2 children Monthly income: $1,200 LIKELY ELIGIBLE Estimated benefit: $303/mo (TX family of 3) Time limit: 60 months lifetime (federal) Categorical chains: → TANF receipt auto-qualifies benefits/snap → TANF receipt auto-qualifies benefits/medicaid

v0.4.0

Life Events (20 Events)

Expanded from 12 to 20 life events with temporal deadlines and dependency ordering.

New events: lost-health-insurance, had-income-change, arrested-or-convicted, natural-disaster, turning-18, turning-26, child-turning-18, received-inheritance

Use --date to compute concrete deadline dates:

life-event with date
$ npx pigeongov life-event death-of-spouse --date 2026-03-15 Life Event: Death of spouse Event date: March 15, 2026 Action Plan (8 workflows) --- Phase 1: Immediate (this week) --- > estate/basic-will (!) [DEADLINE: Mar 22, 2026] Review/update your own estate documents > benefits/ssdi-application (!) [DEADLINE: Mar 22, 2026] Survivor benefits — notify SSA immediately --- Phase 2: Within 60 days --- > healthcare/aca-enrollment (!) [DEADLINE: May 14, 2026] Loss of spouse coverage is a qualifying event > tax/1040 Filing status changes — may file jointly for 2026 > identity/name-change Update documents if reverting to prior name --- Phase 3: Within 6 months --- > estate/power-of-attorney Designate new POA agent > retirement/ssa-estimator Recalculate with survivor benefit options > benefits/snap Income change may affect eligibility Done. Run pigeongov fill <workflow-id> to start any workflow.
new life events
# New life events in v0.4.0: $ npx pigeongov life-event lost-health-insurance $ npx pigeongov life-event had-income-change $ npx pigeongov life-event arrested-or-convicted $ npx pigeongov life-event natural-disaster $ npx pigeongov life-event turning-18 $ npx pigeongov life-event turning-26 $ npx pigeongov life-event child-turning-18 $ npx pigeongov life-event received-inheritance

Agent integration

For Agents

Structured output

Every CLI command supports --json for deterministic structured output. Agent-facing results always include flaggedFields with severity, field path, and human-readable explanation.

Exit codes

PigeonGov uses a full range of deterministic exit codes for machine consumption:

exit codes
Exit Code Reference 0 success Bundle is valid. Operation completed. 1 runtimeError Unexpected failure during execution. 2 hasWarnings Completed with warnings. Review flagged fields. 3 hasErrors Validation errors. Bundle has flagged fields. 4 invalidInput Missing or malformed input data. 5 notFound Workflow, draft, or resource not found. 6 permissionDenied Insufficient permissions for the operation. 7 conflict Resource conflict (e.g., draft already exists). 8 schemaError Schema validation failed. Data doesn't match spec. 9 dependencyMissing Required dependency not available. 10 timeout Operation timed out.

MCP tools (26)

mcp tools
Workflow Tools list-workflows List all workflows with domain, status, and audience filters. describe-workflow Detailed description with sections, fields, starter data, input schema. start-workflow Get starter data for a workflow. fill-workflow Fill a workflow with provided data and return the complete bundle. validate-workflow Validate a filled workflow bundle. review-workflow Get a structured review summary for a bundle. build-packet Build a complete packet from a filled workflow bundle. explain-flag Explain a specific flagged field with suggested next steps. Form Tools (legacy) list-forms List available form schemas by tax year. describe-form Describe a specific form schema. fill-form Fill a form with data. validate-form Validate a form. review-form Review a form. Intelligence Tools extract-document Extract structured data from a source document. calculate-tax Run the deterministic tax calculator. deadlines Get filing deadlines for a workflow. fees Get filing fees and processing times. glossary Look up government terminology. plan-life-event Get prioritized workflow plan for a life event. screen-eligibility Run eligibility screening for a benefits workflow. get-dependencies Get cross-agency dependency graph for a workflow. calculate-cliff Calculate benefits cliff points and safe raise targets. track-case Track USCIS case status by receipt number. estimate-cost Compare DIY vs. attorney costs for a workflow. student-loan-advisor SAVE transition advisor with plan comparison and PSLF tracking. calculate-state-tax Run state income tax calculation for supported states.

Agent guide

The pigeongov guide command prints the recommended agent pipeline. Point your agent at PigeonGov and it follows this flow automatically:

agent guide
$ npx pigeongov guide Agent Pipeline 1. Discover list-workflows → browse available workflows by domain 2. Initialize start-workflow → get starter data with field schema 3. Fill fill-workflow → populate with user data, get validated bundle 4. Review review-workflow → check flags, suggestions, and next steps Intelligence (optional) get-dependencies → what else does this workflow trigger? calculate-cliff → will a raise cost them benefits? estimate-cost → DIY vs. attorney cost comparison track-case → check USCIS case status

Agent discovery

discovery endpoints
# agents.json — structured capability manifest $ curl https://pigeongov.vercel.app/agents.json # llms.txt — plain-text agent instructions $ curl https://pigeongov.vercel.app/llms.txt # MCP endpoint $ curl https://pigeongov.vercel.app/mcp

Connect

agent setup
# Claude Code $ claude mcp add pigeongov -- npx pigeongov serve # Codex $ codex mcp add pigeongov -- npx pigeongov serve # Local HTTP server $ npx pigeongov serve --http Listening on http://127.0.0.1:3847/mcp

Extend

For Developers

Plugin system

Scaffold a new workflow with pigeongov scaffold my-workflow. This generates the Zod schema, builder function, test fixtures, and registry entry. Install third-party plugins with pigeongov plugins install <name>.

REST API

rest api
# Start the HTTP server $ npx pigeongov serve --http # List workflows GET http://127.0.0.1:3847/api/workflows # Fill a workflow POST http://127.0.0.1:3847/api/fill Content-Type: application/json { "workflowId": "tax/1040", "data": { ... } }

OpenAPI

The REST API serves an OpenAPI spec at /api/openapi.json when running in HTTP mode.

Testing

development
$ pnpm install $ pnpm test # Run all tests $ pnpm typecheck # TypeScript type checking $ pnpm build # Build the project $ pnpm build:mcp # Build MCP server $ pnpm build:mcp:vercel # Build for Vercel deployment

Adding a new workflow

  1. Add a workflow definition to src/workflows/domains/
  2. Define starter data, sections, evidence logic, and validation/review rules
  3. Register the domain in src/workflows/registry.ts
  4. Reuse the shared bundle contract — CLI, TUI, site, and MCP inherit automatically
  5. Add tests for registry behavior, CLI output, and MCP tool integration

Source

contribute
$ git clone https://github.com/CMLKevin/pigeongov.git $ cd pigeongov $ pnpm install $ pnpm test

Trust

Privacy

Local-first guarantees

  • All processing happens locally on your machine
  • No cloud account required for CLI, TUI, or local MCP server
  • No telemetry is sent
  • No user data is logged
  • SSNs are masked in terminal prompts
  • No hidden network calls with user data

What is logged

Nothing. PigeonGov does not phone home, track usage, or store analytics.

What is NOT logged

  • Tax returns and financial data
  • Personal identity information
  • Immigration status or case details
  • Health insurance or benefits data
  • Any PII whatsoever

Browser tools

The planner and reviewer are client-side surfaces. They run entirely in your browser. They do not submit data to any server. They do not submit to government agencies.