@chrisromp/copilot-bridge 0.6.0-dev.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Chris Romp
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,93 @@
+# copilot-bridge
+
+<div align="center">
+<img src="docs/images/copilot-bridge.png" alt="Copilot Bridge" width="200" height="200">
+</div>
+
+Bridge GitHub Copilot CLI to messaging platforms. Send messages from Mattermost (or other platforms) and get responses from Copilot sessions running on your machine.
+
+> [!WARNING]
+> This is all experimental.
+
+```
+Mattermost Channel → copilot-bridge → @github/copilot-sdk → Copilot CLI
+     ↑                                                          ↓
+     └──────────── streaming response (edit-in-place) ←─────────┘
+```
+
+## Features
+
+- **Multi-bot support** — Run multiple bot identities on the same platform (e.g., `@copilot` for admin, `@alice` for tasks)
+- **Workspaces** — Each bot gets an isolated workspace with its own `AGENTS.md`, `.env` secrets, and `MEMORY.md`
+- **DM auto-discovery** — Just message a bot; no channel config needed for direct messages
+- **Streaming responses** — Edit-in-place message updates with throttling
+- **MCP & skills** — Auto-loads MCP servers and skill directories from Copilot config
+- **Fuzzy model matching** — `/model opus` resolves to `claude-opus-4.6` (mobile-friendly)
+- **Interactive permissions** — Approve/deny tool use via chat, or `/autopilot` to auto-approve
+- **Session management** — `/reload` to refresh config, `/resume` to switch between sessions
+- **Persistent preferences** — Model, agent, verbose mode, permissions saved per-channel
+- **Scheduled tasks** — Recurring (cron) and one-off (datetime) tasks per channel
+- **Inter-agent communication** — Bot-to-bot messaging via `ask_agent` tool
+- **File sharing** — `send_file` and `show_file_in_chat` tools for pushing files to chat
+- **Attachment ingestion** — File and image attachments are extracted and passed to the session
+- **Mid-turn steering** — Send messages while the bot is working to redirect it
+- **Streamer mode** — Hide preview/internal models from `/model` list for on-air use
+- **Thread-aware replies** — Reply in threads via 🧵 trigger or per-channel config
+- **Config hot-reload** — `/reload config` applies safe changes without restarting the bridge
+- **Admin onboarding** — Templates and tools for creating channels, managing workspaces
+
+## Quick Start
+
+1. **Prerequisites**: Node.js 20+, GitHub Copilot CLI installed and authenticated
+2. **Install** (pick one):
+   - **npm**: `npm install -g @chrisromp/copilot-bridge`
+   - **From source**: `git clone https://github.com/ChrisRomp/copilot-bridge.git && cd copilot-bridge && npm install`
+3. **Configure**: `copilot-bridge init` (or `npm run init` from source) — interactive wizard
+4. **Validate**: `copilot-bridge check` (or `npm run check`)
+5. **Run**: `copilot-bridge start` (or `npm run dev` for development with watch mode)
+
+For DMs, that's it — the bridge auto-discovers DM channels for each bot. For group channels, add a `channels` entry mapping the channel ID to a working directory. See the [Setup Guide](docs/setup.md) for the full walkthrough or [Configuration](docs/configuration.md) for reference.
+
+### Running as a service
+
+See the [Setup Guide — Running as a Service](docs/setup.md#running-as-a-service) for macOS (launchd) and Linux (systemd) instructions, or run `npm run install-service` to install automatically.
+
+## Chat Commands
+
+| Command | Aliases | Description |
+|---------|---------|-------------|
+| **Session** | | |
+| `/new` | | Start a fresh session |
+| `/stop` | `/cancel` | Stop the current task |
+| `/reload` | | Reload session (re-reads AGENTS.md, workspace config) |
+| `/reload config` | | Hot-reload config.json (safe changes apply without restart) |
+| `/resume [id]` | | List past sessions, or resume one by ID |
+| `/model [name]` | `/models` | List models or switch model (fuzzy match) |
+| `/agent <name>` | | Switch custom agent (empty to deselect) |
+| `/reasoning <level>` | | Set reasoning effort (`low`/`medium`/`high`/`xhigh`) |
+| `/context` | | Show context window usage |
+| `/verbose` | | Toggle tool call visibility |
+| `/status` | | Show session info |
+| **Permissions** | | |
+| `/approve` / `/deny` | | Handle pending permission request |
+| `/remember` | | Approve + persist the permission rule |
+| `/rules` | `/rule` | List saved permission rules |
+| `/rules clear [spec]` | | Clear rules (all, or by spec) |
+| `/autopilot` | `/yolo` | Toggle auto-approve mode |
+| **Scheduling** | | |
+| `/schedule` | `/schedules`, `/tasks` | Manage scheduled tasks (list, cancel, pause, resume, history) |
+| **Tools & Info** | | |
+| `/skills` | `/tools` | Show available skills and MCP tools |
+| `/mcp` | | Show MCP servers and their source |
+| `/streamer-mode` | `/on-air` | Toggle streamer mode (hides preview/internal models) |
+| `/help` | | Show common commands; `/help all` for full list |
+
+## Documentation
+
+- **[Configuration](docs/configuration.md)** — Platforms, channels, permissions, defaults
+- **[Workspaces & Agents](docs/workspaces.md)** — Workspace system, .env secrets, templates, agent onboarding
+- **[Architecture](docs/architecture.md)** — Source layout, message flow, adapter pattern, persistence
+
+## License
+
+MIT

package/bin/copilot-bridge.js

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+
+import { spawn } from 'node:child_process';
+import { dirname, join } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { readFileSync } from 'node:fs';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const root = join(__dirname, '..');
+
+const commands = {
+  start: join(root, 'dist', 'index.js'),
+  init: join(root, 'scripts', 'init.ts'),
+  check: join(root, 'scripts', 'check.ts'),
+  'install-service': join(root, 'scripts', 'install-service.ts'),
+  'uninstall-service': join(root, 'scripts', 'uninstall-service.ts'),
+};
+
+const command = process.argv[2];
+
+if (!command || command === '--help' || command === '-h') {
+  console.log(`copilot-bridge — Mattermost ↔ GitHub Copilot bridge
+
+Usage: copilot-bridge <command>
+
+Commands:
+  init               Interactive setup wizard
+  check              Validate configuration
+  start              Start the bridge
+  install-service    Install as system service
+  uninstall-service  Remove system service
+
+Options:
+  --help, -h         Show this help
+  --version, -v      Show version`);
+  process.exit(0);
+}
+
+if (command === '--version' || command === '-v') {
+  const pkg = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8'));
+  console.log(pkg.version);
+  process.exit(0);
+}
+
+const script = commands[command];
+if (!script) {
+  console.error(`Unknown command: ${command}\nRun 'copilot-bridge --help' for usage.`);
+  process.exit(1);
+}
+
+// Use --import tsx/esm for TypeScript and ESM compatibility
+const child = spawn(process.execPath, ['--import', 'tsx/esm', script, ...process.argv.slice(3)], {
+  stdio: 'inherit',
+  cwd: root,
+});
+
+child.on('exit', (code) => process.exit(code ?? 1));
+child.on('error', (err) => {
+  console.error(`Failed to run command: ${err.message}`);
+  process.exit(1);
+});

package/config.sample.json

@@ -0,0 +1,100 @@
+{
+  "platforms": {
+    "mattermost": {
+      "url": "https://chat.example.com",
+
+      "_comment_auth": "Use ONE of: 'botToken' (single bot) OR 'bots' (multiple identities)",
+
+      "botToken": "SINGLE_BOT_TOKEN",
+
+      "_comment_bots": "Multi-bot example (remove 'botToken' above and rename '_bots' to 'bots'):",
+      "_bots": {
+        "copilot": { "token": "BOT_TOKEN_1", "admin": true },
+        "bob": { "token": "BOT_TOKEN_2", "agent": "bob-agent" }
+      }
+    }
+  },
+  "channels": [
+    {
+      "id": "channel-id-from-mattermost",
+      "platform": "mattermost",
+      "bot": "copilot",
+      "name": "My Project",
+      "workingDirectory": "/path/to/project",
+      "agent": null,
+      "model": "claude-sonnet-4.6",
+      "triggerMode": "mention",
+      "threadedReplies": true,
+      "verbose": false
+    },
+    {
+      "id": "another-channel-id",
+      "platform": "mattermost",
+      "bot": "bob",
+      "name": "Bob's Channel",
+      "workingDirectory": "/path/to/other-project",
+      "model": "claude-sonnet-4.6",
+      "triggerMode": "mention",
+      "threadedReplies": true,
+      "verbose": false
+    }
+  ],
+  "defaults": {
+    "model": "claude-sonnet-4.6",
+    "agent": null,
+    "triggerMode": "mention",
+    "threadedReplies": true,
+    "verbose": false,
+    "permissionMode": "interactive"
+  },
+  "permissions": {
+    "_comment": "CLI-compatible permission syntax: shell(cmd), write, read, MCP_SERVER(tool)",
+    "allow": [
+      "read",
+      "shell(ls)",
+      "shell(cat)",
+      "shell(head)",
+      "shell(tail)",
+      "shell(find)",
+      "shell(grep)",
+      "shell(wc)"
+    ],
+    "deny": [
+      "shell(rm)",
+      "shell(git push)",
+      "shell(git reset)",
+      "shell(shutdown)",
+      "shell(reboot)",
+      "shell(halt)",
+      "shell(systemctl poweroff)",
+      "shell(networksetup)",
+      "shell(diskutil)"
+    ],
+    "allowPaths": [],
+    "allowUrls": [
+      "docs.github.com",
+      "learn.microsoft.com",
+      "npmjs.com",
+      "pypi.org",
+      "crates.io",
+      "pkg.go.dev",
+      "nuget.org",
+      "rubygems.org",
+      "packagist.org",
+      "maven.apache.org",
+      "stackoverflow.com",
+      "developer.mozilla.org"
+    ]
+  },
+  "_comment_interAgent": "Optional: enable inter-agent communication (ask_agent tool)",
+  "interAgent": {
+    "enabled": false,
+    "defaultTimeout": 60,
+    "maxTimeout": 300,
+    "maxDepth": 3,
+    "allow": {
+      "copilot": { "canCall": ["bob"], "canBeCalledBy": ["bob"] },
+      "bob": { "canCall": ["copilot"], "canBeCalledBy": ["copilot"] }
+    }
+  }
+}

package/dist/channels/mattermost/adapter.d.ts

@@ -0,0 +1,55 @@
+import type { ChannelAdapter, InboundMessage, InboundReaction, SendOpts, CreateChannelOpts, TeamInfo, ChannelInfo } from '../../types.js';
+export declare class MattermostAdapter implements ChannelAdapter {
+    readonly platform: string;
+    private client;
+    private wsClient;
+    private botId;
+    private botUsername;
+    private url;
+    private token;
+    private messageHandlers;
+    private reactionHandlers;
+    private disconnectedAt;
+    private lastServerTimestamp;
+    private activeChannels;
+    private recentPostIds;
+    private isReplaying;
+    private pendingReplay;
+    private static readonly MAX_RECENT_POSTS;
+    private static readonly MAX_REPLAY_WINDOW_MS;
+    private static readonly CHANNEL_STALENESS_MS;
+    constructor(platformName: string, url: string, token: string);
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    /**
+     * Discover existing DM channels for this bot via the Mattermost API.
+     * Returns channel IDs for direct message conversations the bot is already part of.
+     */
+    discoverDMChannels(): Promise<{
+        channelId: string;
+        otherUserId: string;
+    }[]>;
+    onMessage(handler: (msg: InboundMessage) => void): void;
+    onReaction(handler: (reaction: InboundReaction) => void): void;
+    sendMessage(channelId: string, content: string, opts?: SendOpts): Promise<string>;
+    updateMessage(_channelId: string, messageId: string, content: string): Promise<void>;
+    deleteMessage(_channelId: string, messageId: string): Promise<void>;
+    setTyping(channelId: string): Promise<void>;
+    replyInThread(channelId: string, rootId: string, content: string): Promise<string>;
+    getBotUserId(): string;
+    addReaction(postId: string, emoji: string): Promise<void>;
+    private handlePosted;
+    private extractAttachments;
+    downloadFile(fileId: string, destPath: string): Promise<string>;
+    sendFile(channelId: string, filePath: string, message?: string, opts?: SendOpts): Promise<string>;
+    createChannel(opts: CreateChannelOpts): Promise<string>;
+    addUserToChannel(channelId: string, userId: string): Promise<void>;
+    getTeams(): Promise<TeamInfo[]>;
+    getChannelByName(teamId: string, name: string): Promise<ChannelInfo | null>;
+    private handleReaction;
+    /** Track a post ID and its channel for deduplication and replay targeting. */
+    private trackPost;
+    /** Fetch and replay messages missed during a WebSocket disconnect. */
+    private replayMissedMessages;
+}
+//# sourceMappingURL=adapter.d.ts.map

package/dist/channels/mattermost/adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../../../src/channels/mattermost/adapter.ts"],"names":[],"mappings":"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"}