Thunderbird Agent

Thunderbird Agent turns a local Thunderbird profile into a CLI-first automation surface for AI agents.

It lets Claude Code, Codex, OpenClaw, Hermes, and any other shell-capable agent safely work with:

mail search and message retrieval
draft / reply / forward workflows
folder cleanup and tagging
filter CRUD and manual application
contacts, calendars, and tasks

The architecture is intentionally simple:

Thunderbird extension — the execution engine and permission boundary
shared transport core — connection discovery, auth, retry, JSON-RPC over localhost
local CLI — the primary agent-facing interface
repo-local instructions + skill — reusable guidance across agent runtimes

Project origin

This repository was directly refactored from TKasperczyk/thunderbird-mcp, which was the concrete starting point for this work.

That upstream README also credited bb1/thunderbird-mcp as an earlier inspiration, but this project's direct source repository for the current rewrite was TKasperczyk/thunderbird-mcp.

Thunderbird Agent is now a downstream rewrite with a narrower, different scope:

renamed to thunderbird-agent
CLI-first instead of MCP-first
no MCP compatibility layer
vendor-neutral instructions and skill surfaces for multiple AI agents

No upstream demo media is embedded in this README; any future demo assets should be recorded specifically for this repository.

Why this project exists

Thunderbird is a rich local mail client, but most AI tooling still assumes either browser automation or remote SaaS APIs. Thunderbird Agent closes that gap with a localhost-only integration layer that keeps mail inside Thunderbird while giving AI agents high-level tools to read, draft, organize, and inspect.

The default posture is conservative:

compose flows open review UI before send
account/tool access is user-configurable in the extension
auth tokens are session-scoped and stored in a local connection file
there is no remote listener and no cloud relay

Quick start

1. Clone the repository

git clone https://github.com/buddhism5080/thunderbird-agent.git
cd thunderbird-agent

2. Build the extension artifact

npm run build

This produces:

dist/thunderbird-agent.xpi
a refreshed shared/tool-catalog.json

3. Install the extension in Thunderbird

In Thunderbird:

Tools → Add-ons and Themes
click the gear menu
Install Add-on From File...
choose dist/thunderbird-agent.xpi
restart Thunderbird

Or from the repository root on a local workstation:

./scripts/install.sh

4. Verify the CLI can see Thunderbird

node packages/cli/thunderbird-agent.cjs doctor

5. Call tools directly

node packages/cli/thunderbird-agent.cjs tools list
node packages/cli/thunderbird-agent.cjs tools call searchMessages --args '{"query":"invoice","maxResults":10}'

If installed globally:

thunderbird-agent doctor
thunderbird-agent tools list

Tool surface

Thunderbird Agent currently exports 36 tools across six categories.

Mail

listAccounts
listFolders
searchMessages
getMessage
getRecentMessages
displayMessage
updateMessage
deleteMessages
createFolder
renameFolder
moveFolder
deleteFolder
emptyTrash
emptyJunk

Compose

sendMail
replyToMessage
forwardMessage

Filters

listFilters
createFilter
updateFilter
deleteFilter
reorderFilters
applyFilters

Contacts

searchContacts
createContact
updateContact
deleteContact

Calendar and tasks

listCalendars
createEvent
listEvents
updateEvent
deleteEvent
createTask
listTasks
updateTask

Access control visibility

getAccountAccess

For the authoritative machine-readable catalog, use:

node packages/cli/thunderbird-agent.cjs tools list --catalog

CLI reference

thunderbird-agent doctor
thunderbird-agent tools list
thunderbird-agent tools list --catalog
thunderbird-agent tools call searchMessages --args '{"query":"from:alice report","maxResults":5}'
thunderbird-agent rpc --request '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Commands:

doctor — validate connection discovery and live access
tools list — enumerate live tools from a running Thunderbird session
tools list --catalog — inspect the offline exported catalog
tools call <name> --args <json> — invoke one tool and print JSON output
catalog [show <name>] — inspect the shared tool catalog
rpc --request <json> — send raw JSON-RPC to the localhost transport for debugging

Agent integration surfaces

This repository intentionally optimizes for repo-aware, terminal-capable agents, not for a shared runtime protocol.

Primary surfaces:

AGENTS.md — repo-level instructions for broad agent runtimes
CLAUDE.md — Claude Code specific companion guidance
skills/thunderbird-agent/SKILL.md — reusable Thunderbird workflow skill
docs/agents/ — concise integration notes for Claude Code, Codex, and OpenClaw

Start here:

docs/README.md
docs/agents/README.md

Build and packaging

Canonical build commands

npm run check:versions
npm run build:catalog
npm run build:xpi
npm run build
npm run pack:check

What they do:

check:versions — enforce that package.json and extension/manifest.json use the same release version
build:catalog — re-export shared/tool-catalog.json
build:xpi — produce dist/thunderbird-agent.xpi without mutating the source tree
build — run the full local release pipeline
pack:check — preview npm package contents and size

The npm package intentionally ships the CLI, extension source, exported tool catalog, skill/docs surfaces, and the built XPI artifact — but excludes repo-only materials that are not required for installation or agent use.

Connection discovery

The shared transport re-discovers connection.json on cache misses. Search order:

THUNDERBIRD_AGENT_CONNECTION_FILE
native temp dir: <os.tmpdir()>/thunderbird-agent/connection.json
macOS temp fallback under /var/folders/*/*/T/thunderbird-agent/connection.json
Thunderbird Snap TMPDIR plus the official snap fallback path
Flatpak / Betterbird runtime paths under $XDG_RUNTIME_DIR/app/*/thunderbird-agent/connection.json

Useful overrides:

export THUNDERBIRD_AGENT_CONNECTION_FILE=/absolute/path/to/connection.json
export THUNDERBIRD_AGENT_CLI=/absolute/path/to/thunderbird-agent/packages/cli/thunderbird-agent.cjs

Security model

localhost only — no remote listener
session-scoped bearer token — written to a local connection file with restrictive permissions
review-first compose flows — mail can open in Thunderbird before send
user-controlled account access — mailbox visibility is configurable in extension settings
user-controlled tool access — individual tools can be disabled in extension settings

If you are using an AI agent to send or modify mail, keep skipReview: false unless the user explicitly asked for silent send behavior.

Troubleshooting

Problem	What to check
`doctor` says connection file not found	Thunderbird is running; extension is enabled; connection override path is correct
CLI can list catalog but not live tools	Thunderbird is not running yet, or the extension failed to start
Compose actions fail with `skipReview`	The user may have enabled the extension-side safety block
IMAP state looks stale	Open the folder in Thunderbird or repair/sync it before retrying
Build output missing	Run `npm run build` and confirm `dist/thunderbird-agent.xpi` exists

Documentation map

README.zh-CN.md — Simplified Chinese overview and quick start
docs/README.md — documentation overview
docs/agents/README.md — agent integration overview
docs/agents/claude-code.md — Claude Code workflow notes
docs/agents/codex.md — Codex workflow notes
docs/agents/openclaw.md — OpenClaw workflow notes
docs/filter-api-research.md — archived filter implementation notes

Development checklist

npm test
npm run build
npm run pack:check

If you change tool metadata in extension/agent_server/api.js, always refresh shared/tool-catalog.json before committing.

Repository layout

thunderbird-agent/
├── AGENTS.md
├── CLAUDE.md
├── README.md
├── README.zh-CN.md
├── dist/
│   └── thunderbird-agent.xpi
├── docs/
│   ├── README.md
│   ├── agents/
│   └── filter-api-research.md
├── extension/
│   ├── agent_server/
│   ├── manifest.json
│   └── options.*
├── packages/
│   ├── cli/
│   └── core/
├── scripts/
├── shared/
├── skills/
│   └── thunderbird-agent/
└── test/

Navigation Menu

Repository navigation

About

Repository files navigation

Thunderbird Agent

Project origin

Why this project exists

Quick start

1. Clone the repository

2. Build the extension artifact

3. Install the extension in Thunderbird

4. Verify the CLI can see Thunderbird

5. Call tools directly

Tool surface

Mail

Compose

Filters

Contacts

Calendar and tasks

Access control visibility

CLI reference

Agent integration surfaces

Build and packaging

Canonical build commands

Connection discovery

Security model

Troubleshooting

Documentation map

Development checklist

Repository layout

About

Releases

Packages

Contributors

Languages

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
dist		dist
docs		docs
extension		extension
packages		packages
scripts		scripts
shared		shared
skills		skills
test		test
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
README.md		README.md
README.zh-CN.md		README.zh-CN.md
package.json		package.json

Latest commit

History

Folders and files

Repository files navigation

Thunderbird Agent

Project origin

Why this project exists

Quick start

1. Clone the repository

2. Build the extension artifact

3. Install the extension in Thunderbird

4. Verify the CLI can see Thunderbird

5. Call tools directly

Tool surface

Mail

Compose

Filters

Contacts

Calendar and tasks

Access control visibility

CLI reference

Agent integration surfaces

Build and packaging

Canonical build commands

Connection discovery

Security model

Troubleshooting

Documentation map

Development checklist

Repository layout

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages