6.8 KiB
๐ง Internal Development Notes
This document captures the development history, design decisions, and architecture of the Smart Follow-ups skill.
Created: January 20, 2026
Author: Cami (Bot) with Robby
Status: v1.0.0 - Ready for testing
๐ Development History
Origin
The Smart Follow-ups skill was inspired by Chameleon AI Chat, Robby's open-source AI chat application. Chameleon features a "Smart Follow-up Suggestions" system that generates contextual follow-up questions after every AI response.
Robby wanted to bring this feature to Bot as a standalone skill that could work across multiple messaging channels.
Initial Specification (from Chameleon)
Chameleon's original implementation:
- 6 suggestions total (2 per category)
- Three categories: Quick (green), Deep Dive (purple), Related (blue)
- Mobile-optimized with clickable suggestions
- AI-generated based on conversation context
Design Decisions
1. Reduced to 3 suggestions (from 6)
Decision: 1 suggestion per category instead of 2
Rationale (from Robby):
"Make 3 instead of 6 for here makes more sense, 6 is too much"
Benefits:
- Cleaner mobile UX
- Less overwhelming
- Faster to scan and decide
- Each suggestion is more focused/high-quality
2. Bot Native Auth as Default
Decision: Use Bot's existing authentication by default, not separate API keys
Robby's requirement:
"Follow ups skill should use the exact same login and model and authentication... we use as auth anthropic Claude CLI token NOT Openrouter"
Implementation:
- Default
provider: "bot"uses current session's model and auth - OpenRouter and direct Anthropic are optional fallbacks
- No separate API key required for default mode
3. Model Inheritance
Decision: Follow-ups use the same model as the current chat session
Robby's requirement:
"Default should use the model the user is using for chat"
Implementation:
- If chatting with Opus โ follow-ups use Opus
- If chatting with Sonnet โ follow-ups use Sonnet
- If chatting with Haiku โ follow-ups use Haiku
- Configurable override available
4. Manual Trigger (not auto)
Decision: Use /followups command, not automatic after every response
Rationale:
- User controls when they want suggestions
- No spam/clutter
- Lower API costs
- Can add auto-trigger as optional feature later
๐๏ธ Architecture
Handler-Based Integration
The skill works by returning a prompt to Bot's agent system:
User types /followups
โ
Handler receives command
โ
Handler returns agent-prompt type response
โ
Bot agent generates follow-ups using current model/auth
โ
Handler transforms response to buttons/text
โ
Sent to user
Why this approach:
- No separate API calls from the skill
- Uses Bot's existing infrastructure
- Inherits session model and authentication
- Consistent with Bot's architecture
CLI Tool (Fallback/Testing)
The CLI exists for:
- Standalone testing
- Users who want to use OpenRouter/Anthropic directly
- Scripting/automation use cases
CLI receives context JSON
โ
Makes API call (OpenRouter or Anthropic)
โ
Parses response
โ
Formats output (json/telegram/text/compact)
๐ง Technical Notes
OpenRouter Model IDs
OpenRouter uses different model ID format:
- โ
anthropic/claude-sonnet-4.5(dot) - โ
anthropic/claude-sonnet-4-5(dash)
Discovered during testing when claude-sonnet-4-5 returned "not a valid model ID" error.
Telegram Callback Data Limit
Telegram inline buttons have a 64-byte limit for callback_data. Questions are truncated if needed:
callback_data: suggestions.quick.substring(0, 50)
readme.md Domain Issue
During development, we discovered that typing "readme.md" in messages caused Telegram to show spam link previews. This is because readme.md is an actual registered domain (Moldova TLD) that redirects to a spam site:
readme.md โ 302 redirect โ dealsbe.com (spam)
Not a security issue โ just unfortunate domain squatting. Telegram auto-generates link previews for text that looks like URLs.
๐ File Structure
| File | Purpose | Audience |
|---|---|---|
README.md |
Public documentation | Users, Skills |
SKILL.md |
Bot skill manifest | Bot |
FAQ.md |
Common questions | Users |
INTERNAL.md |
This file - dev notes | Developers |
handler.js |
Command handler | Bot |
cli/followups-cli.js |
Standalone CLI | Power users |
CHANGELOG.md |
Version history | Users, devs |
CONTRIBUTING.md |
Contribution guide | Contributors |
LICENSE |
MIT License | Legal |
๐ฎ Future Improvements
Short-term
- Add auto-trigger mode (configurable)
- Support custom prompts/categories
- Add
/followups 5to specify number - Cache recent suggestions to avoid regeneration
Medium-term
- Support for follow-up chains (click suggestion โ new suggestions)
- Category customization (add/remove categories)
- Integration with Bot memory (suggest based on past conversations)
Long-term
- Multi-language support
- Learning from user preferences (which categories they click most)
- Context-aware auto-trigger (only suggest when conversation seems stuck)
๐งช Testing Checklist
- CLI help command works
- CLI generates valid JSON output
- CLI generates valid Telegram buttons
- CLI text mode formatting correct
- OpenRouter API integration works
- Model ID format correct for OpenRouter
- Handler integration with Bot
/followupscommand registered- Telegram buttons clickable and functional
- Signal/iMessage text fallback works
๐ Cost Analysis
| Model | Cost per Generation | Notes |
|---|---|---|
| Claude 3 Haiku | ~$0.0002 | Cheapest, good quality |
| Claude Sonnet 4.5 | ~$0.003 | Default for Bot |
| Claude Opus 4.5 | ~$0.015 | Highest quality |
Recommendation: For cost-conscious users, configure OpenRouter with Haiku specifically for follow-ups while keeping main chat on Sonnet/Opus.
๐ฃ๏ธ Key Quotes from Development
On button count:
"Make 3 instead of 6 for here makes more sense 6 is too much" โ Robby
On authentication:
"Follow ups skill should use the exact same login and model and authentication... NOT Openrouter but yeah make Openrouter a configurable option if you want" โ Robby
On model consistency:
"Default should use the model the user is using for chat" โ Robby
๐ Changelog Summary
v1.0.0 (2026-01-20)
- Initial release
- 3 suggestions (Quick, Deep, Related)
- Bot native auth as default
- OpenRouter and Anthropic as optional providers
- CLI tool for standalone use
- Multi-channel support (buttons + text fallback)
Last updated: January 20, 2026