Files

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 5 to 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
  • /followups command 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