Agent Teams

A TypeScript CLI tool that enables AI agents and humans to interact with Microsoft Teams through a simple command interface. Features seamless token extraction from the Teams desktop app and multi-team support.

Quick Start

CODEBLOCK0

Authentication

Credentials are extracted automatically from the Teams desktop app on first use. No manual setup required — just run any command and authentication happens silently in the background.

Teams tokens expire in 60-90 minutes. The CLI automatically re-extracts a fresh token when the current one expires, so you don't need to manage token lifecycle manually.

IMPORTANT: NEVER guide the user to open a web browser, use DevTools, or manually copy tokens from a browser. Always use agent-teams auth extract to obtain tokens from the desktop app.

Multi-Team Support

CODEBLOCK1

Multi-Account Support (Work / Personal)

CODEBLOCK2

Memory

The agent maintains a ~/.config/agent-messenger/MEMORY.md file as persistent memory across sessions. This is agent-managed — the CLI does not read or write this file. Use the Read and Write tools to manage your memory file.

Reading Memory

At the start of every task, read ~/.config/agent-messenger/MEMORY.md using the Read tool to load any previously discovered team IDs, channel IDs, user IDs, and preferences.

• - If the file doesn't exist yet, that's fine — proceed without it and create it when you first have useful information to store.
• If the file can't be read (permissions, missing directory), proceed without memory — don't error out.

Writing Memory

After discovering useful information, update ~/.config/agent-messenger/MEMORY.md using the Write tool. Write triggers include:

• - After discovering team IDs and names (from team list, snapshot, etc.)
• After discovering useful channel IDs and names (from channel list, snapshot, etc.)
• After discovering user IDs and names (from user list, user me, etc.)
• After the user gives you an alias or preference ("call this the standup channel", "my main team is X")
• After discovering channel structure (standard vs private channels)

When writing, include the complete file content — the Write tool overwrites the entire file.

What to Store

• - Team IDs with names
• Channel IDs with names and team context
• User IDs with display names
• User-given aliases ("standup channel", "main team")
• Account preferences (work vs personal)
• Any user preference expressed during interaction

What NOT to Store

Never store tokens, credentials, or any sensitive data. Never store full message content (just IDs and channel context). Never store file upload contents.

Handling Stale Data

If a memorized ID returns an error (channel not found, team not found), remove it from MEMORY.md. Don't blindly trust memorized data — verify when something seems off. Prefer re-listing over using a memorized ID that might be stale.

Format / Example

CODEBLOCK3

Memory lets you skip repeated channel list and team list calls. When you already know an ID from a previous session, use it directly.

Commands

Auth Commands

CODEBLOCK4

Message Commands

CODEBLOCK5

Channel Commands

CODEBLOCK6

Team Commands

CODEBLOCK7

User Commands

CODEBLOCK8

Reaction Commands

CODEBLOCK9

File Commands

CODEBLOCK10

Snapshot Command

Get comprehensive team state for AI agents:

CODEBLOCK11

Returns JSON with:

• - Team metadata (id, name)
• Channels (id, name, type, description)
• Recent messages (id, content, author, timestamp)
• Members (id, displayName, email)

Output Format

JSON (Default)

All commands output JSON by default for AI consumption:

CODEBLOCK12

Pretty (Human-Readable)

Use --pretty flag for formatted output:

CODEBLOCK13

Key Differences from Discord/Slack

Important: Teams uses UUID-style channel IDs (like 19:abc123@thread.tacv2). You cannot use channel names directly - use channel list to find IDs first.

Common Patterns

See references/common-patterns.md for typical AI agent workflows.

Templates

See templates/ directory for runnable examples:

• - post-message.sh - Send messages with error handling
• INLINECODE27 - Monitor channel for new messages (with token refresh)
• INLINECODE28 - Generate team summary

Error Handling

All commands return consistent error format:

CODEBLOCK14

Common errors:

• - Not authenticated: No valid token (auto-extraction failed — see Troubleshooting)
• INLINECODE30: Token has expired and auto-refresh failed — see Troubleshooting
• INLINECODE31: Run team switch <id> first
• INLINECODE33: Invalid message ID
• INLINECODE34: Invalid channel ID
• INLINECODE35: Token expired and auto-refresh failed — see Troubleshooting

Configuration

Credentials stored in: INLINECODE36

Format:
CODEBLOCK15

Security: File permissions set to 0600 (owner read/write only)

Limitations

• - No real-time events / WebSocket connection
• No voice/video channel support
• No team management (create/delete channels, roles)
• No meeting support
• No webhook support
• Plain text messages only (no adaptive cards in v1)
• User tokens only (no app tokens)
• Token expires in 60-90 minutes - auto-refreshed, but requires Teams desktop app to be logged in

Troubleshooting

Authentication fails or token expired

Credentials and token refresh are normally handled automatically. If auto-extraction fails, run it manually with debug output:

CODEBLOCK16

Common causes:

• - Teams desktop app is not installed or not logged in
• Teams Cookies database is locked or inaccessible
• Token expired and Teams desktop app session also expired (re-login to Teams)

agent-teams: command not found

agent-teams is NOT the npm package name. The npm package is agent-messenger.

If the package is installed globally, use agent-teams directly:

CODEBLOCK17

If the package is NOT installed, use bunx agent-messenger teams:

CODEBLOCK18

NEVER run bunx agent-teams — it will fail or install a wrong package since agent-teams is not the npm package name.

References

• - Authentication Guide
• Common Patterns