agent-messenger 1.0.0

package/.claude/commands/release.md

@@ -0,0 +1,92 @@
+# Release Command
+
+Bump version and create a new release.
+
+## Arguments
+
+- `$ARGUMENTS` - The new version number (e.g., `1.2.3`)
+
+## Version Files to Update
+
+Update the version in these files:
+
+1. **package.json** (line 3) - `"version": "X.X.X"`
+2. **.claude-plugin/plugin.json** (line 3) - `"version": "X.X.X"`
+3. **README.md** - OpenCode plugins example: `"agent-messenger@X.X.X"`
+
+Note: CLI files and tests read version from package.json automatically.
+
+## Release Steps
+
+### Step 1: Validate Version Argument
+
+Ensure `$ARGUMENTS` is provided and is a valid semver version (e.g., `1.2.3`).
+If not provided, ask the user for the version number.
+
+### Step 2: Update Version in All Files
+
+Update the version string in each file listed above. Use the Edit tool for precise updates.
+
+### Step 3: Build
+
+Run the build command:
+```bash
+bun run build
+```
+
+Ensure the build succeeds before proceeding.
+
+### Step 4: Run Tests
+
+Run the test suite to ensure nothing is broken:
+```bash
+bun test
+```
+
+Ensure all tests pass before proceeding.
+
+### Step 5: Create Commit
+
+Stage and commit all changes including:
+- Version file changes
+- Build output (dist/)
+
+Commit message format:
+```
+Bump version to $ARGUMENTS
+```
+
+### Step 6: Create Tag and Push
+
+Create a git tag **without** the `v` prefix:
+```bash
+git tag $ARGUMENTS
+git push origin main
+git push origin $ARGUMENTS
+```
+
+### Step 7: Create GitHub Release
+
+Create a GitHub release using `gh release create`:
+- Tag: `$ARGUMENTS` (no `v` prefix)
+- Title: `$ARGUMENTS` (no `v` prefix)
+- Generate release notes automatically
+
+```bash
+gh release create $ARGUMENTS --title "$ARGUMENTS" --generate-notes
+```
+
+### Step 8: Publish to npm
+
+Publish the package to npm registry:
+```bash
+npm publish
+```
+
+Note: The `prepublishOnly` script in package.json will run `bun run build` automatically, but since we already built in Step 3, this is redundant but harmless.
+
+## Important Notes
+
+- **No `v` prefix**: Tags and release titles must NOT include the `v` prefix (use `1.2.3` not `v1.2.3`)
+- **Build artifacts**: The commit must include the build output in `dist/`
+- **Test validation**: Tests must pass before release

package/.claude-plugin/README.md

@@ -0,0 +1,144 @@
+# Agent Messenger - Claude Code Plugin
+
+Messaging platform interaction skills for AI agents and Claude Code. Supports Slack workspaces and Discord servers.
+
+## Installation
+
+```bash
+# Add the marketplace
+claude plugin marketplace add devxoul/agent-messenger
+
+# Install the plugin
+claude plugin install agent-messenger
+```
+
+Or within Claude Code:
+
+```
+/plugin marketplace add devxoul/agent-messenger
+/plugin install agent-messenger
+```
+
+## What it does
+
+Enables AI agents to interact with messaging platforms through CLI interfaces:
+
+### Slack (`agent-slack`)
+- **Send messages** to channels and threads
+- **Read channels** and message history
+- **Manage reactions** (add/remove/list)
+- **Upload files** to channels
+- **Search messages** across workspace
+- **Multi-workspace support** with easy switching
+
+### Discord (`agent-discord`)
+- **Send messages** to channels
+- **Read channels** and message history
+- **Manage reactions** (add/remove/list)
+- **Upload files** to channels
+- **Multi-guild support** with easy switching
+
+## Key Features
+
+### Zero-Config Authentication
+
+Automatically extracts credentials from desktop apps - no manual token copying needed:
+
+```bash
+# Slack
+agent-slack auth extract
+
+# Discord
+agent-discord auth extract
+```
+
+### AI-Friendly References (Slack)
+
+Uses session-scoped references for entities:
+- Channels: `@c1`, `@c2`, `@c3`, ...
+- Messages: `@m1`, `@m2`, `@m3`, ...
+- Users: `@u1`, `@u2`, `@u3`, ...
+- Files: `@f1`, `@f2`, `@f3`, ...
+
+### JSON Output
+
+All commands output JSON by default for easy AI consumption. Use `--pretty` for human-readable output.
+
+## Requirements
+
+- Slack desktop app and/or Discord desktop app installed and logged in
+- Node.js 18+ or Bun runtime
+
+## Quick Start
+
+### Slack
+
+```bash
+# 1. Extract credentials from Slack desktop app
+agent-slack auth extract
+
+# 2. Get workspace snapshot with refs
+agent-slack snapshot
+
+# 3. Send a message
+agent-slack message send general "Hello from AI agent!"
+
+# 4. Use refs for AI-friendly interaction
+agent-slack message send @c1 "Message to first channel"
+```
+
+### Discord
+
+```bash
+# 1. Extract credentials from Discord desktop app
+agent-discord auth extract
+
+# 2. Get guild snapshot
+agent-discord snapshot
+
+# 3. Send a message (use channel ID)
+agent-discord message send <channel-id> "Hello from AI agent!"
+```
+
+## Example Usage
+
+### Slack
+
+```bash
+# List channels
+agent-slack channel list
+
+# Read recent messages
+agent-slack message list general --limit 20
+
+# Search messages
+agent-slack message search "project update"
+
+# Add reaction to a message
+agent-slack reaction add @c1 @m5 thumbsup
+
+# Upload a file
+agent-slack file upload general ./report.pdf
+```
+
+### Discord
+
+```bash
+# List channels
+agent-discord channel list
+
+# Read recent messages
+agent-discord message list <channel-id> --limit 20
+
+# Add reaction to a message
+agent-discord reaction add <channel-id> <message-id> thumbsup
+
+# Upload a file
+agent-discord file upload <channel-id> ./report.pdf
+```
+
+## More Information
+
+- [GitHub Repository](https://github.com/devxoul/agent-messenger)
+- [Slack Skill Documentation](https://github.com/devxoul/agent-messenger/blob/main/skills/agent-slack/SKILL.md)
+- [Discord Skill Documentation](https://github.com/devxoul/agent-messenger/blob/main/skills/agent-discord/SKILL.md)

package/.claude-plugin/marketplace.json

@@ -0,0 +1,37 @@
+{
+  "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
+  "name": "agent-messenger",
+  "description": "Messaging platform interaction skills for AI agents - Slack workspaces and Discord servers",
+  "owner": {
+    "name": "devxoul",
+    "url": "https://github.com/devxoul"
+  },
+  "plugins": [
+    {
+      "name": "agent-slack",
+      "description": "Interact with Slack workspaces through a CLI interface. Features seamless token extraction from Slack desktop app, multi-workspace support, AI-friendly entity references (@c1, @m1, @u1), message operations, channel management, reactions, and file uploads.",
+      "version": "0.1.0",
+      "author": {
+        "name": "devxoul",
+        "url": "https://github.com/devxoul"
+      },
+      "source": "./",
+      "category": "productivity",
+      "homepage": "https://github.com/devxoul/agent-messenger",
+      "keywords": ["slack", "messaging", "workspace", "ai-agent", "cli", "communication"]
+    },
+    {
+      "name": "agent-discord",
+      "description": "Interact with Discord servers through a CLI interface. Features seamless token extraction from Discord desktop app, multi-guild support, message operations, channel management, reactions, and file uploads.",
+      "version": "0.1.0",
+      "author": {
+        "name": "devxoul",
+        "url": "https://github.com/devxoul"
+      },
+      "source": "./",
+      "category": "productivity",
+      "homepage": "https://github.com/devxoul/agent-messenger",
+      "keywords": ["discord", "messaging", "guild", "server", "ai-agent", "cli", "communication"]
+    }
+  ]
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,17 @@
+{
+  "name": "agent-messenger",
+  "version": "1.0.0",
+  "description": "Messaging platform interaction skills for AI agents. Interact with Slack workspaces and Discord servers - send messages, read channels, manage reactions, upload files, and more through simple CLI interfaces.",
+  "author": {
+    "name": "devxoul",
+    "url": "https://github.com/devxoul"
+  },
+  "license": "MIT",
+  "keywords": ["slack", "discord", "messaging", "workspace", "guild", "ai-agent", "cli", "communication", "productivity"],
+  "homepage": "https://github.com/devxoul/agent-messenger",
+  "repository": "https://github.com/devxoul/agent-messenger",
+  "skills": [
+    "./skills/agent-slack",
+    "./skills/agent-discord"
+  ]
+}

package/.github/workflows/ci.yml

@@ -0,0 +1,30 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  ci:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Lint
+        run: bun run lint
+
+      - name: Test
+        run: bun test
+
+      - name: Build
+        run: bun run build

package/CLAUDE.md

@@ -0,0 +1,106 @@
+
+Default to using Bun instead of Node.js.
+
+- Use `bun <file>` instead of `node <file>` or `ts-node <file>`
+- Use `bun test` instead of `jest` or `vitest`
+- Use `bun build <file.html|file.ts|file.css>` instead of `webpack` or `esbuild`
+- Use `bun install` instead of `npm install` or `yarn install` or `pnpm install`
+- Use `bun run <script>` instead of `npm run <script>` or `yarn run <script>` or `pnpm run <script>`
+- Use `bunx <package> <command>` instead of `npx <package> <command>`
+- Bun automatically loads .env, so don't use dotenv.
+
+## APIs
+
+- `Bun.serve()` supports WebSockets, HTTPS, and routes. Don't use `express`.
+- `bun:sqlite` for SQLite. Don't use `better-sqlite3`.
+- `Bun.redis` for Redis. Don't use `ioredis`.
+- `Bun.sql` for Postgres. Don't use `pg` or `postgres.js`.
+- `WebSocket` is built-in. Don't use `ws`.
+- Prefer `Bun.file` over `node:fs`'s readFile/writeFile
+- Bun.$`ls` instead of execa.
+
+## Testing
+
+Use `bun test` to run tests.
+
+```ts#index.test.ts
+import { test, expect } from "bun:test";
+
+test("hello world", () => {
+  expect(1).toBe(1);
+});
+```
+
+## Frontend
+
+Use HTML imports with `Bun.serve()`. Don't use `vite`. HTML imports fully support React, CSS, Tailwind.
+
+Server:
+
+```ts#index.ts
+import index from "./index.html"
+
+Bun.serve({
+  routes: {
+    "/": index,
+    "/api/users/:id": {
+      GET: (req) => {
+        return new Response(JSON.stringify({ id: req.params.id }));
+      },
+    },
+  },
+  // optional websocket support
+  websocket: {
+    open: (ws) => {
+      ws.send("Hello, world!");
+    },
+    message: (ws, message) => {
+      ws.send(message);
+    },
+    close: (ws) => {
+      // handle close
+    }
+  },
+  development: {
+    hmr: true,
+    console: true,
+  }
+})
+```
+
+HTML files can import .tsx, .jsx or .js files directly and Bun's bundler will transpile & bundle automatically. `<link>` tags can point to stylesheets and Bun's CSS bundler will bundle.
+
+```html#index.html
+<html>
+  <body>
+    <h1>Hello, world!</h1>
+    <script type="module" src="./frontend.tsx"></script>
+  </body>
+</html>
+```
+
+With the following `frontend.tsx`:
+
+```tsx#frontend.tsx
+import React from "react";
+import { createRoot } from "react-dom/client";
+
+// import .css files directly and it works
+import './index.css';
+
+const root = createRoot(document.body);
+
+export default function Frontend() {
+  return <h1>Hello, world!</h1>;
+}
+
+root.render(<Frontend />);
+```
+
+Then, run index.ts
+
+```sh
+bun --hot ./index.ts
+```
+
+For more information, read the Bun API docs in `node_modules/bun-types/docs/**.mdx`.

package/CONTRIBUTING.md

@@ -0,0 +1,131 @@
+# Contributing to Agent Messenger
+
+## Development Setup
+
+```bash
+# Clone the repository
+git clone https://github.com/devxoul/agent-messenger.git
+cd agent-messenger
+
+# Install dependencies
+bun install
+
+# Link CLI globally for local testing
+bun link
+
+# Run tests
+bun test
+
+# Build
+bun run build
+```
+
+## Running Tests
+
+We follow TDD (Test-Driven Development). Tests are co-located with source files.
+
+```bash
+# Run all tests
+bun test
+
+# Run specific test file
+bun test src/platforms/slack/commands/message.test.ts
+
+# Watch mode
+bun test --watch
+```
+
+## Code Quality
+
+We use Biome for linting and formatting, and TypeScript for type checking:
+
+```bash
+# Type check
+bun run typecheck
+
+# Lint
+bun run lint
+
+# Auto-fix lint issues
+bun run lint --write
+
+# Format code
+bun run format
+```
+
+## Commit Conventions
+
+Follow conventional commits:
+
+- `feat(scope): description` - New features
+- `fix(scope): description` - Bug fixes
+- `docs: description` - Documentation changes
+- `test(scope): description` - Test changes
+- `chore: description` - Build/tooling changes
+- `refactor(scope): description` - Code refactoring
+
+Examples:
+```
+feat(slack): add message send command
+feat(discord): add guild switching
+fix(auth): handle missing credentials gracefully
+docs: update README with new examples
+test(channel): add channel list tests
+```
+
+## Pull Request Process
+
+1. Create a feature branch from `main`
+2. Write tests first (TDD)
+3. Implement the feature
+4. Ensure all tests pass: `bun test`
+5. Ensure types are correct: `bun run typecheck`
+6. Fix any lint issues: `bun run lint --write`
+7. Submit PR with clear description
+
+## Project Structure
+
+```
+src/
+  cli.ts                    # Main CLI entry point
+  platforms/
+    slack/                  # Slack platform
+      cli.ts                # Slack CLI entry
+      client.ts             # Slack API client
+      credential-manager.ts # Credential storage
+      token-extractor.ts    # Auto credential extraction
+      types.ts              # TypeScript types
+      commands/             # Command handlers
+        auth.ts
+        channel.ts
+        message.ts
+        ...
+    discord/                # Discord platform
+      cli.ts                # Discord CLI entry
+      client.ts             # Discord API client
+      credential-manager.ts # Credential storage
+      token-extractor.ts    # Auto credential extraction
+      types.ts              # TypeScript types
+      commands/             # Command handlers
+        auth.ts
+        channel.ts
+        guild.ts
+        message.ts
+        ...
+  shared/
+    utils/                  # Shared utilities
+```
+
+Tests are co-located with source files (e.g., `client.test.ts` next to `client.ts`).
+
+## Testing Guidelines
+
+- Write tests FIRST (TDD)
+- Mock platform clients (SlackClient, DiscordClient) in command tests
+- Use descriptive test names
+- Tests are co-located: `foo.ts` -> `foo.test.ts`
+- Aim for high coverage
+
+## Questions?
+
+Open an issue or start a discussion!

package/README.md

@@ -0,0 +1,140 @@
+# 💬 Agent Messenger
+
+**Give your AI agent the power to read and send messages across Slack, Discord, Teams and more**
+
+A unified, agent-friendly CLI for messaging platforms. Zero-config credential extraction from your desktop apps—no OAuth flows, no API keys, no admin approval needed. Works out of the box.
+
+## ✨ Why Agent Messenger?
+
+- 🔑 **No API keys needed** — Automatically extracts credentials from your installed desktop apps
+- 🌐 **One interface, multiple platforms** — Learn once, use everywhere (Slack, Discord, Teams)
+- 🤖 **AI-agent friendly** — JSON output by default, perfect for LLM tool use
+- 👤 **Human friendly too** — Add `--pretty` for readable output
+
+## 📦 Installation
+
+```bash
+npm install -g agent-messenger
+```
+
+Or use your favorite package manager.
+
+This installs:
+- `agent-slack` — Slack CLI
+- `agent-discord` — Discord CLI
+
+## 🧩 Agent Skills
+
+Agent Messenger includes [Agent Skills](https://agentskills.io/) that teach your AI agent how to use these CLIs effectively.
+
+### Skills CLI
+
+```bash
+npx skills add devxoul/agent-messenger
+```
+
+See [skills.sh](https://skills.sh/) for more details.
+
+### Claude Code
+
+```bash
+claude plugin marketplace add devxoul/agent-messenger
+claude plugin install agent-messenger
+```
+
+Or within Claude Code:
+
+```
+/plugin marketplace add devxoul/agent-messenger
+/plugin install agent-messenger
+```
+
+### OpenCode
+
+Add to your `opencode.jsonc`:
+
+```jsonc
+{
+  "plugins": [
+    "agent-messenger@1.0.0"
+  ]
+}
+```
+
+## 🚀 Quick Start
+
+Get up and running in 30 seconds:
+
+```bash
+# 1. Extract credentials from your Slack desktop app
+agent-slack auth extract
+
+# 2. See your workspace at a glance
+agent-slack snapshot --pretty
+
+# 3. Send a message
+agent-slack message send general "Hello from the CLI!"
+```
+
+That's it. No OAuth flows. No API tokens. No configuration files.
+
+## 🔌 Supported Platforms
+
+| Feature | Slack | Discord |
+|---------|:-----:|:-------:|
+| Auto credential extraction | ✅ | ✅ |
+| Send / List / Search messages | ✅ | ✅ |
+| Threads | ✅ | ✅ |
+| Channels & Users | ✅ | ✅ |
+| Reactions | ✅ | ✅ |
+| File uploads | ✅ | ✅ |
+| Workspace snapshots | ✅ | ✅ |
+| Multi-workspace | ✅ | ✅ |
+| Bot support | 🏗️ | 🏗️ |
+
+🔜 **Coming soon**: Microsoft Teams and more
+
+## 📚 Platform Guides
+
+- **[Slack Guide](docs/slack.md)** — Full command reference for Slack
+- **[Discord Guide](docs/discord.md)** — Full command reference for Discord
+
+## 💡 Use Cases
+
+**🤖 For AI Agents**
+- Give Claude, GPT, or your custom agent the ability to read and send messages
+- Automate Slack/Discord workflows with simple CLI commands
+- Build integrations without OAuth complexity
+
+**👩‍💻 For Developers**
+- Quick message sending from terminal
+- Scripted notifications and alerts
+- Workspace snapshots for debugging
+
+**👥 For Teams**
+- Automate standups and reminders
+- Cross-post announcements to multiple platforms
+- Build custom notification pipelines
+
+## 🧠 Philosophy
+
+**Why not MCP?** MCP servers expose all tools at once, bloating context and confusing agents. **[Agent Skills](https://agentskills.io/) + agent-friendly CLI** offer a better approach—load what you need, when you need it. Fewer tokens, cleaner context, better output.
+
+**Why not OAuth?** OAuth requires an app and it requires workspace admin approval to install, which can take days. This tool just works—zero setup required. Bot support is on the roadmap for those who prefer it.
+
+Inspired by [agent-browser](https://github.com/vercel-labs/agent-browser) from Vercel Labs.
+
+## 🤝 Contributing
+
+```bash
+bun install    # Install dependencies
+bun link       # Link CLI globally for local testing
+bun test       # Run tests
+bun typecheck  # Type check
+bun lint       # Lint
+bun run build  # Build
+```
+
+## 📄 License
+
+MIT