sophia-code/SOPHIA_CLI_GUIDE.md

Production-ready agentic CLI code editor with AI-powered coding assistance, planning, and multi-agent delegation. Enterprise-grade security and reliability.

# 🤖 Sophia CLI Guide

Sophia is the interactive command-line interface for Sophosic-Coder, providing a ChatGPT-like experience directly in your terminal.

## 🚀 Quick Start

### 1. Installation

**Local Usage (from project directory):**
```bash
# Setup environment
./setup.sh

# Run locally
source .venv/bin/activate
PYTHONPATH=src python src/cli.py
```

**Global Installation:**
```bash
# Install sophia command globally
./install.sh

# Or using make
make install-global

# Now use from anywhere
sophia
```

### 2. Set API Key

```bash
export GROQ_API_KEY="your_groq_api_key_here"
```

### 3. Start Coding!

```bash
sophia
```

## 🎯 Features

### Interactive Chat Interface
- **Real-time streaming responses** - See AI responses as they're generated
- **Conversation history** - Maintains context across the session
- **Auto-save** - Your conversations are automatically saved
- **Readline support** - Command history with up/down arrows

### Built-in Commands
```
/help     - Show help and usage information
/clear    - Clear conversation history
/config   - Show current configuration
/history  - Show recent conversation history
/model    - Change AI model
/sessions - List saved sessions
/switch <id> - Switch to another session
/compress - Summarize long history
/goal    - Manage session goals
/plan    - Generate or run a task plan
/edit     - Apply AI-generated patches to files
/exit     - Exit Sophia (or Ctrl+C)
```

### Planning & Goals
Sophia can remember your objectives and help execute multi-step tasks.

- `/goal add <text>` records a goal
- `/goal list` shows current goals
- `/goal clear` removes all goals
- `/plan <task>` asks Sophia to outline numbered steps
- `/plan run` executes those steps one at a time with your confirmation

### External Information Tools
Sophia can pull in data from the web using plugin commands. These tools can be
invoked manually or automatically when the assistant responds with a line
starting with `TOOL:`.

```
/http <url>                - Fetch the contents of a URL
/search <query>            - Search the web and return top results
/github_issue owner repo n - Show a GitHub issue's title and body
```

To supply a GitHub token for private repositories or higher rate limits, set:

```bash
export GITHUB_TOKEN="your_token_here"
```

### Session Management
- **Persistent sessions** - Conversations saved to `~/.sophia/sessions/<id>.jsonl`
- **Configurable settings** - Stored in `~/.sophia/config.json`
- **Multiple models** - Switch between different AI models
- **Temperature control** - Adjust creativity vs consistency

## 📋 Usage Examples

### Basic Coding Help
```
👤 You: write a Python function to calculate fibonacci numbers

🤖 Sophia: Here's an efficient Python function to calculate Fibonacci numbers:

def fibonacci(n):
    """Calculate the nth Fibonacci number."""
    if n <= 1:
        return n
    
    a, b = 0, 1
    for _ in range(2, n + 1):
        a, b = b, a + b
    
    return b
```

### Code Review
```
👤 You: Review this code: [paste your code]

🤖 Sophia: I'll review your code for potential issues and improvements...
```

### Debugging Help
```
👤 You: I'm getting this error: TypeError: 'NoneType' object is not subscriptable

🤖 Sophia: This error typically occurs when you're trying to access an index or key on a None value...
```

### Multi-language Support
```
👤 You: Convert this Python code to JavaScript: [code]

🤖 Sophia: Here's the JavaScript equivalent...
```

## ⚙️ Configuration

### View Current Config
```bash
sophia --config
```

### Configuration File (`~/.sophia/config.json`)
```json
{
  "model": "openai/gpt-oss-120b",
  "temperature": 0.7,
  "max_tokens": 4096,
  "system_message": "You are Sophia, an AI coding assistant...",
  "auto_save_history": true
}
```

### Available Models
- `openai/gpt-oss-120b` (default) - Best for coding tasks
- `llama-3.2-90b-text-preview` - Good for general coding
- `mixtral-8x7b-32768` - Fast responses

### Change Model During Session
```
/model
# Then select from the available options
```

## 🔧 Advanced Usage

### AI-Driven File Editing
Use `/edit <files...>: <instruction>` to have Sophia generate a unified diff and apply it to the specified files. Review the diff before confirming and optionally commit the result.

### Command Line Options
```bash
sophia --help           # Show help
sophia --version        # Show version
sophia --config         # Show configuration
sophia --clear-history  # Clear conversation history
```

### Environment Variables
```bash
# Required
export GROQ_API_KEY="your_api_key"

# Optional
export SOPHIA_MODEL="openai/gpt-oss-120b"
```

### Session Files
```
~/.sophia/
├── config.json        # Configuration settings
├── history.jsonl      # Conversation history
└── readline_history   # Command line history
```

## 🎨 Customization

### Custom System Message
Edit `~/.sophia/config.json`:
```json
{
  "system_message": "You are a senior Python developer specializing in web development..."
}
```

### Adjust Response Style
```json
{
  "temperature": 0.3,  # More focused responses
  "max_tokens": 8192   # Longer responses
}
```

## 🛠️ Troubleshooting

### Common Issues

**"API key not found"**
```bash
# Make sure to set your API key
export GROQ_API_KEY="your_api_key_here"

# Check if it's set
echo $GROQ_API_KEY
```

**"Command not found: sophia"**
```bash
# Reinstall globally
./install.sh

# Or check your PATH
echo $PATH
```

**"Import error"**
```bash
# Make sure dependencies are installed
./setup.sh
source .venv/bin/activate
```

### Reset Configuration
```bash
# Clear all history and config
sophia --clear-history
rm ~/.sophia/config.json
```

### Debug Mode
```bash
# Run with verbose output
PYTHONPATH=src python src/cli.py --config
```

## 🤝 Integration with Existing Tools

### With Make Commands
```bash
# Use alongside existing tools
make run-example PROMPT="your prompt"
sophia  # Then continue in interactive mode
```

### With Scripts
```bash
# Use Sophia for research, then implement
sophia
# Ask questions, get code examples
# Then use the knowledge in your scripts
```

## 💡 Tips & Best Practices

### Effective Prompting
- **Be specific**: "Write a Python FastAPI endpoint for user authentication" vs "Write an API"
- **Include context**: "In my React app, how do I..." 
- **Ask for explanations**: "Explain why this code is better..."

### Session Management
- Use `/sessions` to view saved sessions
- Use `/switch <id>` to jump between sessions
- Use `/clear` for new topics to avoid context mixing
- Check `/history` to see what context you have
- Save important conversations externally for reference

### Model Selection
- **gpt-oss-120b**: Best for complex coding tasks
- **llama models**: Good for general programming help  
- **mixtral**: Fast for quick questions

## 🚀 What's Next?

Sophia is designed to be your coding companion. Use it for:

- **Learning**: Ask about new concepts and best practices
- **Debugging**: Get help with error messages and issues
- **Code Review**: Get feedback on your implementations
- **Architecture**: Discuss design patterns and approaches
- **Problem Solving**: Break down complex coding challenges

---

**Happy Coding with Sophia! 🤖✨**