# ClaudeTools Discord Bot

Discord bot providing MSP team access to ClaudeTools database, M365 remediation-tool, and Claude AI assistance through Discord channels.

## Features

- **Conversational AI**: Powered by Claude API with full context awareness
- **ClaudeTools Integration**: Query MSP database (clients, sessions, tasks, infrastructure)
- **M365 Security**: Run breach checks and tenant sweeps via remediation-tool
- **Thread-Based**: Isolated conversations with full history
- **Streaming Responses**: Real-time updates as Claude thinks and executes tools

## Architecture

As of Phase 1.5, the bot is "Claude Code in a Discord channel." Each Discord
thread is a persistent `ClaudeSDKClient` session whose `cwd` is the ClaudeTools
repo root, with `.claude/CLAUDE.md` as the system prompt. The agent uses the
Claude Agent SDK's native tools (Read, Edit, Write, Bash, Glob, Grep, etc.) —
the bot does not hand-write tool definitions or call the ClaudeTools HTTP API.

```
Discord thread  ──>  MessageHandler  ──>  ClaudeAgentManager
                                                │
                                                v
                                       ClaudeSDKClient (per thread)
                                       cwd = ClaudeTools repo
                                       system_prompt = .claude/CLAUDE.md
                                                │
                                                v
                                       Native SDK tools:
                                       Read / Edit / Write / Bash / Glob / Grep / ...
```

## Prerequisites

- **Python 3.11+**
- **Discord Bot** created in Discord Developer Portal
- **Anthropic API Key** for Claude access
- **ClaudeTools API** running at http://172.16.3.30:8001
- **Git Bash** (Windows) for remediation-tool scripts
- **SOPS Vault** accessible at D:\vault (Windows) or configured path

## Setup

### 1. Discord Bot Setup

1. Go to [Discord Developer Portal](https://discord.com/developers/applications)
2. Create New Application
3. Go to "Bot" section
4. Click "Add Bot"
5. Enable these **Privileged Gateway Intents**:
   - Message Content Intent
   - Server Members Intent
6. Copy the bot token
7. Go to "OAuth2" → "URL Generator"
8. Select scopes: `bot`, `applications.commands`
9. Select bot permissions:
   - Send Messages
   - Send Messages in Threads
   - Create Public Threads
   - Read Message History
   - Use Slash Commands
10. Copy the generated URL and invite bot to your server

### 2. Environment Configuration

1. Copy `.env.example` to `.env`:
   ```bash
   cp .env.example .env
   ```

2. Edit `.env` and fill in your values:
   ```env
   DISCORD_TOKEN=your_bot_token_from_step_1
   DISCORD_GUILD_ID=your_server_id
   ANTHROPIC_API_KEY=your_anthropic_key
   CLAUDETOOLS_API_KEY=your_api_key

   # Windows paths (adjust for your system)
   VAULT_PATH=D:\vault
   CLAUDETOOLS_ROOT=D:\claudetools
   ```

### 3. Install Dependencies

```bash
pip install -r requirements.txt
```

## Running the Bot

### Development (Command Line)

```bash
cd projects/discord-bot
python -m bot.main
```

### Production (Windows Service with NSSM)

1. Download [NSSM](https://nssm.cc/)

2. Install as service:
   ```powershell
   nssm install ClaudeToolsDiscordBot "C:\Python311\python.exe" "-m bot.main"
   nssm set ClaudeToolsDiscordBot AppDirectory "D:\claudetools\projects\discord-bot"
   nssm set ClaudeToolsDiscordBot Start SERVICE_AUTO_START
   nssm set ClaudeToolsDiscordBot AppStdout "D:\claudetools\projects\discord-bot\logs\stdout.log"
   nssm set ClaudeToolsDiscordBot AppStderr "D:\claudetools\projects\discord-bot\logs\stderr.log"
   ```

3. Start service:
   ```powershell
   nssm start ClaudeToolsDiscordBot
   ```

4. Check status:
   ```powershell
   nssm status ClaudeToolsDiscordBot
   ```

## Usage

### Mention-Based Conversations

Start a conversation by mentioning the bot:

```
@ClaudeTools hello!
@ClaudeTools list clients from last week
@ClaudeTools check john.trozzi@cascadestucson.com for breach
```

The bot will:
1. Create a dedicated thread for the conversation
2. Stream Claude's response with live updates
3. Execute tools as needed (database queries, breach checks)
4. Maintain full conversation context

### Example Queries

**ClaudeTools Database:**
```
@ClaudeTools show me GuruRMM sessions from April
@ClaudeTools list all Cascades tickets
@ClaudeTools what infrastructure do we manage for Dataforth?
```

**M365 Breach Checks:**
```
@ClaudeTools check user@domain.com for breach
@ClaudeTools sweep cascadestucson.com tenant for security issues
```

**General Questions:**
```
@ClaudeTools what projects are we working on?
@ClaudeTools summarize work from yesterday
```

## Project Structure

```
discord-bot/
├── bot/
│   ├── main.py                  # Entry point
│   ├── config.py                # Configuration
│   ├── handlers/
│   │   └── message_handler.py   # Discord message handling
│   ├── claude/
│   │   ├── client.py            # Claude API wrapper
│   │   └── tools.py             # Tool definitions
│   ├── services/               # (Phase 2) ClaudeTools API client
│   ├── auth/                   # (Phase 2) User permissions
│   └── formatting/             # (Phase 4) Embeds and tables
├── .env                        # Environment config (gitignored)
├── .env.example                # Template
├── requirements.txt
└── README.md
```

## Development Roadmap

### Phase 1.5: Claude Agent SDK refactor (Current)
- [x] Discord bot connection
- [x] Claude Agent SDK streaming (replaces raw Anthropic SDK)
- [x] Per-thread persistent agent sessions (`ClaudeSDKClient`)
- [x] Workspace = ClaudeTools repo; system prompt = `.claude/CLAUDE.md`
- [x] Native SDK tools (Read/Edit/Write/Bash/Glob/Grep) — no hand-written tools
- The hand-written `query_claudetools_api`, `run_breach_check`, and
  `run_tenant_sweep` tools from the Phase 1 scaffold were removed. The agent
  invokes those workflows via the existing skills under `.claude/skills/` and
  via Bash + the vault wrapper, the same way Claude Code does.

### Phase 2: ClaudeTools API Integration
- [ ] HTTP client with JWT auth
- [ ] Implement `query_claudetools_api` tool
- [ ] User role mapping (admin vs tech)
- [ ] Audit logging

### Phase 3: Remediation-Tool Integration
- [ ] Bash subprocess runner
- [ ] Implement `run_breach_check` tool
- [ ] Implement `run_tenant_sweep` tool
- [ ] Progress streaming
- [ ] Artifact upload

### Phase 4: Polish
- [ ] Confirmation buttons for remediation
- [ ] Rich embeds for structured data
- [ ] Select menus for multi-choice
- [ ] Ephemeral messages for sensitive data
- [ ] Slash commands

## Troubleshooting

### Bot doesn't respond to mentions

1. Check bot is online: Look for green status in Discord
2. Check intents: Message Content Intent must be enabled in Discord Developer Portal
3. Check logs: `tail -f logs/bot.log`
4. Verify permissions: Bot needs "Send Messages" and "Send Messages in Threads"

### Path validation errors

```
FileNotFoundError: Vault not found at D:\vault
```

**Fix:** Update `VAULT_PATH` in `.env` to match your system.

### Module import errors

```
ModuleNotFoundError: No module named 'discord'
```

**Fix:** Install dependencies: `pip install -r requirements.txt`

## Contributing

This is Phase 1 MVP. Next steps:
1. Implement tool execution (see `bot/handlers/message_handler.py` `execute_tool` placeholder)
2. Add ClaudeTools API client (see `bot/services/`)
3. Add remediation script runner (see `bot/services/`)

## License

Internal Arizona Computer Guru project.