Outlook for Claude Code

Your Microsoft 365 mail, calendar and archives in the terminal - driven by Claude Code or Codex

A free, open-source tool by DBHQ

Read your inbox, draft and send properly formatted replies and forwards, triage with flags and categories, manage attachments up to 150 MB, and run your calendar - including responding to invites and inviting attendees - all from Claude Code or Codex, in plain language. Multi-account, OAuth-based, and built with the safety rails that matter for real correspondence.

Two skills ship in this pack:

Skill	What it does	Needs
`outlook-graph`	Live Microsoft 365 mail and calendar via the Graph API	OAuth, network
`outlook-to-md`	Turns PST exports and live mail into integrity-verified markdown, offline	Nothing but a file

They cover the two halves of the same problem: the mail you are handling now, and the mail you were handed in a box - and they join up, so one archive spans both. outlook-to-md itself needs no credentials and makes no network calls; it reads files on disk, whether they came out of a PST or out of outlook-graph.

Why it is different

Reply-all by default. Replies preserve every original To: and Cc: recipient, so you never silently drop someone from a thread. Trim to sender-only when you actually mean to. Losing a recipient by accident is invisible from your side; sending to one person too many is not.

Reads the whole message, never the preview. The skill is instructed to open the full body end-to-end before summarising or replying, so deadlines, attachments and requests buried below the fold are not missed.

Nothing leaves without a second command. Drafting and sending are different verbs, and so are creating an event and inviting anyone to it. An agent driving a mailbox is one confident inference away from mailing a client; the gap is where a person gets to look.

Time-aware. It anchors "today", "tomorrow" and "by EOD" against the real clock and tracks BST against UTC, so scheduled sends and deadline arithmetic are correct. Calendar times are wall-clock in a timezone it tells you about rather than assumes.

Professional formatting. Markdown drafts convert to clean HTML with the Microsoft 365 Aptos font stack and inline styles - including per-paragraph margins - that survive Outlook's rendering.

It asks for five permissions and no more. Mail.ReadWrite, Mail.Send, Calendars.ReadWrite, User.Read, offline_access, all delegated. Nothing tenant-wide, nothing that can reach another mailbox, and no admin consent to obtain.

What it covers

outlook-graph-mail.sh      inbox · unread · focused · sent · drafts · flagged · folder · from
                           search · thread · read · preview · export
                           draft · mddraft · reply · mdreply · forward · followup
                           update · send · aliases
                           attachments · download · attach
                           markread · flag · categorize · categories · junk · archive · delete
                           move · batch-move · mkdir · rename · rmdir · folders · stats

outlook-graph-calendar.sh  events · today · week · day · search · read · calendars
                           create · invite · quick · update · respond · cancel · delete · free

outlook-graph-token.sh     refresh · get · test · status · list

outlook_to_md.py           <pst-or-eml-dir> <output-dir> [--append --timezone --owner-email …]

You normally type none of this - you ask, and the skill picks the command. Every argument, flag and default is in docs/reference.md.

Install

As a Claude Code plugin (recommended)

/plugin marketplace add dbhq-uk/marketplace
/plugin install outlook-graph@dbhq

Then run the one-time setup the skill points you to, and talk to it in plain language: "check my email", "draft a reply to the last message from Sam", "am I free Thursday afternoon".

Any agent (Cursor, Copilot, Windsurf, Gemini, Cline and more)

npx skills add dbhq-uk/outlook-graph-skill

The skills.sh CLI installs into whichever agent directories it finds, so this works outside Claude Code and Codex too. Both skills come in one command.

Local install (Claude Code or Codex)

git clone https://github.com/dbhq-uk/outlook-graph-skill.git
cd outlook-graph-skill
./install.sh          # Claude Code: symlinks into ~/.claude/skills (edits are live)
./install-codex.sh    # Codex: installs into ~/.codex/skills

First run launches outlook-graph-setup.sh, which registers an Azure app and signs you in. Credentials are stored per account under ~/.outlook-graph/<account>/, never leave your machine, and refresh themselves. The whole install-to-first-email path is docs/getting-started.md.

Requirements

Checked per skill - a missing dependency skips that skill rather than failing the install, so you can take either half on its own.

Skill	Required	Optional
`outlook-graph`	`azure-cli` · `jq` · `curl`	`pandoc` (markdown-formatted emails)
`outlook-to-md`	`python3` (3.9+)	`readpst` (`pst-utils`; fallback PST backend)

outlook-to-md provisions its own virtualenv on install. Its preferred PST backend pins an old numpy and cannot install on Python 3.12 or later, so setup.sh picks a 3.9-3.11 interpreter when one exists and otherwise builds without it and says so - see the Python version problem.

Documentation

The documentation index reaches everything. Start with getting started to set it up, handling a thread and running the calendar to use it, the reference to look a command up, and how the pack is built to understand why it behaves the way it does. There are also guides for markdown archives and accounts and tokens.

Hacking on it, or running from source with live edits: docs/dev-setup.md, CONTRIBUTING.md, and AGENTS.md if you are an AI agent doing so.

Credentials and privacy

No secrets live in this repository. Your tokens are stored locally under ~/.outlook-graph/ and used only to talk to Microsoft Graph directly from your machine.

Outlook Graph Skill

At a glance

README