Huddle

 __ __ __ __ ___   ___   _       ___ 
|  |  |  |  |   \ |   \ | |     /  _]
|  |  |  |  |    \|    \| |    /  [_ 
|  _  |  |  |  D  |  D  | |___|    _]
|  |  |  :  |     |     |     |   [_ 
|  |  |     |     |     |     |     |
|__|__|\__,_|_____|_____|_____|_____|

A sophisticated terminal-based chat application that enables multi-bot conversations with AI assistants. Built with Go and Bubble Tea, Huddle provides a rich TUI experience for managing discussions with specialized AI bots and custom commands.

Features

🤖 Multi-Bot Conversations

• Specialized AI Bots: Pre-configured bots with specific expertise (Product Manager, Senior Developer, UX Designer)
• Intelligent Response Strategy: AI-powered analysis determines which bots should respond based on conversation context
• JSON-Structured Communication: Prevents multi-persona responses and ensures consistent bot behavior
• Dynamic Bot Management: Add/remove bots from discussions with real-time UI updates

💬 Advanced Chat Interface

• Rich TUI: Beautiful terminal interface with panels for discussions, chat, and participants
• Syntax Highlighting: Code blocks are automatically highlighted using Chroma
• Message History: Persistent SQLite database stores all conversations
• Real-time Indicators: Visual feedback for bot thinking and response states

⚡ Command System

Comprehensive slash command system inspired by Claude Code:

Built-in Commands

• /help - Show available commands and usage
• /clear - Clear current discussion messages
• /export [format] - Export discussion to markdown, JSON, or text
• /info - Show discussion and system statistics
• /quit - Exit application

Custom Commands

Create your own commands using Markdown files with YAML frontmatter:

---
description: Show system status and current time
usage: /status
---

# System Status

**Current Time:** $TIME $DATE
**Active Discussion:** $DISCUSSION
**User:** $USER

$ uptime
$ df -h

Features:

• YAML frontmatter for metadata
• Variable substitution ($TIME, $DATE, $DISCUSSION, $USER, $1, $2, etc.)
• Shell command execution with enhanced formatting
• Automatic command discovery from .huddle/commands/

🎨 Enhanced Formatting

• Charm Integration: Beautiful styling using Lip Gloss and Glamour
• Command Output: Styled terminal output with borders, colors, and proper spacing
• Responsive Layout: Adapts to terminal size changes
• Mouse Support: Click to focus panels and interact with UI elements

🛠 Technical Features

• Go + Bubble Tea: Modern TUI framework for responsive interfaces
• SQLite Database: Reliable local storage for conversations
• Modular Architecture: Clean separation of concerns with dedicated packages
• Error Handling: Comprehensive error handling with user-friendly messages
• Concurrent Processing: Multi-bot responses handled efficiently

Installation

Prerequisites

• Go 1.21 or higher
• Terminal with mouse support (recommended)

Build from Source

git clone https://github.com/scottharvey/huddle.git
cd huddle
go build .
./huddle

Usage

Getting Started

1. Launch Huddle: Run ./huddle in your terminal
2. Create Discussion: Use [+ New Discussion] or start typing a message
3. Add Bots: Select bots from the Available Bots panel
4. Start Chatting: Type your message and press Enter

Keyboard Shortcuts

• Tab - Switch between panels
• ↑/↓ or j/k - Navigate lists
• Enter - Send message or select item
• Esc or Ctrl+C - Quit application
• d - Delete discussion (in discussions panel)
• r - Rename discussion (in discussions panel)

Panel Navigation

• Discussions: Manage conversation threads
• Chat: View messages and bot responses
• Participants: Add/remove bots from discussions
• Input: Type messages and commands

Custom Commands

Create custom commands by adding Markdown files to .huddle/commands/:

1. Create command file: .huddle/commands/mycommand.md
2. Add YAML frontmatter with description and usage
3. Write command content with variables and shell commands
4. Use command: Type /mycommand in chat

Example commands included:

• /status - System information and resource usage
• /brainstorm <topic> - Start brainstorming session
• /summarize - Summarize current discussion

Configuration

Bot Configuration

Bots are defined in bots/ directory with JSON configurations and markdown prompts:

bots/
├── sarah/
│   ├── config.json      # Bot metadata and capabilities
│   └── prompt.md        # System prompt and personality
├── alex/
│   ├── config.json
│   └── prompt.md
└── jordan/
    ├── config.json
    └── prompt.md

Environment Variables

Create a .env file for configuration:

# AI API Configuration
OPENAI_API_KEY=your_api_key_here
CLAUDE_API_KEY=your_claude_key_here

# Database Configuration
DB_PATH=./huddle.db

# Debug Mode
DEBUG=false

Development

Project Structure

huddle/
├── internal/
│   ├── ai/           # LLM integration and strategy analysis
│   ├── bot/          # Bot management and definitions
│   ├── commands/     # Command system implementation
│   ├── config/       # Configuration management
│   ├── db/           # Database operations
│   ├── tui/          # Terminal UI components
│   └── types/        # Common data structures
├── bots/             # Bot configurations and prompts
├── .huddle/
│   └── commands/     # Custom user commands
└── main.go

Adding New Bots

1. Create bot directory in bots/
2. Add config.json with bot metadata
3. Create prompt.md with system prompt
4. Bot will be automatically discovered

Contributing

1. Fork the repository
2. Create feature branch: git checkout -b feature/amazing-feature
3. Commit changes: git commit -m 'Add amazing feature'
4. Push to branch: git push origin feature/amazing-feature
5. Open Pull Request

Examples

Multi-Bot Product Discussion

You: I need to design a new mobile app feature for task management

Sarah (Product Manager): Let me break down the requirements...
Alex (Senior Developer): From a technical perspective, we'll need...
Jordan (UX Designer): For the user experience, I'd recommend...

Custom Command Usage

/status
# Shows system status with current time, uptime, and disk usage

/brainstorm mobile app features
# Starts structured brainstorming session

/export markdown
# Exports current discussion to markdown file

License

MIT License - see LICENSE file for details.

Acknowledgments

• Bubble Tea - Excellent TUI framework
• Lip Gloss - Terminal styling
• Chroma - Syntax highlighting
• Claude Code - Command system inspiration

---

Built with ❤️ using Go and the Charm ecosystem