pi-news-api

A live news briefing extension for the Pi coding agent, powered by the Currents News API.

pi-news-api adds agent-callable Currents News tools and a Pi-native header widget that pulls live headlines from the Currents News API, lets you toggle Currents' 16 canonical news categories, run keyword searches, and queue a deep-dive research prompt for any story you pick.

| Resource | Link | | --- | --- | | GitHub | github.com/currentslab/pi-news-api | | License | MIT | | Changelog | CHANGELOG.md | | Security policy | SECURITY.md | | Contributing guide | CONTRIBUTING.md | | Compatibility notes | docs/COMPATIBILITY.md | | Currents API docs | https://currentsapi.services/en/docs/ |

Why this package

This package is for Pi users who want a lightweight, always-available general news surface inside the TUI, backed by a single API instead of a fixed list of RSS feeds.

What it does well:

• Live category feed — fetches enabled Currents categories in one /v2/latest-news request per refresh
• Readable Pi widget — width-aware rendering, same discipline as other Pi header widgets
• Interactive category management — /news_categories opens a simple TUI category manager
• Keyword search — /news_search <keywords> queries Currents' /v2/search endpoint directly, independent of the category toggle list
• Agent-callable news — Pi can invoke news_get_latest, news_search, and news_configure from ordinary user requests
• Deep-dive handoff — /news_menu queues a focused research prompt for a selected headline
• Persistent settings — enabled categories and language choice persist across Pi sessions in ~/.config/pi-news-api/config.json
• Local interest learning — successful searches retain a bounded topic frequency profile, infer category preferences, and personalize later default briefings without saving article history
• Ephemeral banner behavior — the widget shows a short-lived headline banner, then disappears instead of lingering during long agent/subagent work
• Pi-native packaging — installable through npm as a normal Pi package

Design philosophy

This package is intentionally a small, TUI-native news briefing extension for Pi, built around what the Currents API actually offers rather than imitating a multi-RSS-feed design:

• Currents already returns structured category metadata per article, so the widget uses Currents' own 16-category taxonomy instead of guessing topics from headline keywords.
• Currents serves many categories from a single authenticated request, so the widget makes one /v2/latest-news call per refresh instead of one call per enabled category. This matters because the free tier caps at 1,000 requests per day.
• It keeps persistence lightweight with a single user-level JSON file for category and language state.
• It tries to be explicit about what is confirmed by the linked article versus what Pi may infer during a deep-dive follow-up.

Stability guarantees

Current guarantees:

• published command names are treated as stable once released
• the widget remains width-aware and should not guess based on full terminal width
• category and language state persist through the documented ~/.config/pi-news-api/config.json file
• commands remain available for direct control while agent tools support ordinary natural-language requests

Trust, safety, and operating model

This extension is intentionally narrow in scope.

Important expectations:

• It registers three documented LLM-callable tools alongside Pi commands, a widget, and lifecycle hooks
• It calls the Currents News API over HTTPS; no other third-party service is contacted
• It requires a Currents API key via the CURRENTS_API_KEY environment variable — never hardcode the key in config files, prompts, or logs
• It creates ~/.config/pi-news-api/config.json for category, language, and local interest preferences; it never writes the API key or article history to disk
• Choosing a story from /news_menu or /news_search sends a hidden user-style message into Pi to trigger a research turn
• Category/language state persists globally in ~/.config/pi-news-api/config.json; legacy Pi session entries are only used for migration/fallback
• Deep-dive output quality depends on the current model and the available public reporting behind the selected headline

Need an API key?

Register for a free Currents API key (1,000 requests/day): https://currentsapi.services/en/register

Install

Install into Pi as a package:

pi install npm:pi-news-api

Use it for a single run without changing your settings:

pi -e npm:pi-news-api

Run it from this repository during local development:

pi -e .

Set your API key

pi-news-api reads CURRENTS_API_KEY from the process environment at runtime. It never displays or persists this variable. Pi does not load a general-purpose .env file for extensions, so inject the key before starting Pi. On macOS, the key can remain in Keychain:

security add-generic-password -a "$USER" -s pi-news-api-currents -U -w
CURRENTS_API_KEY="$(security find-generic-password -a "$USER" -s pi-news-api-currents -w)" pi

If the key is missing, the widget shows a setup notice instead of failing silently, and commands that call the API return a clear error.

Quick start

A typical flow:

/news_categories
/news_enable health
/news_refresh
/news_menu
/news_interests

Keyword search works independently of the category toggles:

/news_search quantum computing

You can also ask Pi to help operate the extension in plain English, for example:

Enable the health category in pi-news-api
Show me the latest science and technology headlines
Search pi-news-api for "central bank interest rates"
Set the pi-news-api language to Spanish

Pi can call the news tools directly from a natural-language request and use the returned, source-linked results to prepare a concise briefing.

Commands

| Command | Description | | --- | --- | | /news_menu | Open a headline picker for deep-dive research on a story. | | /news_refresh | Refresh the widget with the latest headlines from enabled categories. | | /news_categories | Open the category manager in TUI, or print category status in non-TUI mode. | | /news_enable <category name> | Enable a category by exact or partial name. | | /news_disable <category name> | Disable a category by exact or partial name. | | /news_search <keywords> | Search Currents News for a keyword or phrase and pick a result for deep-dive research. | | /news_interests [on\|off\|clear] | Inspect, enable, disable, or clear locally learned topic/category interests. | | /news_language <code> | Set the language filter (ISO 639-1 code, e.g. en, es, fr). |

Agent tools

| Tool | Purpose | | --- | --- | | news_get_latest | Fetch recent source-linked headlines using saved, requested, and learned categories. | | news_search | Search Currents by keyword or phrase and return structured article metadata and URLs. | | news_configure | Inspect settings or explicitly change categories, language, and interest tracking. |

Tool results label article metadata as untrusted source data. The model should verify reporting before presenting article claims as confirmed facts.

Interest personalization

Interest tracking is enabled by default. After each successful /news_search or agent news_search call, the extension stores only:

• the normalized search topic, search count, and last-search timestamp
• inferred Currents category counts and last-search timestamps

Privacy: The personalization profile is stored only on this machine in ~/.config/pi-news-api/config.json. Raw topic history, counts, timestamps, and interest weights are never uploaded as a profile. Personalized news requests send only the resulting category slugs to Currents, because those filters are required to fetch matching news. An explicit search also sends its query to Currents. Detailed topic history is shown only by the local /news_interests command and is not returned through agent tools.

It keeps at most 20 topics. Interest scores decay with a 30-day half-life, so old searches gradually matter less. Up to two strongest learned categories are merged with explicitly enabled categories for the next default briefing, and matching headlines rank higher within the same freshness bucket.

Personalization remains a single /v2/latest-news request: it does not issue one request per topic. Raw article history, titles, URLs, and API credentials are not stored in the interest profile.

Use /news_interests to inspect the profile, /news_interests off to pause learning and personalization, or /news_interests clear to erase learned topics and categories. Agent requests can perform the same explicit actions through news_configure. Full usage: /news_interests [on|off|clear].

Turn personalization off immediately with:

/news_interests off

You can also tell Pi, “Turn off news personalization.” The agent can invoke news_configure with disable_interest_tracking without receiving the raw topic history. Turning it off preserves the local profile for a later /news_interests on; use /news_interests clear to delete the profile entirely.

Widget behavior

The widget:

• renders above the editor
• shows fresh, prioritized headlines from selected and learned categories
• displays the number of locally learned topics when interest tracking has data
• filters dated items older than 7 days when fresher headlines are available, so old stories do not stay pinned
• disappears after 60 seconds unless you manually refresh it again
• clears itself as soon as Pi starts an active agent run, so it does not linger over long tool or subagent activity
• keeps layout bounded to the widget width instead of guessing based on the full terminal width
• shows a setup notice instead of a network error when CURRENTS_API_KEY is unset

Categories

Currents' canonical /v2 category taxonomy. general, politics_government, and science_technology are enabled by default. Category and interest choices persist globally in ~/.config/pi-news-api/config.json; the folder and JSON file are created automatically when the extension starts.

| # | Category | Icon | Default | | --- | --- | --- | --- | | 1 | General | 🌍 | ✅ enabled | | 2 | Politics & Government | 🏛️ | ✅ enabled | | 3 | Economy, Business & Finance | 💰 | ❌ disabled | | 4 | Science & Technology | 🔬 | ✅ enabled | | 5 | Health | 🏥 | ❌ disabled | | 6 | Society | 🏙️ | ❌ disabled | | 7 | Environment | 🌱 | ❌ disabled | | 8 | Crime, Law & Justice | ⚖️ | ❌ disabled | | 9 | Sport | ⚽ | ❌ disabled | | 10 | Arts, Culture & Entertainment | 🎭 | ❌ disabled | | 11 | Lifestyle & Leisure | 🧘 | ❌ disabled | | 12 | Human Interest | ❤️ | ❌ disabled | | 13 | Education | 🎓 | ❌ disabled | | 14 | Labour | 👷 | ❌ disabled | | 15 | Automotive | 🚗 | ❌ disabled | | 16 | Real Estate | 🏠 | ❌ disabled |

Deep-dive workflow

A typical flow looks like this:

1. Start Pi with the package enabled and CURRENTS_API_KEY set
2. Let the widget populate from the enabled categories
3. Run /news_menu (or /news_search <keywords>)
4. Pick a story
5. Pi receives a hidden follow-up prompt asking for:
   • Executive Summary
   • Why It Matters
   • Key Facts / Context
   • Open Questions or Uncertainties
   • What to Watch Next

Repository layout

dist/                     Compiled extension output committed to the repo
index.ts                  TypeScript source
tests/                    Non-network unit and package-structure tests
docs/COMPATIBILITY.md     Compatibility notes
README.md                 User-facing package documentation
AGENTS.md                 Maintainer and agent guidance
CONTRIBUTING.md           Contributor workflow
SECURITY.md               Vulnerability reporting policy
CHANGELOG.md              Release history

Compatibility

Current project expectations:

• Node.js >=20
• Pi extension runtime support
• outbound HTTPS access to api.currentsapi.services
• a valid CURRENTS_API_KEY

See docs/COMPATIBILITY.md for the maintained notes.

Development

npm install
npm test
npm pack --dry-run

The test suite covers:

• Currents article normalization and deduplication
• category-query matching behavior
• widget line-width formatting guarantees
• rate-limit header parsing and error-message behavior
• package metadata and publish-file expectations

Publishing

npm pack --dry-run
npm publish

Versioning and release discipline live in AGENTS.md.

Support and feedback

When reporting problems, include the package version, Pi version, command used, and category or search query if relevant. Never include your CURRENTS_API_KEY in a bug report.

See also

• AGENTS.md — maintainer and agent guidance
• CHANGELOG.md — release history
• CONTRIBUTING.md — contributor workflow
• SECURITY.md — security policy
• docs/COMPATIBILITY.md — compatibility notes

License

MIT — see LICENSE.