@hoverlover/cc-discord 0.2.5 → 0.3.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 Chad Boyd
+
+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

@@ -5,6 +5,7 @@
 - One autonomous Claude Code agent per Discord channel
 - Messages stored in SQLite, delivered to agents via hooks
 - Replies sent back to Discord via `send-discord` tool
+- Automatic catch-up of missed messages on startup — no messages lost during restarts
 - Typing indicators, busy notifications, live trace threads, memory context, attachment support, and more
 
 ## Quick start
@@ -119,6 +120,7 @@ Project-local env files take precedence over `~/.config/cc-discord/`, so cloned-
 | `MAX_ATTACHMENT_INLINE_BYTES` | `100000` | Max bytes for inline attachment content |
 | `MAX_ATTACHMENT_DOWNLOAD_BYTES` | `10000000` | Max bytes for downloaded attachments |
 | `ATTACHMENT_TTL_MS` | `3600000` | TTL for downloaded attachment files (ms) |
+| `CATCHUP_MESSAGE_LIMIT` | `100` | Messages to fetch per channel on startup for catch-up (`0` to disable) |
 
 ### `.env.worker` — required
 
@@ -197,6 +199,10 @@ Security note: the worker process intentionally does not receive `DISCORD_BOT_TO
 
 ## Features
 
+### Message catch-up
+
+When the relay starts, it fetches recent message history from each allowed channel and persists any messages that arrived while it was offline. Duplicates are silently ignored. This ensures no messages are lost during restarts or outages. Controlled by `CATCHUP_MESSAGE_LIMIT` (default 100, set to `0` to disable).
+
 ### Typing indicators
 
 When a user sends a message, the relay starts a typing indicator that repeats every `TYPING_INTERVAL_MS` (default 8s). It stops automatically when Claude replies. After `TYPING_MAX_MS` (default 120s), a configurable fallback patience message is sent.
@@ -265,16 +271,18 @@ In interactive mode, the orchestrator runs as a Claude Code session with a visib
 
 To keep cc-discord running across reboots and terminal closures, install it as a system service.
 
+> **Dedicated Mac server?** If you're setting up a Mac mini (or similar) as a headless, always-on server, see the [macOS Headless Server Setup Guide](docs/mac-setup-guide.md). It covers disabling SIP, configuring TCC permissions, FileVault tradeoffs, auto-login, and LaunchDaemon setup for fully unattended operation.
+
 ### macOS (launchd)
 
-1. Find the full path to `bunx`:
+1. Find the full paths to `bunx` and `claude`:
 
 ```bash
-which bunx
-# e.g. /Users/you/.bun/bin/bunx
+which bunx    # e.g. /Users/you/.bun/bin/bunx
+which claude  # e.g. /Users/you/.local/bin/claude
 ```
 
-2. Create the plist file:
+2. Create the plist file (replace all `/Users/you/...` paths with your actual paths from step 1):
 
 ```bash
 cat > ~/Library/LaunchAgents/com.cc-discord.plist << 'EOF'
@@ -295,8 +303,9 @@ cat > ~/Library/LaunchAgents/com.cc-discord.plist << 'EOF'
 
   <key>EnvironmentVariables</key>
   <dict>
+    <!-- Must include directories for both bunx and claude -->
     <key>PATH</key>
-    <string>/Users/you/.bun/bin:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin</string>
+    <string>/Users/you/.bun/bin:/Users/you/.local/bin:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin</string>
   </dict>
 
   <key>RunAtLoad</key>
@@ -315,7 +324,7 @@ cat > ~/Library/LaunchAgents/com.cc-discord.plist << 'EOF'
 EOF
 ```
 
-3. Replace `/Users/you/.bun/bin/bunx` and the `PATH` value with your actual paths.
+3. **Important:** launchd does not source your shell profile, so the `PATH` must explicitly include the directories for both `bunx` and `claude`. Verify the paths match your system.
 
 4. Load the service:
 
@@ -461,3 +470,9 @@ Monitor all logs:
 ```bash
 tail -f /tmp/cc-discord/logs/*.log
 ```
+
+---
+
+## License
+
+[MIT](LICENSE)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hoverlover/cc-discord",
-  "version": "0.2.5",
+  "version": "0.3.1",
   "description": "Discord <-> Claude Code relay: use your Claude subscription to power per-channel AI bots",
   "type": "module",
   "bin": {

package/scripts/start.sh

@@ -149,7 +149,7 @@ RELAY_PORT="${RELAY_PORT:-3199}"
 RELAY_API_TOKEN="${RELAY_API_TOKEN:-}"
 
 # Ensure bun/curl/claude are findable
-export PATH="$HOME/.bun/bin:/opt/homebrew/bin:/usr/local/bin:$PATH"
+export PATH="$HOME/.bun/bin:$HOME/.local/bin:/opt/homebrew/bin:/usr/local/bin:$PATH"
 
 # ---- Pre-flight: Claude auth check ----
 if ! claude auth status >/dev/null 2>&1; then

package/server/catchup.ts

@@ -0,0 +1,54 @@
+/**
+ * Catch-up: fetch recent messages from allowed channels on startup
+ * to fill in any messages missed while the relay was offline.
+ */
+
+import type { Client } from "discord.js";
+import { CATCHUP_MESSAGE_LIMIT, IGNORED_CHANNEL_IDS, ALLOWED_CHANNEL_IDS, isAllowedUser } from "./config.ts";
+import { persistInboundDiscordMessage, persistOutboundDiscordMessage } from "./messages.ts";
+import { startTypingIndicator } from "./typing.ts";
+
+export async function catchUpMissedMessages(client: Client) {
+  if (CATCHUP_MESSAGE_LIMIT <= 0) {
+    console.log("[Catchup] Disabled (CATCHUP_MESSAGE_LIMIT=0)");
+    return;
+  }
+
+  let channelsScanned = 0;
+  let messagesCaughtUp = 0;
+
+  for (const [, guild] of client.guilds.cache) {
+    const guildChannels = await guild.channels.fetch();
+    for (const [, channel] of guildChannels) {
+      if (!channel || !channel.isTextBased() || channel.isThread() || channel.isVoiceBased()) continue;
+      if (IGNORED_CHANNEL_IDS.has(channel.id)) continue;
+      if (ALLOWED_CHANNEL_IDS.length > 0 && !ALLOWED_CHANNEL_IDS.includes(channel.id)) continue;
+
+      try {
+        const messages = await channel.messages.fetch({ limit: CATCHUP_MESSAGE_LIMIT });
+        channelsScanned++;
+
+        // Sort oldest-first so they're persisted in chronological order
+        const sorted = [...messages.values()]
+          .filter((m) => !m.author.bot && isAllowedUser(m.author.id))
+          .sort((a, b) => a.createdTimestamp - b.createdTimestamp);
+
+        let channelHasNew = false;
+        for (const msg of sorted) {
+          const isNew = await persistInboundDiscordMessage(msg);
+          if (isNew) {
+            messagesCaughtUp++;
+            channelHasNew = true;
+          }
+        }
+        if (channelHasNew) {
+          startTypingIndicator(client, channel.id, persistOutboundDiscordMessage);
+        }
+      } catch (err: unknown) {
+        console.error(`[Catchup] Failed to fetch messages for #${channel.name} (${channel.id}):`, (err as Error).message);
+      }
+    }
+  }
+
+  console.log(`[Catchup] Done — scanned ${channelsScanned} channel(s), caught up ${messagesCaughtUp} message(s)`);
+}

package/server/config.ts

@@ -83,8 +83,23 @@ export const MAX_ATTACHMENT_INLINE_BYTES = Number(process.env.MAX_ATTACHMENT_INL
 export const MAX_ATTACHMENT_DOWNLOAD_BYTES = Number(process.env.MAX_ATTACHMENT_DOWNLOAD_BYTES || 10_000_000);
 export const ATTACHMENT_TTL_MS = Number(process.env.ATTACHMENT_TTL_MS || 3_600_000);
 
+export const CATCHUP_MESSAGE_LIMIT = Number(process.env.CATCHUP_MESSAGE_LIMIT ?? 100);
+
 export const ATTACHMENT_DIR = join("/tmp", "cc-discord", "attachments");
 
+export function isAllowedChannel(channelId: string): boolean {
+  if (!channelId) return false;
+  if (IGNORED_CHANNEL_IDS.has(channelId)) return false;
+  if (ALLOWED_CHANNEL_IDS.length > 0) return ALLOWED_CHANNEL_IDS.includes(channelId);
+  return true;
+}
+
+export function isAllowedUser(userId: string | undefined): boolean {
+  if (!userId) return false;
+  if (ALLOWED_DISCORD_USER_IDS.length === 0) return true;
+  return ALLOWED_DISCORD_USER_IDS.includes(userId);
+}
+
 function loadDotEnv(path: string) {
   if (!existsSync(path)) return;
   const raw = readFileSync(path, "utf8");

package/server/index.ts

@@ -4,6 +4,7 @@ import { Client, GatewayIntentBits, REST, Routes, SlashCommandBuilder } from "di
 import express, { type NextFunction, type Request, type Response } from "express";
 import { cleanupOldAttachments } from "./attachment.ts";
 import { maybeNotifyBusyQueued } from "./busy-notify.ts";
+import { catchUpMissedMessages } from "./catchup.ts";
 import {
   ALLOWED_CHANNEL_IDS,
   ALLOWED_DISCORD_USER_IDS,
@@ -13,6 +14,8 @@ import {
   DISCORD_BOT_TOKEN,
   DISCORD_SESSION_ID,
   IGNORED_CHANNEL_IDS,
+  isAllowedChannel,
+  isAllowedUser,
   MESSAGE_ROUTING_MODE,
   RELAY_ALLOW_NO_AUTH,
   RELAY_API_TOKEN,
@@ -39,19 +42,6 @@ const client = new Client({
   intents: [GatewayIntentBits.Guilds, GatewayIntentBits.GuildMessages, GatewayIntentBits.MessageContent],
 });
 
-function isAllowedChannel(channelId: string): boolean {
-  if (!channelId) return false;
-  if (IGNORED_CHANNEL_IDS.has(channelId)) return false;
-  if (ALLOWED_CHANNEL_IDS.length > 0) return ALLOWED_CHANNEL_IDS.includes(channelId);
-  return true;
-}
-
-function isAllowedUser(userId: string | undefined): boolean {
-  if (!userId) return false;
-  if (ALLOWED_DISCORD_USER_IDS.length === 0) return true;
-  return ALLOWED_DISCORD_USER_IDS.includes(userId);
-}
-
 function requireAuth(req: Request, res: Response): boolean {
   if (RELAY_ALLOW_NO_AUTH) return true;
   const token = req.header("x-api-token") || req.header("authorization")?.replace(/^Bearer\s+/i, "");
@@ -104,6 +94,11 @@ client.once("clientReady", async () => {
 
   // Start live trace thread flush loop
   startTraceFlushLoop(client);
+
+  // Catch up messages missed while offline
+  catchUpMissedMessages(client).catch((err) => {
+    console.error("[Relay] Catch-up failed:", (err as Error).message);
+  });
 });
 
 client.on("messageCreate", async (message) => {

package/server/messages.ts

@@ -26,7 +26,7 @@ export async function formatInboundMessage(message: any) {
   return `${author}: ${fullText}`;
 }
 
-export async function persistInboundDiscordMessage(message: any) {
+export async function persistInboundDiscordMessage(message: any): Promise<boolean> {
   const normalizedContent = await formatInboundMessage(message);
   // In channel mode, route to channelId so per-channel subagents consume independently.
   // In agent mode (legacy), route to CLAUDE_AGENT_ID for single-agent consumption.
@@ -57,13 +57,15 @@ export async function persistInboundDiscordMessage(message: any) {
     });
 
     console.log(`[Relay] queued Discord message ${message.id} -> ${targetAgent}`);
+    return true;
   } catch (err: unknown) {
     const msg = String((err as any)?.message || "");
     if (msg.includes("UNIQUE constraint failed")) {
       // Discord can re-deliver in edge cases; idempotent ignore
-      return;
+      return false;
     }
     console.error("[Relay] failed to persist inbound message:", (err as Error).message);
+    return false;
   }
 }
 

package/server/trace-thread.ts

@@ -36,6 +36,15 @@ let flushTimer: ReturnType<typeof setInterval> | null = null;
 
 // ── Thread lifecycle ────────────────────────────────────────────────
 
+/** Unarchive a thread if it's been auto-archived by Discord. */
+async function ensureUnarchived(thread: ThreadChannel): Promise<void> {
+  try {
+    if (thread.archived) await thread.setArchived(false);
+  } catch {
+    // best-effort — bot may lack MANAGE_THREADS
+  }
+}
+
 /** Lock a thread if not already locked (idempotent). */
 async function ensureLocked(thread: ThreadChannel): Promise<void> {
   try {
@@ -60,7 +69,8 @@ async function ensureTraceThread(client: Client, channelId: string): Promise<Thr
     try {
       const thread = await client.channels.fetch(cachedThreadId);
       if (thread && thread.isThread()) {
-        // Ensure thread is locked (idempotent — handles pre-existing unlocked threads)
+        // Unarchive if Discord auto-archived it, then ensure locked
+        await ensureUnarchived(thread as ThreadChannel);
         await ensureLocked(thread as ThreadChannel);
         return thread as ThreadChannel;
       }
@@ -76,7 +86,8 @@ async function ensureTraceThread(client: Client, channelId: string): Promise<Thr
     try {
       const thread = await client.channels.fetch(dbThreadId);
       if (thread && thread.isThread()) {
-        // Ensure thread is locked
+        // Unarchive if Discord auto-archived it, then ensure locked
+        await ensureUnarchived(thread as ThreadChannel);
         await ensureLocked(thread as ThreadChannel);
         threadCache.set(channelId, dbThreadId);
         return thread as ThreadChannel;
@@ -86,6 +97,37 @@ async function ensureTraceThread(client: Client, channelId: string): Promise<Thr
     }
   }
 
+  // Search existing threads by name before creating a new one (fallback for
+  // cases where the DB record was lost but the thread still exists in Discord)
+  try {
+    const channel = await client.channels.fetch(channelId);
+    if (channel && channel.type === ChannelType.GuildText) {
+      const textChannel = channel as TextChannel;
+      // Check active threads
+      const activeThreads = await textChannel.threads.fetchActive();
+      const existing = activeThreads.threads.find((t) => t.name === TRACE_THREAD_NAME);
+      if (existing) {
+        await ensureUnarchived(existing);
+        await ensureLocked(existing);
+        setTraceThreadId(channelId, existing.id);
+        threadCache.set(channelId, existing.id);
+        return existing;
+      }
+      // Check archived threads
+      const archivedThreads = await textChannel.threads.fetchArchived({ limit: 10 });
+      const existingArchived = archivedThreads.threads.find((t) => t.name === TRACE_THREAD_NAME);
+      if (existingArchived) {
+        await ensureUnarchived(existingArchived);
+        await ensureLocked(existingArchived);
+        setTraceThreadId(channelId, existingArchived.id);
+        threadCache.set(channelId, existingArchived.id);
+        return existingArchived;
+      }
+    }
+  } catch {
+    // best effort — fall through to create
+  }
+
   // Create new thread
   try {
     const channel = await client.channels.fetch(channelId);