Skip to content

Commit 8acae65

Browse files
Stewart86claude
Stewart86
and
claude
committed
docs: enhance documentation with quick Docker setup and contribution guidelines
- Restructure README.md to lead with 2-minute Docker installation - Move detailed setup instructions to lower sections for better UX - Add comprehensive CONTRIBUTING.md following GitHub best practices - Include MIT LICENSE file for open source compliance - Update project structure and contributing information 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <[email protected]>
1 parent fc03a32 commit 8acae65

File tree

3 files changed

+345
-12
lines changed

3 files changed

+345
-12
lines changed

‎CONTRIBUTING.md‎

Lines changed: 257 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,257 @@
1+
# Contributing to Bobby
2+
3+
Thank you for your interest in contributing to Bobby! This document provides guidelines for contributing to the project.
4+
5+
## Table of Contents
6+
7+
- [Getting Started](#getting-started)
8+
- [Development Setup](#development-setup)
9+
- [Code Architecture](#code-architecture)
10+
- [Contributing Guidelines](#contributing-guidelines)
11+
- [Pull Request Process](#pull-request-process)
12+
- [Bug Reports](#bug-reports)
13+
- [Feature Requests](#feature-requests)
14+
15+
## Getting Started
16+
17+
Bobby is a Discord bot that uses Claude Code to analyze codebases and answer questions. It's built with:
18+
19+
- **Bun**: Fast JavaScript runtime
20+
- **Discord.js**: Discord bot framework
21+
- **Claude Code CLI**: AI-powered code analysis
22+
- **GitHub CLI**: Automated issue creation
23+
24+
## Development Setup
25+
26+
### Prerequisites
27+
28+
- [Bun](https://bun.sh/) runtime
29+
- Discord Bot Token (see README.md for setup)
30+
- Anthropic API Key
31+
- GitHub Personal Access Token
32+
33+
### Local Development
34+
35+
1. **Clone the repository**:
36+
```bash
37+
git clone https://github.com/your-org/bobby.git
38+
cd bobby
39+
```
40+
41+
2. **Install dependencies**:
42+
```bash
43+
bun install
44+
```
45+
46+
3. **Install required CLI tools**:
47+
```bash
48+
# Install Claude Code CLI
49+
bun install -g @anthropic-ai/claude-code
50+
51+
# Install GitHub CLI (platform specific)
52+
# See: https://github.com/cli/cli#installation
53+
```
54+
55+
4. **Set up environment variables**:
56+
```bash
57+
cp .env.example .env
58+
# Edit .env with your tokens and configuration
59+
```
60+
61+
5. **Run the development server**:
62+
```bash
63+
bun run dev
64+
```
65+
66+
### Docker Development
67+
68+
For testing the full Docker setup:
69+
70+
```bash
71+
# Build the image
72+
docker build -t bobby-bot .
73+
74+
# Run with your configuration
75+
docker run --env-file .env bobby-bot
76+
```
77+
78+
## Code Architecture
79+
80+
### Core Components
81+
82+
#### `index.js` - Main Application
83+
- **Discord Client Setup**: Initializes Discord.js client with required intents
84+
- **Message Handling**: Processes mentions and thread-based conversations
85+
- **Session Management**: Manages Claude Code sessions per Discord thread
86+
- **Streaming Responses**: Real-time response streaming from Claude Code
87+
88+
#### `entrypoint.sh` - Docker Initialization
89+
- Environment validation
90+
- GitHub authentication
91+
- Repository cloning and syncing
92+
- Service startup
93+
94+
### Key Functions
95+
96+
#### `processWithClaude(query, channel, sessionId)`
97+
Handles the core interaction with Claude Code CLI:
98+
- Spawns Claude Code process with streaming output
99+
- Manages session continuity across thread conversations
100+
- Processes real-time JSON responses
101+
- Handles error cases and fallbacks
102+
103+
#### Thread Management
104+
- `isNewBobbyCall()`: Detects new mentions in channels
105+
- `isThreadFollowUp()`: Identifies follow-up messages in threads
106+
- `extractSessionId()`: Extracts session ID from thread names
107+
- Thread naming: `Bobby - Title - session-id`
108+
109+
#### Security Features
110+
- Server whitelist validation (`guildCreate` event)
111+
- Environment variable validation
112+
- Token masking in logs
113+
114+
### Data Flow
115+
116+
1. **New Conversation**:
117+
```
118+
User mentions Bobby → Create thread → Start new Claude session → Stream response → Update thread name
119+
```
120+
121+
2. **Thread Follow-up**:
122+
```
123+
User message in thread → Extract session ID → Resume Claude session → Stream response
124+
```
125+
126+
3. **Bug Detection**:
127+
```
128+
Claude detects issue → Creates GitHub issue → Returns issue link in response
129+
```
130+
131+
## Contributing Guidelines
132+
133+
### Code Style
134+
135+
- Use modern JavaScript (ES6+)
136+
- Follow existing formatting patterns
137+
- Add comments for complex logic
138+
- Use descriptive variable names
139+
140+
### Commit Messages
141+
142+
Use conventional commit format:
143+
```
144+
type(scope): description
145+
146+
feat(discord): add thread-based session management
147+
fix(claude): handle streaming response edge cases
148+
docs(readme): update Docker setup instructions
149+
```
150+
151+
### Branch Naming
152+
153+
- `feature/description` - New features
154+
- `fix/description` - Bug fixes
155+
- `docs/description` - Documentation updates
156+
- `refactor/description` - Code refactoring
157+
158+
### Testing
159+
160+
- Test Discord bot functionality in a development server
161+
- Verify Claude Code integration with different query types
162+
- Test Docker deployment with environment variable variations
163+
- Validate GitHub issue creation workflow
164+
165+
## Pull Request Process
166+
167+
1. **Fork the repository** and create your feature branch
168+
2. **Make your changes** following the guidelines above
169+
3. **Test thoroughly** - ensure no regressions
170+
4. **Update documentation** if needed
171+
5. **Submit a pull request** with:
172+
- Clear description of changes
173+
- Link to any related issues
174+
- Screenshots/demos for UI changes
175+
176+
### PR Template
177+
178+
```markdown
179+
## Description
180+
Brief description of changes
181+
182+
## Type of Change
183+
- [ ] Bug fix
184+
- [ ] New feature
185+
- [ ] Documentation update
186+
- [ ] Refactoring
187+
188+
## Testing
189+
- [ ] Tested locally
190+
- [ ] Tested in Docker
191+
- [ ] Discord integration verified
192+
- [ ] Claude Code integration verified
193+
194+
## Checklist
195+
- [ ] Code follows project style guidelines
196+
- [ ] Self-review completed
197+
- [ ] Documentation updated
198+
- [ ] No sensitive information exposed
199+
```
200+
201+
## Bug Reports
202+
203+
When reporting bugs, include:
204+
205+
1. **Environment details**:
206+
- Operating system
207+
- Bun version
208+
- Docker version (if applicable)
209+
210+
2. **Steps to reproduce**:
211+
- Exact Discord commands used
212+
- Expected vs actual behavior
213+
- Error messages or logs
214+
215+
3. **Configuration**:
216+
- Environment variables (without sensitive values)
217+
- Discord server setup
218+
- Repository configuration
219+
220+
## Feature Requests
221+
222+
For new features:
223+
224+
1. **Use case description**: Why is this feature needed?
225+
2. **Proposed solution**: How should it work?
226+
3. **Alternatives considered**: Other approaches you've thought about
227+
4. **Implementation details**: Technical considerations (if applicable)
228+
229+
## Code of Conduct
230+
231+
- Be respectful and inclusive
232+
- Focus on constructive feedback
233+
- Help newcomers learn and contribute
234+
- Keep discussions relevant and professional
235+
236+
## Getting Help
237+
238+
- **Issues**: Create a GitHub issue for bugs or questions
239+
- **Discussions**: Use GitHub Discussions for general questions
240+
- **Discord**: Join our development Discord server (link in README)
241+
242+
## Security
243+
244+
If you find security vulnerabilities:
245+
246+
1. **DO NOT** create a public issue
247+
2. Email security concerns to [security email]
248+
3. Allow time for fixing before public disclosure
249+
250+
## Recognition
251+
252+
Contributors will be recognized in:
253+
- README.md contributors section
254+
- Release notes for significant contributions
255+
- Special thanks for first-time contributors
256+
257+
Thank you for contributing to Bobby! 🤖

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2025 Bobby Discord Bot
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md‎

Lines changed: 67 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -2,21 +2,72 @@
22

33
Bobby is a Discord chatbot that helps answer questions about your codebase, file bugs, and translate business requirements into technical requirements. Bobby leverages Claude Code to understand your codebase and provide intelligent responses.
44

5+
## Quick Start with Docker
6+
7+
Get Bobby running in under 2 minutes:
8+
9+
```bash
10+
# 1. Build the Docker image
11+
docker build -t bobby-bot .
12+
13+
# 2. Run Bobby with your credentials
14+
docker run -d \
15+
--name bobby \
16+
-e DISCORD_TOKEN=your_discord_bot_token \
17+
-e ANTHROPIC_API_KEY=your_anthropic_api_key \
18+
-e GH_TOKEN=your_github_personal_access_token \
19+
-e GITHUB_REPO=owner/repo-name \
20+
-v bobby-data:/app/data \
21+
bobby-bot
22+
```
23+
24+
That's it! Bobby will automatically:
25+
- Install and configure Claude Code CLI
26+
- Authenticate with GitHub
27+
- Clone your repository
28+
- Start monitoring Discord for mentions
29+
30+
**Privacy & Security**: You create your own Discord bot and run Bobby in your own isolated Docker container. Your code, conversations, and API keys never leave your environment.
31+
532
## Features
633

734
- **AI-Powered Responses**: Uses Claude Code to answer questions about your codebase
835
- **Bug Detection**: Automatically creates GitHub issues when bugs are detected
9-
- **Memory Management**: Stores responses in a searchable, topic-organized format
10-
- **Rate Limiting**: Prevents abuse with SQLite-based rate limiting
11-
- **Easy Deployment**: Docker support for simple deployment
36+
- **Thread-Based Sessions**: Each conversation maintains context in Discord threads
37+
- **Read-Only Design**: Analyzes code without making changes
38+
- **Privacy-First**: Your own Discord bot and isolated Docker container
39+
- **Easy Deployment**: Complete Docker support with automated setup
40+
41+
## How It Works
42+
43+
Bobby uses Discord threads for session management:
44+
45+
1. **Start a conversation**: Mention Bobby in any channel to create a new thread
46+
2. **Continue chatting**: Type in the thread (no need to mention Bobby again)
47+
3. **Each thread maintains context**: Bobby remembers your conversation history
48+
4. **Auto-organization**: Threads are named based on your questions
49+
50+
Bobby can:
51+
- ✅ Analyze and explore your codebase
52+
- ✅ Answer questions about code functionality
53+
- ✅ Detect bugs and create GitHub issues
54+
- ✅ Provide code recommendations
55+
- ❌ Cannot modify or write code files (read-only by design)
56+
57+
**Why Self-Host Bobby?**
58+
- 🔒 **Complete Privacy**: Your code never leaves your infrastructure
59+
- 🏠 **Your Own Bot**: Create and control your own Discord bot
60+
- 🐳 **Isolated Environment**: Runs in your own Docker container
61+
- 🔑 **Your API Keys**: Direct relationship with Anthropic and GitHub
62+
- 🛡️ **Zero Trust**: No third-party services handling your sensitive data
1263

1364
## Prerequisites
1465

15-
- [Bun](https://bun.sh/) runtime for local development
1666
- [Discord Bot Token](https://discord.com/developers/applications) (see setup instructions below)
1767
- [Anthropic API Key](https://anthropic.com) for Claude (see setup instructions below)
1868
- [GitHub Personal Access Token](https://github.com/settings/tokens) with repo and issue scopes
1969
- GitHub repository name in the format `owner/repo-name`
70+
- [Bun](https://bun.sh/) runtime (for local development only)
2071

2172
## Discord Bot Setup
2273

@@ -339,27 +390,31 @@ bobby/
339390
├── index.js # Main application file
340391
├── docs/ # Memory storage directory
341392
├── data/ # Data storage directory
342-
│ └── bobby.sqlite # Rate limiting database
343393
├── CLAUDE.md # Memory index for Claude
344394
├── package.json # Dependency management
345395
├── entrypoint.sh # Docker container initialization script
346396
├── deploy-bobby.sh # Multi-instance deployment script
347397
├── config-wizard.js # Configuration setup wizard
348398
├── Dockerfile # Docker configuration
399+
├── CONTRIBUTING.md # Contribution guidelines
349400
└── README.md # Documentation
350401
```
351402
352-
## Memory Management
403+
## Contributing
404+
405+
Bobby is built with modern JavaScript and Bun runtime. Key components:
353406
354-
Bobby stores information in Markdown files in the `docs/` directory, organized by topic. The `CLAUDE.md` file serves as an index to these memory files, helping Claude find relevant information.
407+
- **Discord.js**: Handles Discord bot interactions and thread management
408+
- **Claude Code CLI**: Powers AI analysis of codebases
409+
- **GitHub CLI**: Creates issues automatically when bugs are detected
410+
- **Bun**: Fast JavaScript runtime for better performance
355411
356-
## Rate Limiting
412+
See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed development guidelines, code architecture, and how to contribute to the project.
357413
358-
Bobby implements rate limiting to prevent abuse:
414+
## Memory Management
359415
360-
- 20 requests per user per hour
361-
- Limits are stored in SQLite database
416+
Bobby stores information in Markdown files in the `docs/` directory, organized by topic. The `CLAUDE.md` file serves as an index to these memory files, helping Claude find relevant information during conversations.
362417
363418
## License
364419
365-
MIT
420+
MIT License - see [LICENSE](LICENSE) file for details.

0 commit comments

Comments
 (0)