gh-human-frontier-labs-inc-human-frontier-labs-marketplace-plugins-bubbletea-maintenance/INSTALLATION.md

Installation Guide

Step-by-step guide to installing and using the Bubble Tea Maintenance Agent.

---

Prerequisites

Required:

• Python 3.8+
• Claude Code CLI installed

Optional (for full functionality):

• /Users/williamvansickleiii/charmtuitemplate/charm-tui-template/tip-bubbltea-apps.md
• /Users/williamvansickleiii/charmtuitemplate/charm-tui-template/lipgloss-readme.md

---

Installation Steps

1. Navigate to Agent Directory

cd /Users/williamvansickleiii/charmtuitemplate/vinw/bubbletea-designer/bubbletea-maintenance

2. Verify Files

Check that all required files exist:

ls -la

You should see:

• .claude-plugin/marketplace.json
• SKILL.md
• README.md
• scripts/ directory
• references/ directory
• tests/ directory

3. Install the Agent

/plugin marketplace add .

Or from within Claude Code:

/plugin marketplace add /Users/williamvansickleiii/charmtuitemplate/vinw/bubbletea-designer/bubbletea-maintenance

4. Verify Installation

The agent should now appear in your Claude Code plugins list:

/plugin list

Look for: bubbletea-maintenance

---

Testing the Installation

Quick Test

Ask Claude Code:

"Analyze my Bubble Tea app at /path/to/your/app"

The agent should activate and run a comprehensive analysis.

Detailed Test

Run the test suite:

cd /Users/williamvansickleiii/charmtuitemplate/vinw/bubbletea-designer/bubbletea-maintenance
python3 -m pytest tests/ -v

Expected output:

tests/test_diagnose_issue.py ✓✓✓✓
tests/test_best_practices.py ✓✓✓✓
tests/test_performance.py ✓✓✓✓
tests/test_architecture.py ✓✓✓✓
tests/test_layout.py ✓✓✓✓
tests/test_integration.py ✓✓✓

======================== XX passed in X.XXs ========================

---

Configuration

Setting Up Local References

For full best practices validation, ensure these files exist:

1. tip-bubbltea-apps.md

   ls /Users/williamvansickleiii/charmtuitemplate/charm-tui-template/tip-bubbltea-apps.md
   

   If missing, the agent will still work but best practices validation will be limited.

2. lipgloss-readme.md

   ls /Users/williamvansickleiii/charmtuitemplate/charm-tui-template/lipgloss-readme.md
   

Customizing Paths

If your reference files are in different locations, update paths in:

• scripts/apply_best_practices.py (line 16: TIPS_FILE)

---

Usage Examples

Example 1: Diagnose Issues

User: "My Bubble Tea app is slow, diagnose issues"

Agent: [Runs diagnose_issue()]
Found 3 issues:
1. CRITICAL: Blocking HTTP request in Update() (main.go:45)
2. WARNING: Hardcoded terminal width (main.go:89)
3. INFO: Consider model tree pattern for 18 fields

[Provides fixes for each]

Example 2: Check Best Practices

User: "Check if my TUI follows best practices"

Agent: [Runs apply_best_practices()]
Overall Score: 75/100

✅ PASS: Fast event loop
✅ PASS: Terminal recovery
⚠️  FAIL: No debug message dumping
⚠️  FAIL: No tests with teatest
INFO: No VHS demos (optional)

[Provides recommendations]

Example 3: Comprehensive Analysis

User: "Run full analysis on ./myapp"

Agent: [Runs comprehensive_bubbletea_analysis()]

=================================================================
COMPREHENSIVE BUBBLE TEA ANALYSIS
=================================================================

Overall Health: 78/100
Summary: Good health. Some improvements recommended.

Priority Fixes (5):

🔴 CRITICAL (1):
  1. [Performance] Blocking HTTP request in Update() (main.go:45)

⚠️  WARNINGS (2):
  2. [Best Practices] Missing debug message dumping
  3. [Layout] Hardcoded dimensions in View()

💡 INFO (2):
  4. [Architecture] Consider model tree pattern
  5. [Performance] Cache lipgloss styles

Estimated Fix Time: 2-4 hours

Full report saved to: ./bubbletea_analysis_report.json

---

Troubleshooting

Issue: Agent Not Activating

Solution 1: Check Installation

/plugin list

If not listed, reinstall:

/plugin marketplace add /path/to/bubbletea-maintenance

Solution 2: Use Explicit Activation

Instead of:

"Analyze my Bubble Tea app"

Try:

"Use the bubbletea-maintenance agent to analyze my app"

Issue: "No .go files found"

Cause: Wrong path provided

Solution: Use absolute path or verify path exists:

ls /path/to/your/app

Issue: "tip-bubbltea-apps.md not found"

Impact: Best practices validation will be limited

Solutions:

1. Get the file:

   # If you have charm-tui-template
   ls /Users/williamvansickleiii/charmtuitemplate/charm-tui-template/tip-bubbltea-apps.md
   

2. Update path in scripts/apply_best_practices.py:

   TIPS_FILE = Path("/your/custom/path/tip-bubbltea-apps.md")
   

3. Or skip best practices: The other 5 functions still work without it.

Issue: Tests Failing

Check Python Version:

python3 --version  # Should be 3.8+

Install Test Dependencies:

pip3 install pytest

Run Individual Tests:

python3 tests/test_diagnose_issue.py

Issue: Permission Denied

Solution: Make scripts executable:

chmod +x scripts/*.py

---

Uninstallation

To remove the agent:

/plugin marketplace remove bubbletea-maintenance

Or manually delete the plugin directory:

rm -rf /path/to/bubbletea-maintenance

---

Upgrading

To v1.0.1+

1. Backup your config (if you customized paths)
2. Remove old version:

   /plugin marketplace remove bubbletea-maintenance
   

3. Install new version:

   cd /path/to/new/bubbletea-maintenance
   /plugin marketplace add .
   

4. Verify:

   cat VERSION  # Should show new version
   

---

Support

Issues: Check SKILL.md for detailed documentation

Questions:

• Read references/common_issues.md for solutions
• Check CHANGELOG.md for known limitations

---

Next Steps

After installation:

1. Try it out: Analyze one of your Bubble Tea apps
2. Read documentation: Check references/ for guides
3. Run tests: Ensure everything works
4. Customize: Update paths if needed

---

Built with Claude Code agent-creator on 2025-10-19