command-assistant/docs/user/advanced-features.md

# Advanced Features

Edison offers several advanced features to enhance your productivity. This guide explores these capabilities in detail.

## Interactive Mode

Interactive mode provides a dedicated shell for continuous Edison interactions.

```mermaid
stateDiagram-v2
    [*] --> Interactive: edison -i
    Interactive --> Query: Enter query
    Query --> CommandGeneration: Process query
    CommandGeneration --> CommandDisplay: Display command
    CommandDisplay --> ActionChoice: Prompt for action
    ActionChoice --> Execution: y/Enter
    ActionChoice --> Modification: m
    ActionChoice --> Explanation: x
    ActionChoice --> Clipboard: c
    ActionChoice --> Query: n/skip
    Execution --> Query: Command executed
    Modification --> Execution: Execute modified command
    Explanation --> ActionChoice: Show explanation
    Clipboard --> ActionChoice: Copy to clipboard
    Interactive --> [*]: exit/quit/!exit/Ctrl+D
```

To start interactive mode:

```bash
edison -i
```

In interactive mode, you can:
- Enter queries one after another without restarting Edison
- Access command history with up/down arrows
- Use tab completion for Edison commands
- Type `!help` to see available commands
- Type `!exit`, `exit`, `!quit`, `quit` or press `Ctrl+D` to exit

## Command Explanations

Get explanations for complex commands:

```bash
edison -e how to find duplicate files in a directory
```

The `-e` (or `--explain`) flag makes Edison provide an explanation of the generated command, breaking it down part by part. Edison uses terminal-friendly formatting to make explanations more readable:

- **Bold text** for emphasis and headers
- **Green text** for commands and file paths
- **Yellow text** for command parameters and options
- **Cyan text** for section beginnings and important concepts
- **Code formatting** for command snippets and examples

In interactive mode, use the `x` option when prompted for an action to get an explanation.

## Configuration

Edison can be configured through the `edison.yaml` file. This configuration file is located in the Edison installation directory.

Here's an example configuration:

```yaml
# OpenAI API settings
model: gpt-3.5-turbo
temperature: 0
max_tokens: 500

# Safety settings
safety: true

# Shell settings
shell: bash
```

Configuration options:

| Option | Description | Default |
|--------|-------------|---------|
| model | OpenAI model to use | gpt-3.5-turbo |
| temperature | Randomness of completions (0-1) | 0 |
| max_tokens | Maximum response tokens | 500 |
| safety | Require confirmation before execution | true |
| shell | Shell to use for command execution | system default |
| openai_api_key | OpenAI API key (optional) | - |

You can view your current configuration with:

```bash
edison -c
```

## Logging and Debugging

Edison provides verbose logging for troubleshooting:

```bash
edison -v list all processes
```

With the `-v` (or `--verbose`) flag, Edison will output detailed DEBUG level logs.

Log files are stored in the `edison/logs` directory and can be useful for debugging issues.

## Streaming Command Generation

Edison supports streaming command generation, which shows the command being generated in real-time:

```mermaid
sequenceDiagram
    participant User
    participant Edison
    participant API as OpenAI API
    
    User->>Edison: Natural language query
    Edison->>API: Request with streaming enabled
    Note over Edison,API: Streaming connection established
    API-->>Edison: Token: "f"
    Edison->>User: Display: "f"
    API-->>Edison: Token: "ind"
    Edison->>User: Update: "find"
    API-->>Edison: Token: " -name"
    Edison->>User: Update: "find -name"
    API-->>Edison: Token: " \"*.txt\""
    Edison->>User: Update: "find -name \"*.txt\""
    API-->>Edison: Token: " -type f"
    Edison->>User: Final: "find -name \"*.txt\" -type f"
```

This feature:
- Provides immediate feedback during command generation
- Makes Edison feel more responsive, especially for complex commands
- Allows you to see the thought process in real-time

### Hiding the "Generating command:" Prefix

By default, Edison displays "Generating command:" while it's working. You can hide this prefix with the following configuration:

```yaml
# In edison.yaml
show_generating_prefix: false
```

## Direct Command Modification

Edison provides a direct command modification option that allows you to edit the generated command in-place:

1. When prompted for action, press `d` to directly modify the command
2. Edison will present an interactive editor with the current command
3. Edit the command as needed
4. Press Enter to execute the modified command

This feature is especially useful for:
- Making minor adjustments to generated commands
- Adding flags or options that weren't included
- Correcting parts of the command that may not be exactly what you want

## Performance Optimization

For faster response times:

1. Use a faster model like `gpt-3.5-turbo` (default) instead of larger models
2. Keep queries concise and specific
3. Use interactive mode to avoid startup overhead for multiple commands
4. Enable streaming mode for perceived performance improvements

## Safety Features

Edison includes built-in safety measures:

1. **Command confirmation**: By default, Edison asks for confirmation before executing commands
2. **Dangerous command detection**: Edison will warn about potentially dangerous operations
3. **Markdown filtering**: Commands containing markdown formatting are not executed directly

To disable the safety confirmation (not recommended):

```yaml
# In edison.yaml
safety: false
```

## Cross-Platform Considerations

Edison works on Linux, macOS, and Windows, but some commands might be platform-specific. For best results:

1. Mention your operating system in queries for system-specific commands
2. Use the `-e` flag to understand what a command does before executing it
3. Be aware that file paths use different separators (/ vs \\) on different platforms