GitHub - defog-ai/factiq-plugin: Real-time economy+finance database for AI agents

Turn your agent into a finance and economy analyst. This plugin for Claude (web, desktop, and Cowork), ChatGPT Desktop, Claude Code, and Codex gives the agent direct access to FactIQ's warehouse of official statistics — SEC filings, US, China, India, Korea, IMF, World Bank, and more — plus live market data, earnings-call transcripts, executive media appearances, and satellite-derived data (fire detections, air-quality activity signals, rainfall, nighttime lights, shipping and port activity, reservoir levels). The agent discovers series, runs read-only SQL, computes derived metrics, and returns a sourced answer, terminal preview, or report JSON.

No codebase or hosted database is required — only a free FactIQ account.

Want to contribute? The highest-leverage addition is a domain playbook that teaches the agent a whole class of questions — see Contributing.

Install

FactIQ supports four client paths. The website guides are canonical for app setup and plan requirements, which can change faster than this repository:

Claude (web, desktop, and Cowork)

For the best experience, use Cowork. In Claude, open Customize → Plugins, add defog-ai/factiq-plugin as a personal marketplace, install FactIQ, and complete the browser sign-in. The full plugin requires a paid Claude plan; Claude Free can use the connector-only setup. See the Claude guide for the current steps, organization-policy notes, and connector-only alternative.

ChatGPT Desktop

In the ChatGPT desktop app, open Plugins, add defog-ai/factiq-plugin as a marketplace, install FactIQ from the Personal tab, and complete the browser sign-in. Custom plugins currently require a ChatGPT Pro, Business, Enterprise, or Edu plan. This installation also covers Codex inside the ChatGPT app; Codex CLI uses the separate setup below. See the ChatGPT guide for the current plan matrix and troubleshooting steps.

Claude Code

/plugin marketplace add defog-ai/factiq-plugin
/plugin install factiq@factiq
/reload-plugins

Run /reload-plugins after installing so Claude Code picks up the new skill and MCP server in the current session (otherwise they only appear the next time you start Claude Code).

This adds the FactIQ skill (Claude invokes it automatically for economic/financial data questions) and the bundled FactIQ MCP server. Claude Code namespaces skills installed from plugins, so its manual invocation is:

Finally, authenticate the MCP server:

1. Run /mcp.
2. Select factiq from the list of servers.
3. Choose Authenticate (or Connect) to open the browser sign-in.
4. Complete the FactIQ login (email, Google, or passkey) and return to Claude Code — the FactIQ tools are now authorized.

Codex

codex plugin marketplace add defog-ai/factiq-plugin
codex plugin add factiq@factiq

Then authorize the MCP server:

Complete the browser sign-in (the same FactIQ login: email, Google, or passkey). Start a new Codex thread after installation; the skill auto-invokes for economic/financial data questions.

codex plugin marketplace upgrade factiq
codex plugin add factiq@factiq

[mcp_servers.factiq]
url = "https://api.factiq.com/mcp"

claude mcp add --transport http factiq https://api.factiq.com/mcp

Try it

Once installed and authenticated, ask a question:

/factiq:factiq How has India's trade deficit with China evolved since 2020?

The agent finds the relevant series, runs the SQL, and replies with a sourced answer, terminal chart, or full report, depending on what you ask for. You don't need the slash command: any economic or financial data question in any supported client auto-invokes the skill.

For an earnings question such as "What did Micron management say on its latest call?", the skill checks live transcript coverage first, pins the exact fiscal quarter, and then retrieves bounded management-claim and Q&A-pressure rows for that same call. It keeps spoken remarks separate from formal guidance and SEC filed actuals; the tool does not return a raw transcript.

For a media question such as "How has Jensen Huang discussed export controls outside earnings calls?", the skill checks company-level structured coverage, runs deterministic lexical retrieval with relevance ordering, and uses explicit newest ordering only for a timeline. Results are public-safe paraphrases with timestamped YouTube links, not quotations; the workflow verifies the linked source when exact wording or tone is material. A dedicated playbook also keeps media-vs-earnings comparisons aligned by company, person, topic, and date.

How it works

Your coding agent is the analyst: it finds the data, does the math, and authors a local output. Data access uses the FactIQ MCP server bundled in .mcp.json over one OAuth connection.

┌─────────────────────────────┐
│  Claude / ChatGPT /         │
│  Claude Code / Codex        │
│  + factiq skill (SKILL.md)  │      the agent orchestrates everything
└──────────────┬──────────────┘
               │  MCP over HTTP (one OAuth connection)
┌──────────────▼──────────────┐
│  FactIQ MCP server          │
│                             │
│  discover   search_datasets, describe_dataset, search_series,
│             get_data_catalog
│  fetch      run_sql (read-only), get_series, get_market_data,
│             search_company_filings, search_earnings_transcripts,
│             search_media_appearances, search_news
└──────────────┬──────────────┘
               │
┌──────────────▼──────────────┐
│  FactIQ data warehouse      │      official and derived data sources
└─────────────────────────────┘

The reason a single skill can query BLS unemployment, Chinese customs flows, RBI monetary data, and World Bank indicators with the same SQL idioms: every data source in the backend is normalized into the same three core tables, identical in every schema:

Our ingestion pipelines do the hard work of flattening each source's bespoke format — BLS flat files, BEA APIs, customs records, RBI releases — into this shape, so the agent learns the model once and it works everywhere. Discovery, pivoting, and filtering follow the same patterns across all ~20 schemas; the recipes live in references/data/sql-guide.md.

What's in the warehouse

references/data/schemas.md has the static overview; the get_data_catalog tool returns the live, authoritative version.

Repo map

Where the behavior lives — the files contributors will touch:

• skills/factiq/SKILL.md — the skill definition and single source of truth for the workflow. Auto-discovered by supported plugin clients from the skills/ directory
• references/data/ — the data layer: SQL idioms (sql-guide.md) and the dataset schema overview (schemas.md)
• references/output/ — local output formats: ChartSpec (chart-spec.md) and report JSON (report-spec.md)
• references/report-patterns/ — domain playbooks (monetary policy, bilateral trade, bilateral economic policy, fiscal-policy revenue, business formation, earnings intelligence, media-appearance intelligence). report-patterns/README.md is the single entry point SKILL.md references: it teaches the dialectical method (thesis → antithesis → synthesis) all reports follow and routes each domain to its playbook, so adding a playbook doesn't touch SKILL.md
• scripts/term_chart.py — stdlib-only renderer for ANSI/ASCII previews from FactIQ ChartSpec and report JSON objects. It supports bar, simple line, and table fallback renderers

Plugin plumbing — you shouldn't need to touch these:

• .mcp.json — declares the bundled FactIQ MCP server (Streamable HTTP, OAuth). Read by both Claude Code and Codex plugin loaders
• .claude-plugin/ — Claude and Claude Code plugin + marketplace manifests
• .codex-plugin/ — ChatGPT and Codex plugin manifest
• .agents/plugins/marketplace.json — Codex marketplace entry for codex plugin marketplace add defog-ai/factiq-plugin

Contributing

Contributions are welcome — this plugin is meant to grow with its community. Open an issue or a pull request.

Bespoke skills (domain playbooks) — the highest-leverage contribution

The most valuable thing you can add is a domain playbook: a reference file that teaches the agent how to answer a whole class of questions well. A playbook is a domain's dialectic written down in advance — the headline reading a question invites, the contradictions a competent skeptic would raise against it, and the SQL to fetch both (see the method in references/report-patterns/README.md). The existing ones live in references/report-patterns/ and are the pattern to follow:

• monetary-policy.md — central bank policy stance, administered rates, OMO, balance-sheet context
• bilateral-trade.md — country-pair trade trends, product drivers, mirror-statistics caveats
• fiscal-policy-revenue.md — government receipts, tax composition, distributional detail

A good playbook contains:

1. A trigger — which question shapes it covers ("latest trend in trade between A and B", "explain the Fed's stance"), added as a row to the routing table in references/report-patterns/README.md so the agent reads the playbook before fetching. SKILL.md points at that router, so it doesn't need to change.
2. Required coverage — the domain's canonical antitheses: the counter-checks a complete answer must fetch (mirror statistics, real vs nominal, composition, the counterparty's ledger), so the agent doesn't stop at the first obvious chart.
3. Ready SQL templates — tested queries against the three-table schema for the key computations (latest-month YoY, YTD comparisons, top-N drivers).
4. Caveats and guardrails — unit normalization, base-year changes, national-vs-subnational traps, data gaps to disclose explicitly.

Ideas we'd love to see: labor-market health, inflation decomposition, energy markets, housing, sovereign debt, sector earnings analysis, country macro-risk snapshots.

Other welcome contributions

• Terminal renderers — new chart types or better ASCII/ANSI output in scripts/term_chart.py (keep it stdlib-only).
• SQL idioms and pitfalls — additions to references/data/sql-guide.md from real usage.
• Docs and fixes — anything that makes the agent's first attempt land.

Test a playbook by running its questions end to end and checking the saved chart or report output. Include exact before-and-after examples in the PR.

Security

No secrets belong in this repo, and the plugin holds none — all access goes through the MCP server's OAuth flow, so the coding agent holds the token and nothing is written here. All SQL runs read-only against FactIQ's data warehouse.

License

MIT