Skip to content

PROJECT_SPEC.md

Latest commit

 

History

History
348 lines (256 loc) · 10.6 KB

PROJECT_SPEC.md

File metadata and controls

348 lines (256 loc) · 10.6 KB

Project Overview

Huddle is a terminal-based application for having focused discussions with AI-powered bots representing different company roles (CTO, CFO, CMO). Users can create discussion threads, invite relevant bots, and watch as they collaborate to provide comprehensive insights.

Core Concept

  • Discussions - Focused conversations about specific topics (not "channels")
  • Virtual leadership team - Bots act as C-suite executives with distinct personalities
  • Transparent collaboration - See when bots search the web or consult each other
  • Single binary - Everything in one Go executable, following Charm's design philosophy

Technical Requirements

Stack

  • Language: Go
  • TUI Framework: Bubble Tea, Lip Gloss, Bubbles
  • Database: SQLite (embedded via modernc.org/sqlite)
  • AI Providers: OpenRouter API (remote), Ollama (local - future)
  • Tools: DuckDuckGo search API, File system (read-only)

Architecture Principles

  • Single repository, single binary
  • TUI owns all state
  • Configuration via YAML files
  • First-person bot responses ("I think..." not "The CTO thinks...")
  • Visible tool usage (users see when bots search/read files)
  • Show errors explicitly, let user retry (no automatic fallbacks)

Visual Design

Layout

┌─Discussions──────────┬─────────────────────────────────────┐
│ # product-launch     │ Alex (CTO): I think we should       │
│ = strategy-2024      │ prioritize the API refactor first...│
│ ◉ Alex (CTO)         │                                     │
│ ○ Sarah (CFO)        │ Sarah (CFO): I agree, but we need   │
│ ● infrastructure     │ to keep the budget under $50k...    │
│                      │                                     │
│ [+ New Discussion]   │ 🔍 Alex is searching for similar    │
│                      │ refactoring costs...                │
└──────────────────────┴─────────────────────────────────────┘
│ Ask a question...                                          │
└────────────────────────────────────────────────────────────┘

Visual Conventions

  • # = Group discussion with multiple bots
  • = = Direct discussion with single bot
  • ● = Active/current discussion
  • ◉ = Bot online/available
  • ○ = Bot offline/unavailable
  • Each bot has a unique color (Alex=Cyan, Sarah=Green, Jordan=Magenta)

Default Bots

Alex - CTO

  • Color: Cyan
  • Personality: Technical, pragmatic, detail-oriented
  • Expertise: Architecture, scaling, security, team management, technical debt
  • Can consult: Sarah (for budget), Jordan (for product-market fit)

Sarah - CFO

  • Color: Green
  • Personality: Analytical, conservative, strategic
  • Expertise: Budget, runway, unit economics, fundraising, financial planning
  • Can consult: Alex (for tech costs), Jordan (for CAC/LTV)

Jordan - CMO

  • Color: Magenta
  • Personality: Creative, enthusiastic, customer-focused
  • Expertise: Positioning, brand strategy, growth, customer acquisition
  • Can consult: Sarah (for budget), Alex (for product capabilities)

Phase 1: Foundation (Implement This First)

Goal

Create a working TUI with basic message display and a single functioning bot (Alex/CTO).

File Structure

huddle/
├── main.go
├── go.mod
├── go.sum
├── README.md
├── internal/
│   ├── tui/
│   │   ├── model.go       # Main Bubble Tea model
│   │   ├── views/
│   │   │   ├── discussions.go  # Left panel - discussion list
│   │   │   ├── chat.go        # Right panel - chat messages
│   │   │   └── input.go       # Bottom input area
│   │   ├── styles/
│   │   │   └── theme.go       # Lip Gloss styles (Charm defaults)
│   │   └── keys.go        # Keyboard bindings
│   ├── bot/
│   │   ├── bot.go         # Bot interface and types
│   │   └── manager.go     # Bot lifecycle management
│   ├── ai/
│   │   └── openrouter.go  # OpenRouter API client
│   └── types/
│       ├── discussion.go  # Discussion struct
│       └── message.go     # Message struct
└── config/
    └── huddle.yaml        # Bot definitions and global context

Core Components to Implement

1. Main Application (main.go)

// Pseudocode structure
func main() {
    // Initialize the TUI model
    // Create Bubble Tea program with alt screen
    // Run the program
}

2. TUI Model (internal/tui/model.go)

  • Manage three views: discussions list, chat, input
  • Handle navigation between panels (Tab key)
  • Process user input and bot responses
  • Update view states

3. Discussion List View (internal/tui/views/discussions.go)

  • Show list of discussions with icons (#, =, ●)
  • Highlight active discussion
  • Handle up/down navigation
  • Show "+ New Discussion" option

4. Chat View (internal/tui/views/chat.go)

  • Display messages with bot names and colors
  • Show tool usage indicators (🔍 searching, 📁 reading file)
  • Auto-scroll to latest message
  • Support multi-line messages

5. Input View (internal/tui/views/input.go)

  • Text input using bubbles/textinput or textarea
  • Send on Enter (Shift+Enter for newline)
  • Clear after sending

6. OpenRouter Client (internal/ai/openrouter.go)

  • HTTP client for OpenRouter API
  • Handle API key from environment variable
  • Stream responses (if possible) or return complete
  • Error handling with clear messages

7. Message Types (internal/types/message.go)

type Message struct {
    ID           string
    DiscussionID string
    BotID        string    // "user" for user messages
    BotName      string    // "Alex", "Sarah", "Jordan", or "You"
    Content      string
    Timestamp    time.Time
    ToolUse      *ToolUse  // Optional tool usage info
}

type ToolUse struct {
    Type    string // "web_search", "file_read"
    Query   string // Search query or file path
    Status  string // "searching", "complete", "error"
}

Success Criteria for Phase 1

  • Can launch app and see the TUI with three panels
  • Can navigate between panels with Tab
  • Can create a new discussion
  • Can type messages and see them in chat
  • Alex (CTO) bot responds with real AI responses via OpenRouter
  • Bot responses are colored cyan
  • Clean error handling when API fails
  • Can quit with Ctrl+C or q

Implementation Notes

Styling

  • Use Charm's default styling patterns (see Pop for reference)
  • Keep it simple - focus on readability
  • Use Lip Gloss for colors and borders
  • Default terminal colors where possible

State Management

  • TUI model owns all state
  • No global variables
  • Pass state through Bubble Tea's Update/View pattern

Initial Hardcoded Config

For Phase 1, hardcode the bot configuration:

var alexBot = Bot{
    ID:    "cto",
    Name:  "Alex",
    Role:  "CTO",
    Color: "cyan",
    SystemPrompt: `You are Alex, the CTO of a tech startup. 
    You are technical, pragmatic, and detail-oriented. 
    You care about architecture, scaling, and code quality.
    Respond in first person.`,
}

Environment Variables

OPENROUTER_API_KEY="sk-or-v1-..."  # Required
HUDDLE_MODEL="anthropic/claude-3-opus" # Default model

Phase 2: Multi-Bot & Persistence (Future)

Additional Features

  • SQLite persistence for discussions and messages
  • Multiple bots (Sarah/CFO, Jordan/CMO)
  • Bot-to-bot consultation
  • Discussion management (create, delete, rename)
  • Global context from YAML config

Phase 3: Tools & Polish (Future)

Additional Features

  • DuckDuckGo web search integration
  • File system reading (sandboxed)
  • Visible tool usage in chat
  • Message history search
  • Export discussions to markdown

Development Setup

Initialize Project

go mod init github.com/yourusername/huddle

# Core dependencies
go get github.com/charmbracelet/bubbletea
go get github.com/charmbracelet/lipgloss
go get github.com/charmbracelet/bubbles

# For Phase 1
go get github.com/joho/godotenv  # For .env file support

Environment Setup

Create .env file:

OPENROUTER_API_KEY=sk-or-v1-your-key-here

Run Commands

# Run the app
go run .

# Build binary
go build -o huddle

# Install globally
go install

Reference Implementations

  1. Pop (Charm's email client): https://github.com/charmbracelet/pop

    • Excellent reference for panel layout and navigation
    • Similar split-view architecture

  2. Mods (CLI AI tool): https://github.com/charmbracelet/mods

    • Reference for AI integration patterns
    • OpenAI API client implementation

  3. Bubble Tea Examples: https://github.com/charmbracelet/bubbletea/tree/master/examples

    • chat-server example for message handling
    • split-editors example for panel management

Testing Phase 1

Manual test flow:

  1. Launch huddle
  2. See empty discussions list with "+ New Discussion"
  3. Press Enter to create new discussion
  4. Type "What's the best way to structure a Go project?"
  5. See message appear in chat
  6. See "Alex is typing..." indicator
  7. Receive thoughtful technical response from Alex
  8. Type follow-up question
  9. Verify conversation flows naturally
  10. Press 'q' to quit

Important Notes for Implementation

  1. Start Simple: Phase 1 is just about getting a working TUI with one bot. Don't over-engineer.

  2. No Database Yet: Keep messages in memory for Phase 1. Persistence comes later.

  3. Hardcode for Speed: Hardcode Alex's configuration initially. YAML config comes later.

  4. Error Messages: Show clear error messages in the chat when OpenRouter fails. No panic/crash.

  5. Follow Charm Patterns: Look at Pop's code structure and styling. Huddle should feel like a Charm app.

  6. Test with Real API: Make sure to test with actual OpenRouter API responses early.

Implementation Instructions for Claude Code

Please implement Phase 1 as described above. Focus on:

  1. Getting the basic TUI working with three panels
  2. Message sending and display
  3. Integration with OpenRouter API for Alex (CTO) bot
  4. Clean, idiomatic Go code following Charm's patterns

Start with the file structure outlined above and build incrementally. The goal is a working demo where you can have a real conversation with Alex about technical topics.