agentcord 0.1.0

package/.env.example

@@ -0,0 +1,23 @@
+# Required
+DISCORD_TOKEN=your-bot-token-here
+DISCORD_CLIENT_ID=your-application-client-id
+
+# Optional: Guild ID for instant command registration (otherwise global, ~1hr delay)
+# DISCORD_GUILD_ID=your-guild-id
+
+# Security: Comma-separated Discord user IDs allowed to use the bot
+# ALLOWED_USERS=123456789,987654321
+# Or set this to true to allow everyone (not recommended)
+# ALLOW_ALL_USERS=true
+
+# Optional: Restrict which directories sessions can access
+# ALLOWED_PATHS=/Users/me/Dev,/Users/me/Projects
+
+# Optional: Default working directory for new sessions
+# DEFAULT_DIRECTORY=/Users/me/Dev
+
+# Optional: Auto-delete messages older than N days
+# MESSAGE_RETENTION_DAYS=7
+
+# Optional: Rate limit in ms between messages per user (default 1000)
+# RATE_LIMIT_MS=1000

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 discord-friends contributors
+
+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,135 @@
+# agentcord
+
+Run and manage AI coding agent sessions on your machine through Discord. Currently supports [Claude Code](https://docs.anthropic.com/en/docs/claude-code), with more agents coming soon.
+
+Each session gets a Discord channel for chatting with the agent and a tmux session for direct terminal access. Sessions are organized by project — create multiple sessions in the same codebase, each with their own channel.
+
+## Quick Start
+
+```bash
+npm install -g agentcord
+mkdir my-bot && cd my-bot
+agentcord setup
+agentcord
+```
+
+The setup wizard walks you through creating a Discord app, configuring the bot token, and adding it to your server.
+
+## Requirements
+
+- **Node.js 22.6+** (uses native TypeScript execution)
+- **tmux** (for terminal session access)
+- **Claude Code** installed on the machine (`@anthropic-ai/claude-agent-sdk`)
+
+## How It Works
+
+```
+Discord message → SDK query() → coding agent
+                                      ↓
+Discord embeds ← stream processing ← async iterator
+```
+
+**Hybrid architecture**: The agent SDK handles structured streaming for Discord interaction, while each session also gets a tmux session. You can `tmux attach` and run `claude --resume <session-id>` to take over the same conversation in your terminal.
+
+**Project-based organization**:
+
+```
+Discord Server
+  └── my-api (category)
+  │    ├── #claude-fix-auth        ← session in ~/Dev/my-api
+  │    ├── #claude-add-tests       ← another session, same project
+  │    └── #project-logs
+  └── frontend (category)
+       ├── #claude-redesign        ← session in ~/Dev/frontend
+       └── #project-logs
+```
+
+## Discord Commands
+
+### Sessions
+
+| Command | Description |
+|---------|-------------|
+| `/claude new <name> [directory]` | Create a session with a Discord channel + tmux session |
+| `/claude list` | List active sessions grouped by project |
+| `/claude end` | End the session in the current channel |
+| `/claude continue` | Continue the conversation |
+| `/claude stop` | Abort current generation |
+| `/claude attach` | Show tmux attach command for terminal access |
+| `/claude model <model>` | Change model for the session |
+| `/claude verbose` | Toggle tool call/result visibility |
+| `/claude sync` | Reconnect orphaned tmux sessions |
+
+### Shell
+
+| Command | Description |
+|---------|-------------|
+| `/shell run <command>` | Execute a command in the session directory |
+| `/shell processes` | List running background processes |
+| `/shell kill <pid>` | Kill a process |
+
+### Agent Personas
+
+| Command | Description |
+|---------|-------------|
+| `/agent use <persona>` | Switch persona (code-reviewer, architect, debugger, security, performance, devops) |
+| `/agent list` | List available personas |
+| `/agent clear` | Reset to default |
+
+### Project Config
+
+| Command | Description |
+|---------|-------------|
+| `/project personality <prompt>` | Set a custom system prompt for the project |
+| `/project personality-show` | Show current personality |
+| `/project personality-clear` | Remove personality |
+| `/project skill-add <name> <prompt>` | Add a reusable prompt template (`{input}` placeholder) |
+| `/project skill-run <name> [input]` | Execute a skill |
+| `/project skill-list` | List skills |
+| `/project mcp-add <name> <command>` | Register an MCP server (writes `.mcp.json`) |
+| `/project mcp-list` | List MCP servers |
+| `/project info` | Show project config summary |
+
+## Features
+
+- **Real-time streaming** — Agent responses stream into Discord with edit-in-place updates
+- **Typing indicator** — Shows "Bot is typing..." while the agent is working
+- **Message interruption** — Send a new message to automatically interrupt and redirect the agent
+- **Interactive prompts** — Multi-choice questions render as Discord buttons
+- **Task board** — Agent task lists display as visual embeds with status emojis
+- **Tool output control** — Hidden by default, toggle with `/claude verbose`
+- **Per-project customization** — System prompts, skills, and MCP servers scoped to projects
+- **Agent personas** — Switch between specialized roles (code reviewer, architect, etc.)
+- **Session persistence** — Sessions survive bot restarts
+- **Terminal access** — `tmux attach` to any session for direct CLI use
+
+## Configuration
+
+The setup wizard (`agentcord setup`) creates a `.env` file. You can also edit it directly:
+
+```env
+# Required
+DISCORD_TOKEN=your-bot-token
+DISCORD_CLIENT_ID=your-client-id
+
+# Optional
+DISCORD_GUILD_ID=your-guild-id        # Instant command registration
+ALLOWED_USERS=123456789,987654321      # Comma-separated user IDs
+ALLOW_ALL_USERS=false                  # Or true to skip whitelist
+ALLOWED_PATHS=/Users/me/Dev            # Restrict accessible directories
+DEFAULT_DIRECTORY=/Users/me/Dev        # Default for new sessions
+```
+
+## Development
+
+```bash
+git clone https://github.com/manuelatravajo/agentcord.git
+cd agentcord
+npm install
+cp .env.example .env   # fill in your values
+npm run dev            # start with --watch
+```
+
+## License
+
+MIT

package/bin/agentcord.js

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const cli = join(__dirname, '..', 'src', 'cli.ts');
+const args = process.argv.slice(2);
+
+const child = spawn(
+  process.execPath,
+  ['--experimental-strip-types', cli, ...args],
+  {
+    stdio: 'inherit',
+    cwd: process.cwd(),
+    env: { ...process.env, NODE_NO_WARNINGS: '1' },
+  },
+);
+
+child.on('exit', (code) => process.exit(code ?? 0));

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "agentcord",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Discord bot for managing AI coding agent sessions (Claude Code, Codex, and more)",
+  "bin": {
+    "agentcord": "./bin/agentcord.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "tsconfig.json",
+    ".env.example",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "setup": "node --experimental-strip-types src/setup.ts",
+    "start": "node --experimental-strip-types src/index.ts",
+    "dev": "node --experimental-strip-types --watch src/index.ts",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "keywords": [
+    "discord",
+    "claude",
+    "claude-code",
+    "codex",
+    "ai",
+    "agent",
+    "coding-agent",
+    "tmux",
+    "cli",
+    "bot"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=22.6.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/manuelatravajo/agentcord.git"
+  },
+  "homepage": "https://github.com/manuelatravajo/agentcord#readme",
+  "bugs": {
+    "url": "https://github.com/manuelatravajo/agentcord/issues"
+  },
+  "dependencies": {
+    "@anthropic-ai/claude-agent-sdk": "^0.2.36",
+    "@clack/prompts": "^1.0.0",
+    "discord.js": "^14.16.3",
+    "dotenv": "^17.2.4"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "typescript": "^5.7.2",
+    "vitest": "^3.0.0"
+  }
+}

package/src/agents.ts

@@ -0,0 +1,90 @@
+import type { AgentPersona } from './types.ts';
+
+export const agents: AgentPersona[] = [
+  {
+    name: 'code-reviewer',
+    emoji: '🔍',
+    description: 'Code quality, bugs, best practices',
+    systemPrompt: `You are a senior code reviewer. Focus on:
+- Code quality and readability
+- Potential bugs and edge cases
+- Security vulnerabilities
+- Performance concerns
+- Best practices and design patterns
+Be specific, cite line numbers, and suggest concrete improvements.`,
+  },
+  {
+    name: 'architect',
+    emoji: '🏗️',
+    description: 'System design, patterns, scalability',
+    systemPrompt: `You are a software architect. Focus on:
+- System design and architecture patterns
+- Scalability and maintainability
+- Component boundaries and interfaces
+- Data flow and state management
+- Trade-offs between different approaches
+Think in terms of systems, not just code.`,
+  },
+  {
+    name: 'debugger',
+    emoji: '🐛',
+    description: 'Root cause analysis, debugging strategies',
+    systemPrompt: `You are a debugging specialist. Focus on:
+- Root cause analysis over symptoms
+- Systematic debugging strategies
+- Reproducing issues reliably
+- Tracing data flow to find where things break
+- Suggesting targeted fixes with minimal side effects
+Think methodically and follow the evidence.`,
+  },
+  {
+    name: 'security',
+    emoji: '🔒',
+    description: 'Vulnerabilities, OWASP, secure coding',
+    systemPrompt: `You are a security analyst. Focus on:
+- OWASP Top 10 vulnerabilities
+- Input validation and sanitization
+- Authentication and authorization flaws
+- Injection attacks (SQL, XSS, command)
+- Secure defaults and least privilege
+Flag issues with severity ratings and remediation steps.`,
+  },
+  {
+    name: 'performance',
+    emoji: '🚀',
+    description: 'Optimization, profiling, bottlenecks',
+    systemPrompt: `You are a performance engineer. Focus on:
+- Identifying bottlenecks and hot paths
+- Algorithm and data structure choices
+- Memory allocation and GC pressure
+- I/O optimization and caching strategies
+- Benchmarking and profiling recommendations
+Quantify impact where possible.`,
+  },
+  {
+    name: 'devops',
+    emoji: '⚙️',
+    description: 'CI/CD, Docker, infrastructure',
+    systemPrompt: `You are a DevOps engineer. Focus on:
+- CI/CD pipeline design and optimization
+- Container and orchestration best practices
+- Infrastructure as code
+- Monitoring, logging, and observability
+- Deployment strategies and rollback plans
+Prioritize reliability and automation.`,
+  },
+  {
+    name: 'general',
+    emoji: '🧠',
+    description: 'Default — no specialized focus',
+    systemPrompt: '',
+  },
+];
+
+export function getAgent(name: string): AgentPersona | undefined {
+  return agents.find(a => a.name === name);
+}
+
+export function listAgents(): AgentPersona[] {
+  return agents;
+}

package/src/bot.ts

@@ -0,0 +1,193 @@
+import {
+  Client,
+  GatewayIntentBits,
+  ActivityType,
+  InteractionType,
+  ComponentType,
+  type TextChannel,
+  ChannelType,
+  Collection,
+} from 'discord.js';
+import { config } from './config.ts';
+import { registerCommands } from './commands.ts';
+import { handleClaude, handleShell, handleAgent, handleProject, setLogger } from './command-handlers.ts';
+import { handleMessage } from './message-handler.ts';
+import { handleButton, handleSelectMenu } from './button-handler.ts';
+import { loadSessions, getAllSessions, unlinkChannel } from './session-manager.ts';
+import { loadProjects } from './project-manager.ts';
+
+let client: Client;
+let logChannel: TextChannel | null = null;
+let logBuffer: string[] = [];
+let logTimer: ReturnType<typeof setTimeout> | null = null;
+
+function botLog(msg: string): void {
+  const timestamp = new Date().toISOString().slice(11, 19);
+  const formatted = `\`[${timestamp}]\` ${msg}`;
+  console.log(`[${timestamp}] ${msg}`);
+
+  logBuffer.push(formatted);
+  if (!logTimer) {
+    logTimer = setTimeout(flushLogs, 2000);
+  }
+}
+
+async function flushLogs(): Promise<void> {
+  logTimer = null;
+  if (!logChannel || logBuffer.length === 0) return;
+
+  const batch = logBuffer.splice(0, logBuffer.length).join('\n');
+  try {
+    await logChannel.send(batch);
+  } catch {
+    // Log channel may have been deleted
+  }
+}
+
+function updatePresence(): void {
+  const sessionCount = getAllSessions().length;
+  const generating = getAllSessions().filter(s => s.isGenerating).length;
+
+  if (sessionCount === 0) {
+    client.user?.setPresence({
+      status: 'idle',
+      activities: [{ name: 'No active sessions', type: ActivityType.Custom }],
+    });
+  } else {
+    const status = generating > 0 ? `${generating} generating` : `${sessionCount} sessions`;
+    client.user?.setPresence({
+      status: 'online',
+      activities: [{ name: `${status}`, type: ActivityType.Watching }],
+    });
+  }
+}
+
+// Message retention cleanup
+async function cleanupOldMessages(): Promise<void> {
+  if (!config.messageRetentionDays) return;
+
+  const cutoff = Date.now() - config.messageRetentionDays * 24 * 60 * 60 * 1000;
+
+  for (const session of getAllSessions()) {
+    try {
+      const channel = client.channels.cache.get(session.channelId) as TextChannel | undefined;
+      if (!channel) continue;
+
+      const messages = await channel.messages.fetch({ limit: 100 });
+      const old = messages.filter(m => m.createdTimestamp < cutoff);
+      if (old.size > 0) {
+        await channel.bulkDelete(old, true);
+      }
+    } catch {
+      // Channel may not exist
+    }
+  }
+}
+
+export async function startBot(): Promise<void> {
+  client = new Client({
+    intents: [
+      GatewayIntentBits.Guilds,
+      GatewayIntentBits.GuildMessages,
+      GatewayIntentBits.MessageContent,
+    ],
+  });
+
+  setLogger(botLog);
+
+  // Slash commands
+  client.on('interactionCreate', async interaction => {
+    try {
+      if (interaction.type === InteractionType.ApplicationCommand && interaction.isChatInputCommand()) {
+        switch (interaction.commandName) {
+          case 'claude': return await handleClaude(interaction);
+          case 'shell': return await handleShell(interaction);
+          case 'agent': return await handleAgent(interaction);
+          case 'project': return await handleProject(interaction);
+        }
+      }
+
+      if (interaction.isButton()) {
+        return await handleButton(interaction);
+      }
+
+      if (interaction.isStringSelectMenu()) {
+        return await handleSelectMenu(interaction);
+      }
+    } catch (err) {
+      console.error('Interaction error:', err);
+      try {
+        if (interaction.isRepliable() && !interaction.replied && !interaction.deferred) {
+          await interaction.reply({ content: 'An error occurred.', ephemeral: true });
+        }
+      } catch { /* can't recover */ }
+    }
+  });
+
+  // Channel messages
+  client.on('messageCreate', handleMessage);
+
+  // Channel deletion cleanup
+  client.on('channelDelete', channel => {
+    if (channel.type === ChannelType.GuildText) {
+      unlinkChannel(channel.id);
+    }
+  });
+
+  // Ready
+  client.once('ready', async () => {
+    console.log(`Logged in as ${client.user?.tag}`);
+
+    // Register commands
+    await registerCommands();
+
+    // Load persisted state
+    await loadProjects();
+    await loadSessions();
+
+    // Set up log channel in the first guild
+    const guild = client.guilds.cache.first();
+    if (guild) {
+      // Find existing bot-logs channel or note it doesn't exist
+      logChannel = guild.channels.cache.find(
+        ch => ch.name === 'bot-logs' && ch.type === ChannelType.GuildText,
+      ) as TextChannel | undefined ?? null;
+
+      if (!logChannel) {
+        try {
+          logChannel = await guild.channels.create({
+            name: 'bot-logs',
+            type: ChannelType.GuildText,
+          });
+        } catch {
+          console.warn('Could not create #bot-logs channel');
+        }
+      }
+    }
+
+    botLog(`Bot online. ${getAllSessions().length} session(s) restored.`);
+    updatePresence();
+
+    // Presence update interval
+    setInterval(updatePresence, 30_000);
+
+    // Message cleanup
+    if (config.messageRetentionDays) {
+      await cleanupOldMessages();
+      setInterval(cleanupOldMessages, 60 * 60 * 1000); // hourly
+    }
+  });
+
+  // Graceful shutdown
+  const shutdown = () => {
+    botLog('Shutting down...');
+    flushLogs();
+    client.destroy();
+    process.exit(0);
+  };
+
+  process.on('SIGINT', shutdown);
+  process.on('SIGTERM', shutdown);
+
+  await client.login(config.token);
+}

package/src/button-handler.ts

@@ -0,0 +1,153 @@
+import type {
+  ButtonInteraction,
+  StringSelectMenuInteraction,
+  TextChannel,
+} from 'discord.js';
+import { config } from './config.ts';
+import * as sessions from './session-manager.ts';
+import { handleOutputStream, getExpandableContent } from './output-handler.ts';
+import { isUserAllowed, truncate } from './utils.ts';
+
+export async function handleButton(interaction: ButtonInteraction): Promise<void> {
+  if (!isUserAllowed(interaction.user.id, config.allowedUsers, config.allowAllUsers)) {
+    await interaction.reply({ content: 'Not authorized.', ephemeral: true });
+    return;
+  }
+
+  const customId = interaction.customId;
+
+  // Stop button
+  if (customId.startsWith('stop:')) {
+    const sessionId = customId.slice(5);
+    const stopped = sessions.abortSession(sessionId);
+    await interaction.reply({
+      content: stopped ? 'Generation stopped.' : 'Session was not generating.',
+      ephemeral: true,
+    });
+    return;
+  }
+
+  // Continue button
+  if (customId.startsWith('continue:')) {
+    const sessionId = customId.slice(9);
+    const session = sessions.getSession(sessionId);
+    if (!session) {
+      await interaction.reply({ content: 'Session not found.', ephemeral: true });
+      return;
+    }
+    if (session.isGenerating) {
+      await interaction.reply({ content: 'Session is already generating.', ephemeral: true });
+      return;
+    }
+
+    await interaction.deferReply();
+    try {
+      const channel = interaction.channel as TextChannel;
+      const stream = sessions.continueSession(sessionId);
+      await interaction.editReply('Continuing...');
+      await handleOutputStream(stream, channel, sessionId, session.verbose);
+    } catch (err: unknown) {
+      await interaction.editReply(`Error: ${(err as Error).message}`);
+    }
+    return;
+  }
+
+  // Expand button
+  if (customId.startsWith('expand:')) {
+    const contentId = customId.slice(7);
+    const content = getExpandableContent(contentId);
+    if (!content) {
+      await interaction.reply({ content: 'Content expired.', ephemeral: true });
+      return;
+    }
+    // Discord max message is 2000 chars
+    const display = truncate(content, 1950);
+    await interaction.reply({ content: `\`\`\`\n${display}\n\`\`\``, ephemeral: true });
+    return;
+  }
+
+  // Option buttons (numbered choices)
+  if (customId.startsWith('option:')) {
+    const parts = customId.split(':');
+    const sessionId = parts[1];
+    const optionIndex = parseInt(parts[2], 10);
+
+    const session = sessions.getSession(sessionId);
+    if (!session) {
+      await interaction.reply({ content: 'Session not found.', ephemeral: true });
+      return;
+    }
+
+    // Send the option number as input
+    const optionText = `${optionIndex + 1}`;
+    await interaction.deferReply();
+    try {
+      const channel = interaction.channel as TextChannel;
+      const stream = sessions.sendPrompt(sessionId, optionText);
+      await interaction.editReply(`Selected option ${optionIndex + 1}`);
+      await handleOutputStream(stream, channel, sessionId, session.verbose);
+    } catch (err: unknown) {
+      await interaction.editReply(`Error: ${(err as Error).message}`);
+    }
+    return;
+  }
+
+  // Confirm buttons (yes/no)
+  if (customId.startsWith('confirm:')) {
+    const parts = customId.split(':');
+    const sessionId = parts[1];
+    const answer = parts[2]; // 'yes' or 'no'
+
+    const session = sessions.getSession(sessionId);
+    if (!session) {
+      await interaction.reply({ content: 'Session not found.', ephemeral: true });
+      return;
+    }
+
+    await interaction.deferReply();
+    try {
+      const channel = interaction.channel as TextChannel;
+      const stream = sessions.sendPrompt(sessionId, answer);
+      await interaction.editReply(`Answered: ${answer}`);
+      await handleOutputStream(stream, channel, sessionId, session.verbose);
+    } catch (err: unknown) {
+      await interaction.editReply(`Error: ${(err as Error).message}`);
+    }
+    return;
+  }
+
+  await interaction.reply({ content: 'Unknown button.', ephemeral: true });
+}
+
+export async function handleSelectMenu(interaction: StringSelectMenuInteraction): Promise<void> {
+  if (!isUserAllowed(interaction.user.id, config.allowedUsers, config.allowAllUsers)) {
+    await interaction.reply({ content: 'Not authorized.', ephemeral: true });
+    return;
+  }
+
+  const customId = interaction.customId;
+
+  if (customId.startsWith('select:')) {
+    const sessionId = customId.slice(7);
+    const selected = interaction.values[0];
+
+    const session = sessions.getSession(sessionId);
+    if (!session) {
+      await interaction.reply({ content: 'Session not found.', ephemeral: true });
+      return;
+    }
+
+    await interaction.deferReply();
+    try {
+      const channel = interaction.channel as TextChannel;
+      const stream = sessions.sendPrompt(sessionId, selected);
+      await interaction.editReply(`Selected: ${truncate(selected, 100)}`);
+      await handleOutputStream(stream, channel, sessionId, session.verbose);
+    } catch (err: unknown) {
+      await interaction.editReply(`Error: ${(err as Error).message}`);
+    }
+    return;
+  }
+
+  await interaction.reply({ content: 'Unknown selection.', ephemeral: true });
+}