HeaderKit

An open-source browser extension for modifying HTTP request & response headers.

Install from Chrome Web Store

简体中文

---

HeaderKit is a lightweight, privacy-friendly alternative to ModHeader. It lets you configure browser request headers with flexible filters. The companion HeaderKit CLI enables agents to adjust the extension's configuration and control browser requests.

Everything runs locally in your browser; there are no accounts, no servers, and no telemetry.

Features

• Profiles — group rules into named, colour-coded containers you can toggle independently. Multiple profiles can be active at once.
• Rule types — request headers, response headers, cookies, and redirects.
  • Header actions: set (default), append, remove.
  • Response-header rules can override security headers such as CSP and X-Frame-Options.
  • Cookie rules are structured sugar over the Cookie / Set-Cookie headers.
  • Redirects support a static whole-URL target and regex capture-group substitution.
• Filters — limit which requests a profile affects by:
  • URL — enter a domain (subdomains included) or a URL with * wildcards; a regex mode is available for advanced matching. Usable as include or exclude rules.
  • Tab — lock a profile to a specific open tab.
  • Window — lock a profile to a specific browser window.
  • Resource type — map to declarativeNetRequest resource types.
• Three-level switches — a global pause, per-profile toggles, and per-rule toggles. A rule is only compiled when all three are enabled.
• Import / export — export and import HeaderKit's native JSON format, and import profiles from ModHeader.
• Toolbar feedback — a badge showing the number of active rules.
• One shared UI — the same React interface as a toolbar popup or a full browser tab ("Open in Tab").
• Agent-friendly automation — let coding agents inspect and update browser header profiles through the HeaderKit CLI. Its JSON-lines machine mode pairs with the extension over a local WebSocket (Agent Mode).

Browser support

Browser	Status	Mechanism
Chrome / Edge	Primary target (MV3)	declarativeNetRequest (DNR)
Firefox	Secondary target	webRequest (capability may differ)

Installation

Install HeaderKit directly from the Chrome Web Store.

Connect an agent with the CLI

HeaderKit provides a machine-readable CLI so an agent can configure request headers, response headers, cookies, redirects, and filters in your browser:

npx headerkit --json

Then open the extension popup and click Connect CLI. Once the CLI emits {"event":"paired"}, the agent can send commands over stdin and consume one JSON response per stdout line. See the CLI guide for setup, commands, and the pairing protocol.

Development

Prerequisites

• Node.js 18+ and npm
• Chrome, Edge, or Firefox

Install dependencies

npm install

Develop

# Chrome / Edge
npm run dev

# Firefox
npm run dev:firefox

WXT launches a browser with the extension loaded and hot-reloads on changes.

Build

# Chrome / Edge
npm run build

# Firefox
npm run build:firefox

# Produce a distributable zip
npm run zip

Build output is written to .output/.

Load an unpacked build manually

1. Run npm run build.
2. Open chrome://extensions, enable Developer mode.
3. Click Load unpacked and select .output/chrome-mv3/.

Test & type-check

npm test        # run the unit tests once
npm run test:watch
npm run compile # wxt prepare + tsc --noEmit

Project structure

entrypoints/
  background.ts        # reconciles DNR rules from stored profile data
  popup/               # shared React UI (popup + full tab)
src/
  core/                # profile model, compile, reconcile, storage, import/export
public/                # extension icons and static assets
docs/adr/              # architecture decision records
CONTEXT.md             # domain glossary (ubiquitous language)
wxt.config.ts          # WXT + manifest configuration

Tech stack

• WXT — the browser-extension framework
• React 19 + TypeScript
• Tailwind CSS 4
• Vitest for testing

Contributing

Issues and pull requests are welcome. Before opening a PR:

1. Run npm test and npm run compile to make sure tests and types pass.
2. Follow the conventions in AGENTS.md.

License

Released under the MIT License. © 2026 GeoffZhu.