Your autonomous AI work agent for Microsoft 365.
62 tools. 10 services. 4 permission levels. One agent that respects your security boundaries.
Quick Start • Features • Tool Profiles • Architecture • Contributing
OpenClippy connects to your Microsoft 365 account via the Graph API and manages your email, calendar, tasks, Teams, files, and more through natural language. Ask it to triage your inbox, schedule meetings, create tasks from emails, search across your OneDrive — all from the terminal.
openclippy ask "What are my unread emails from my manager this week?"
openclippy ask "Schedule a 30-minute meeting with the design team next Tuesday at 2pm"
openclippy ask "Find all files in OneDrive related to the Q1 budget"AI agents that manage your Microsoft 365 are powerful — but they need guardrails. OpenClippy was built with a few principles that set it apart:
- Focused scope. 10 M365 services with 62 well-defined tools. Not an everything-agent — a purpose-built M365 agent.
- Granular permissions. 4 tool profiles from
read-only(can't change anything) toadmin(org-wide ops). You decide what the agent can do. - No stored Microsoft secrets. Device code auth via MSAL — your Microsoft credentials stay with Microsoft, not in a config file. (The Anthropic API key for the agent lives in your config or environment.)
- Auditable codebase. TypeScript (strict mode), clean module boundaries, MIT licensed. Read every line if you want.
- Extensible. Plugin system for custom service integrations. Drop an ESM module in
~/.openclippy/plugins/and go.
# Install and build
pnpm install
pnpm build
npm link # makes the `openclippy` command available globally
# Run the setup wizard (Azure app, services, tool profile, API key)
openclippy config --setup
# Or configure by hand:
mkdir -p ~/.openclippy
cat > ~/.openclippy/config.yaml << 'EOF'
azure:
clientId: "your-application-client-id"
tenantId: "common"
EOF
# The agent (`ask` / `chat`) needs an Anthropic API key.
# Set it in the wizard, in config (agent.apiKey), or via the environment:
export ANTHROPIC_API_KEY="sk-ant-..."
# Authenticate with Microsoft (device code flow)
openclippy login
# Ask a question
openclippy ask "What are my unread emails?"
# Or start an interactive chat
openclippy chatSee docs/setup.md for the full Azure AD app registration walkthrough.
Tip: OpenClippy also loads a
.envfile from the current directory at startup, so you can keepANTHROPIC_API_KEYthere instead of exporting it. Shell-exported variables take precedence over.env.
OpenClippy provides 62 tools across 10 Microsoft 365 services:
| Service | What It Does |
|---|---|
| Outlook Mail | List, read, search, send, reply, forward, flag, move, delete emails |
| Outlook Calendar | View, create, update, delete events; accept/decline invites; check free/busy |
| To Do | Manage task lists; create, update, complete, delete tasks |
| Teams Chat | Read and send messages in chats and channels |
| OneDrive | Browse, read, search, upload, delete, and share files |
| People & Contacts | Search for relevant people and browse Outlook contacts |
| Presence | Read Teams availability; set and clear presence overrides |
| Planner | View plans, tasks, and buckets; create and update Planner tasks |
| OneNote | Browse notebooks and sections; read and create pages |
| SharePoint | Search sites; browse lists, items, and document libraries |
Enable only what you need — OpenClippy requests Graph API scopes only for enabled services.
This is the core of OpenClippy's security model. Tool profiles control which operations the agent can perform, so you're never wondering what it might do:
| Profile | Allowed Operations | Use Case |
|---|---|---|
| read-only | List, read, search, free/busy — nothing that changes data | Safe browsing — no changes to your data |
| standard | Everything except delete (create, update, send, reply, upload, share, ...) | Day-to-day work (default) |
| full | All operations, including delete | Full autonomy including destructive operations |
| admin | Same as full today; reserved for future org-wide operations | IT admin scenarios |
Set your comfort level in config:
agent:
toolProfile: "standard" # read-only | standard | full | adminStart with read-only to explore safely. Move to standard when you're comfortable. You're always in control.
OpenClippy reads its configuration from ~/.openclippy/config.yaml:
azure:
clientId: "your-application-client-id"
tenantId: "common"
services:
mail: { enabled: true }
calendar: { enabled: true }
todo: { enabled: true }
teams-chat: { enabled: true }
onedrive: { enabled: true }
planner: { enabled: false }
onenote: { enabled: false }
sharepoint: { enabled: false }
people: { enabled: true }
presence: { enabled: true }
agent:
model: "claude-sonnet-5"
toolProfile: "standard"
apiKey: "sk-ant-..." # or set the ANTHROPIC_API_KEY environment variable
identity:
name: "Clippy"| Command | Description |
|---|---|
openclippy login |
Authenticate with your Microsoft account (device code flow) |
openclippy ask "..." |
One-shot query to the agent |
openclippy chat |
Interactive terminal chat session |
openclippy status |
Check auth and service status |
openclippy services |
List services and their scopes |
openclippy config |
Show current configuration (API keys redacted) |
openclippy config --setup |
Run the interactive setup wizard |
openclippy gateway start |
Start the long-running gateway daemon |
openclippy gateway stop |
Stop the gateway |
openclippy gateway status |
Check gateway status |
Extend OpenClippy with custom service integrations. Plugins are ESM modules loaded from ~/.openclippy/plugins/ and configured via your config.yaml:
plugins:
my-service:
enabled: trueSee the Plugin Authoring Guide for the full reference, or check out the example plugin.
CLI (ask/chat/TUI) Gateway daemon (optional)
| WebSocket + HTTP clients
+--------+----------+
|
Agent Runtime (Claude LLM + tool dispatch)
|
Service Modules (Mail, Calendar, ToDo, ...)
|
Graph API Client (typed fetch, pagination, rate-limit aware)
|
Microsoft Graph API
- Auth: MSAL device code flow (public client, no client secret; tokens cached in
~/.openclippy/) - Graph client: Custom fetch-based client — lean and typed, not the heavy
@microsoft/microsoft-graph-client - CLI:
askandchatrun the agent in-process — no daemon required - Gateway: Optional long-running daemon exposing the same agent over WebSocket (
/ws) and HTTP (POST /api/ask,GET /health,POST /webhooks/graph) - Subscriptions: A Graph change-notification subscription manager (mail, calendar, todo) handles create/renew/delete lifecycle; routing incoming notifications to service modules is still being wired up
- Service modules: Each M365 service implements a clean
ServiceModuleinterface — capabilities, tools, optional health probes, optional subscriptions
- TypeScript (strict, ESM), Node.js 22+
- pnpm package manager
- @azure/msal-node for authentication
- @anthropic-ai/sdk for agent LLM (Claude)
- Commander.js for CLI
- better-sqlite3 for memory and sessions
- ws for WebSocket gateway
- vitest for testing, tsdown for building
- Azure AD Setup Guide — Register your app and configure permissions
- Service Reference — All 10 services with capabilities, scopes, and tools
- Tool Reference — Detailed reference for all 62 tools with parameters
- Plugin Authoring Guide — Build custom service integrations
OpenClippy is early-stage and contributions are welcome! Here are some ways to get involved:
- Try it out and open an issue with bugs or feedback
- Add a service — the
ServiceModuleinterface makes it straightforward to add new Graph API integrations - Write tests — more coverage is always appreciated
- Improve docs — especially setup guides and real-world usage examples
- Build a plugin — and share it with the community
Check out the issues labeled good first issue for entry points.
- Node.js >= 22.12.0
- A Microsoft 365 account (work/school or personal)
- An Azure AD app registration (setup guide)
- An Anthropic API key for the agent (
ask/chat) — console.anthropic.com
pnpm install # Install dependencies
pnpm build # Build with tsdown
pnpm test # Run tests with vitest
pnpm dev # Run in dev mode with tsx
pnpm lint # Lint with oxlint
pnpm typecheck # Type-check with tscYes, it's a Clippy reference. No, it won't ask if you need help writing a letter. (Unless you ask it to.)
MIT