sb push UX enhancement

[owenmccadden]

SessionBase CLI UX Enhancement Plan

Current UX Pain Points

Platform Inconsistencies

• QChat: Requires /save command → sessionbase upload [path] OR sessionbase list --qchat (only shows most recent) → copy path → upload
• Claude: sessionbase list --claude → copy path → upload (don't use /export due to lost context)
• Gemini: Either /chat save [filename] → upload OR sessionbase list --gemini → copy path → upload

Key Issues

1. Inconsistent workflows - Each platform requires different approaches
2. Manual path copying - Users must copy/paste file paths from list commands
3. Platform limitations - QChat only shows most recent session, different export behaviors
4. Cognitive overhead - Users must remember different commands for different platforms

Proposed Solutions

Phase 1: Smart Upload + TUI (Quick Win)

New Upload Command Structure

# Primary use case - upload most recent session from platform
sessionbase upload --claude    # Auto-finds most recent Claude session in cwd
sessionbase upload --gemini    # Auto-finds most recent Gemini session in cwd  
sessionbase upload --qchat     # Auto-finds most recent QChat session in cwd

# Explicit file path (power users, automation)
sessionbase upload path/to/session.jsonl
sessionbase upload path/to/session.json

# Error handling
sessionbase upload             # → "Please specify a platform (--claude, --gemini, --qchat) or provide a file path"
sessionbase upload --claude ./session.json  # → "Cannot specify both platform and file path"

Hybrid Command Structure

sessionbase                    # Opens TUI (default - new behavior)
sessionbase list --claude      # CLI list command (existing)
sessionbase upload --claude    # Smart upload command (new primary UX)
sessionbase login             # CLI login command (existing)
sessionbase --help            # CLI help (existing)

TUI Features

• Zero friction entry: Just type sessionbase
• Rich session previews: Show metadata, message counts, tool calls
• Keyboard shortcuts: Arrow keys for navigation, Enter to upload, 'q' to quit
• Platform filtering: Tab between Claude/Gemini/QChat sessions
• Batch operations: Multi-select for bulk uploads
• Full backwards compatibility: All existing CLI commands still work

Implementation Options

• Option 1: ink (React-like TUI framework)
• Option 2: blessed or terminal-kit for more control
• Option 3: Simple inquirer.js for basic selection interface

Entry Point Logic

// In src/index.ts - if no arguments provided, launch TUI
if (process.argv.length === 2) {
  await launchTUI();
  process.exit(0);
}

// Otherwise process CLI commands normally
program.parseAsync(process.argv)

Phase 2: MCP Server Integration (Highest UX Value)

Natural Language Upload

User: "Upload this session to sessionbase"
MCP Server: *detects platform, finds session file, uploads*

User: "Upload this with tags 'debugging, react' and make it private"  
MCP Server: *applies metadata and uploads*

Detection Strategy

1. Platform detection from chat context/environment variables
2. Session matching via session ID or first message hash
3. Timing heuristic (recent file activity within 5 minutes)
4. Fallback prompts if multiple matches found

Technical Challenges

• Session detection in active chat vs completed session files
• Platform detection accuracy across different environments
• Handling edge cases (multiple sessions, interrupted sessions)

Phase 3: Advanced Features + Enhanced CLI

Additional Upload Options

sessionbase upload --interactive              # Numbered selection interface across all platforms
sessionbase upload --select-multiple          # Bulk upload interface

Enhanced List Integration

sessionbase list --claude --upload            # List with upload prompts

Implementation Logic

// Mutually exclusive: platform flags OR file path
.argument('[file]', 'Path to specific session file')
.option('--claude', 'Upload most recent Claude session in current directory')
.option('--gemini', 'Upload most recent Gemini session in current directory') 
.option('--qchat', 'Upload most recent QChat session in current directory')
.action(async (filePath, options) => {
  const platformFlags = [options.claude, options.gemini, options.qchat].filter(Boolean);
  
  if (filePath && platformFlags.length > 0) {
    console.error('Cannot specify both platform and file path');
    process.exit(1);
  }
  
  if (filePath) {
    await uploadFile(filePath, options);
  } else if (platformFlags.length === 1) {
    const recentFile = await findMostRecentSession(options);
    await uploadFile(recentFile, options);
  } else {
    console.error('Please specify a platform (--claude, --gemini, --qchat) or provide a file path');
    process.exit(1);
  }
});

Implementation Priority

Phase 1 (Immediate - High Impact, Low Risk)

• ✅ Smart upload command with platform flags (sessionbase upload --claude)
• ✅ Auto-discovery of most recent sessions in current directory
• ✅ Mutually exclusive platform/file path arguments
• ✅ TUI entry point when no arguments provided
• ✅ Rich session display with metadata
• ✅ Keyboard navigation and shortcuts

Phase 2 (Medium Term - Highest UX Value)

• ✅ MCP server for natural language uploads
• ✅ Session detection and matching logic
• ✅ Platform-aware upload workflows

Phase 3 (Future Enhancement)

• ✅ Advanced CLI shortcuts and smart defaults
• ✅ Comprehensive documentation for each platform
• ✅ Bulk operations and workflow automation

Success Metrics

User Experience

• Reduced friction: Zero copy-paste workflows in TUI mode
• Consistency: Same interface across all platforms
• Discoverability: Clear path for new users (sessionbase → TUI)

Technical Goals

• Backwards compatibility: All existing workflows continue working
• Performance: Fast session listing and uploads
• Reliability: Robust session detection and error handling

Adoption

• Power users: Maintain CLI efficiency for scripting
• Casual users: Intuitive TUI for occasional use
• Active chat users: Seamless MCP integration

Open Questions

1. TUI Framework: Which provides best balance of features vs complexity?
2. MCP Scope: How broad should natural language command support be?
3. Platform Detection: What's the most reliable method for each platform?
4. Error Handling: How to gracefully handle edge cases in automated workflows?
5. Documentation: What's the right balance between docs vs intuitive UX?

Notes

• Most developers typically use one platform primarily - reasonable to expect brief learning curve
• TUI pattern familiar from tools like lazygit, k9s
• MCP integration could be revolutionary for real-time workflow
• Maintain focus on core use case: uploading sessions with minimal friction

[owenmccadden]

Experimented with a TUI here for the list and uploads, see MVP below. To start off, I would rather have a really solid CLI and MCP integration so users can easily upload right from their chats or create shortcuts to easily upload etc.