abyss-ai/src/cli/cmd/help.ts

Autonomous AI coding agent - enhanced OpenCode with autonomous capabilities

import { cmd } from "./cmd"
import * as prompts from "@clack/prompts"
import { UI } from "../ui"

// Enhanced Help Command
export const HelpCommand = cmd({
  command: "help [topic]",
  describe: "get help with Abyss features and commands",
  builder: (yargs) =>
    yargs
      .positional("topic", {
        type: "string",
        describe: "specific help topic",
        choices: ["basics", "files", "modes", "keybinds", "agents", "config", "troubleshooting"],
      }),
  async handler(args) {
    UI.empty()
    
    if (!args.topic) {
      await showMainHelp()
    } else {
      await showTopicHelp(args.topic as string)
    }
  },
})

async function showMainHelp() {
  prompts.intro("🚀 Abyss Help - Autonomous AI Coding Agent")
  
  console.log(`
Abyss is an autonomous AI-powered coding agent that works without permission prompts.

📚 **Quick Start:**
  abyss                       Start interactive TUI mode  
  abyss run "message"         Send a message directly
  abyss help basics           Learn the fundamentals

🚀 **Autonomous Features (within TUI):**
  Use the 'yolo' tool for autonomous analysis
  Use the 'memory' tool to view learning patterns

🎯 **Popular Topics:**
  abyss help basics           Essential concepts and workflows
  abyss help files            File operations and attachments
  abyss help modes            Plan vs Build vs Autonomous modes
  abyss help keybinds         Keyboard shortcuts
  abyss help agents           Custom agents and configuration
  abyss help config           Configuration options
  abyss help troubleshooting  Common issues and solutions

🔗 **Resources:**
  • Documentation: https://github.com/sst/abyss
  • GitHub: https://github.com/sst/abyss
  • Original Project: https://github.com/sst/opencode

💡 **Pro Tip:** Use 'abyss' to start interactive mode, then use autonomous tools like
    'yolo' and 'memory' for AI assistance without permission prompts!
`)

  prompts.outro("Happy coding! 🎉")
}

async function showTopicHelp(topic: string) {
  prompts.intro(`📖 OpenCode Help: ${topic}`)
  
  switch (topic) {
    case "basics":
      console.log(`
🎯 **OpenCode Basics**

**Core Concepts:**
• OpenCode is an AI assistant that can read, write, and edit your code
• It works best when you provide context about what you want to achieve
• You can reference files using @ symbol for quick access

**Essential Workflow:**
1. Start OpenCode in your project directory: 'opencode'
2. Initialize your project: type '/init' in the chat
3. Ask questions or request changes in natural language
4. Use Plan mode (Tab) to discuss before Build mode implements

**Key Features:**
• 📁 File Operations: Read, write, edit files automatically
• 🔍 Code Analysis: Understand and explain your codebase
• 🛠️ Code Generation: Create new features and functions
• 🔧 Debugging: Find and fix issues in your code
• 📋 Documentation: Generate docs and comments

**Best Practices:**
• Be specific about what you want to achieve
• Provide context about your project and constraints
• Use Plan mode to iterate on ideas before implementing
• Reference specific files with @ when discussing code
`)
      break

    case "files":
      console.log(`
📁 **File Operations**

**Referencing Files:**
• Type '@' to open fuzzy file search
• @filename - Reference a specific file
• Drag & drop files directly into the chat
• Paste file paths for quick access

**Supported Operations:**
• Read: OpenCode can read and understand any text file
• Write: Create new files with generated content
• Edit: Modify existing files with precise changes
• List: Browse directory contents
• Search: Find files and content using patterns

**File Attachments:**
• Drag images (PNG, JPEG, etc.) for visual context
• Copy file paths and paste them
• Use file:// URLs for specific file references

**Pro Tips:**
• Use @package.json to quickly reference your dependencies
• Attach multiple files when discussing related components
• OpenCode tracks file changes to prevent conflicts
`)
      break

    case "modes":
      console.log(`
🎯 **Plan vs Build Modes**

**Plan Mode** (Press Tab to switch):
• 📋 Design and discuss solutions before implementation
• Iterate on approaches without making changes
• Get recommendations and explore options
• Perfect for complex features or architectural decisions

**Build Mode** (Press Tab to switch):
• 🛠️ Direct code implementation and modifications
• File creation, editing, and deletion
• Running commands and tests
• Active development work

**When to Use Each:**
Plan Mode:
• "How should I structure this new feature?"
• "What's the best approach for authentication?"
• "Review this architecture design"

Build Mode:
• "Implement the user login system"
• "Fix the bug in the payment handler"
• "Add tests for the new component"

**Mode Indicators:**
• Look for the mode indicator in the TUI
• Tab key switches between modes instantly
• Different tool permissions in each mode
`)
      break

    case "keybinds":
      console.log(`
⌨️ **Keyboard Shortcuts**

**Leader Key:** Ctrl+X (customizable)

**Essential Shortcuts:**
• Ctrl+X H      Show help dialog
• Ctrl+X E      Open external editor
• Ctrl+X N      New session
• Ctrl+X L      List all sessions
• Ctrl+X S      Share current session
• Ctrl+X I      Initialize project (/init)
• Ctrl+X M      List available models
• Ctrl+X T      List themes
• Ctrl+X F      File browser
• Tab           Switch modes (Plan ↔ Build)
• Shift+Tab     Switch modes (reverse)
• Esc           Interrupt/cancel

**Input Controls:**
• Ctrl+C        Clear input
• Up/Down       Navigate message history
• Ctrl+P/N      Navigate history (vim-style)

**Customization:**
• Edit keybinds in your opencode.json config
• Use 'opencode help config' for configuration options
`)
      break

    case "agents":
      console.log(`
🤖 **Custom Agents**

**What are Agents?**
• Specialized AI assistants for specific tasks
• Custom prompts and tool access
• Project-specific or global scope

**Creating Agents:**
• opencode agent create - Interactive agent creation
• Define agent description and capabilities
• Choose which tools the agent can use

**Agent Configuration:**
Agents are stored as Markdown files with YAML frontmatter:

\`\`\`yaml
---
description: "Specialized code reviewer"
model: "anthropic/claude-3-5-sonnet-20241022"
tools:
  read: true
  write: false
  bash: false
---

You are a code review specialist focused on...
\`\`\`

**Using Agents:**
• Use the 'task' tool to delegate work to specialized agents
• Agents can work autonomously within their permissions
• Great for focused tasks like testing, documentation, or security review

**Agent Locations:**
• Global: ~/.config/opencode/agent/
• Project: .opencode/agent/
`)
      break

    case "config":
      console.log(`
⚙️ **Configuration**

**Config File Locations:**
• Global: ~/.config/opencode/opencode.json
• Project: ./opencode.json or ./opencode.jsonc

**Common Settings:**
\`\`\`json
{
  "provider": {
    "anthropic": { "model": "claude-3-5-sonnet-20241022" },
    "openai": { "model": "gpt-4" }
  },
  "share": "manual",
  "keybinds": {
    "leader": "ctrl+x",
    "app_help": "<leader>h"
  },
  "agent": {
    "my-reviewer": {
      "description": "Code review specialist",
      "tools": { "write": false }
    }
  }
}
\`\`\`

**Authentication:**
• opencode auth login - Set up API keys
• Supports multiple providers: Anthropic, OpenAI, Google, etc.
• Keys stored securely in system keychain

**Model Selection:**
• opencode models - List available models
• Configure preferred models per provider
• Override models per agent or session
`)
      break

    case "troubleshooting":
      console.log(`
🔧 **Troubleshooting**

**Common Issues:**

**Installation Problems:**
• Windows: Download binary from GitHub releases
• macOS: Use Homebrew or install script
• Linux: Install script or package managers

**Copy/Paste Issues (Linux):**
• Install: xclip, xsel (X11) or wl-clipboard (Wayland)
• Headless: Install xvfb for virtual display

**File Access Errors:**
• Check file permissions
• Ensure OpenCode has read/write access to project directory
• Verify file paths are correct (case-sensitive on Linux/macOS)

**API/Model Errors:**
• Run 'opencode auth login' to set up API keys
• Check API key validity and quotas
• Try different models if one is unavailable

**Performance Issues:**
• Large files may be chunked automatically
• Use specific file references (@filename) instead of broad requests
• Consider using Plan mode for complex discussions

**Getting Help:**
• Check logs: ~/.local/share/opencode/log/
• Report issues: https://github.com/sst/opencode/issues
• Join Discord: https://opencode.ai/discord

**Debug Commands:**
• opencode debug - Various debugging utilities
• Check system status and health
`)
      break

    default:
      console.log(`Unknown help topic: ${topic}`)
      console.log(`Available topics: basics, files, modes, keybinds, agents, config, troubleshooting`)
  }
  
  prompts.outro("Need more help? Visit https://opencode.ai/docs")
}