# @involvex/super-agent-cli

![Super Agent CLI Banner](docs/banner.png)

A conversational AI CLI tool powered by Super Agent with intelligent text editor capabilities and tool usage.

## Features

- **🤖 Conversational AI**: Natural language interface powered by Super Agent-3
- **📝 Smart File Operations**: AI automatically uses tools to view, create, and edit files
- **⚡ Bash Integration**: Execute shell commands through natural conversation
- **🔧 Automatic Tool Selection**: AI intelligently chooses the right tools for your requests
- **🚀 Morph Fast Apply**: Optional high-speed code editing at 4,500+ tokens/sec with 98% accuracy
- **🔌 MCP Tools**: Extend capabilities with Model Context Protocol servers (Linear, GitHub, etc.)
- **💬 Interactive UI**: Beautiful terminal interface built with Ink
- **🌍 Global Installation**: Install and use anywhere with `bun add -g @involvex/super-agent-cli`

## Installation

### Prerequisites

bun add -g @involvex/super-agent-cli

Or with npm (fallback):

npm install -g @involvex/super-agent-cli

## Configuration Files

Super Agent CLI uses two types of configuration files to manage settings:

### User-Level Settings (`~/.super-agent/settings.json`)

This file stores **global settings** that apply across all projects. These settings rarely change and include:

- **API Key**: Your Super Agent API key
- **Base URL**: Custom API endpoint (if needed)
- **Default Model**: Your preferred model (e.g., `gemini-3.0-flash`)
- **Available Models**: List of models you can use

**Example:**

```json
{
  "active_provider": "gemini",
  "providers": {
    "gemini": {
      "id": "gemini",
      "provider": "gemini",
      "model": "MODEL_NAME",
      "api_key": "API_KEY",
      "base_url": "BASE_URL (optional)",
      "default_model": "MODEL_NAME"
    }
  }
}
```

### Project-Level Settings (`.super-agent/settings.json`)

This file stores **project-specific settings** in your current working directory. It includes:

- **Current Model**: The model currently in use for this project
- **MCP Servers**: Model Context Protocol server configurations

**Example:**

```json
{
  "active_provider": "gemini",
  "providers": {
    "gemini": {
      "id": "gemini",
      "provider": "gemini",
      "model": "MODEL_NAME",
      "api_key": "API_KEY",
      "base_url": "BASE_URL (optional)",
      "default_model": "MODEL_NAME"
    }
  },
  "mcpServers": {
    "linear": {
      "name": "linear",
      "transport": "stdio",
      "command": "npx",
      "args": ["@linear/mcp-server"]
    }
  }
}
```

### How It Works

1. **Global Defaults**: User-level settings provide your default preferences
2. **Project Override**: Project-level settings override defaults for specific projects
3. **Directory-Specific**: When you change directories, project settings are loaded automatically
4. **Fallback Logic**: Project model → User default model → System default (`gemini-3-pro-preview`)

This means you can have different models for different projects while maintaining consistent global settings like your API key.

### Using Other API Providers

**Important**: Super Agent CLI uses **OpenAI-compatible APIs**. You can use any provider that implements the OpenAI chat completions standard.

**Popular Providers**:

- **Google (Gemini)**: `https://generativelanguage.googleapis.com/v1beta/openai` (default)
- **OpenAI**: `https://api.openai.com/v1`
- **OpenRouter**: `https://openrouter.ai/api/v1`
- **Groq**: `https://api.groq.com/openai/v1`

**Example with OpenRouter**:

```json
{
  "apiKey": "your_openrouter_key",
  "baseURL": "https://openrouter.ai/api/v1",
  "defaultModel": "anthropic/claude-3.5-sonnet",
  "models": [
    "anthropic/claude-3.5-sonnet",
    "openai/gpt-4o",
    "meta-llama/llama-3.1-70b-instruct"
  ]
}
```

## Usage

### Interactive Mode

Start the conversational AI assistant:

```bash
super-agent
# or
super-agent about
# or
super-agent plugins list
```

Or specify a working directory:

```bash
super-agent -d /path/to/project
```

### Headless Mode

Process a single prompt and exit (useful for scripting and automation):

```bash
super-agent --prompt "show me the package.json file"
super-agent -p "create a new file called example.js with a hello world function"
super-agent --prompt "run bun test and show me the results" --directory /path/to/project
super-agent --prompt "complex task" --max-tool-rounds 50  # Limit tool usage for faster execution
```

This mode is particularly useful for:

- **CI/CD pipelines**: Automate code analysis and file operations
- **Scripting**: Integrate AI assistance into shell scripts
- **Terminal benchmarks**: Perfect for tools like Terminal Bench that need non-interactive execution
- **Batch processing**: Process multiple prompts programmatically

### Tool Execution Control

By default, Super Agent CLI allows up to 400 tool execution rounds to handle complex multi-step tasks. You can control this behavior:

```bash
# Limit tool rounds for faster execution on simple tasks
super-agent --max-tool-rounds 10 --prompt "show me the current directory"

# Increase limit for very complex tasks (use with caution)
super-agent --max-tool-rounds 1000 --prompt "comprehensive code refactoring"

# Works with all modes
super-agent --max-tool-rounds 20  # Interactive mode
super-agent git commit-and-push --max-tool-rounds 30  # Git commands
```

**Use Cases**:

- **Fast responses**: Lower limits (10-50) for simple queries
- **Complex automation**: Higher limits (500+) for comprehensive tasks
- **Resource control**: Prevent runaway executions in automated environments

### Model Selection

You can specify which AI model to use with the `--model` parameter

# Use Super Agent models

super-agent --model gemini-3-pro-preview
super-agent --model gemini-2.5-pro
super-agent --model gemini-2.5-flash

**Method 2: User Settings File**
Add to `~/.super-agent/settings.json`:

**Model Priority**: `--model` flag > user default model > system default (gemini-3-pro-preview)

### Command Line Options

```bash
super-agent [options]

Options:
  -V, --version          output the version number
  -d, --directory <dir>  set working directory
  -k, --api-key <key>    Super Agent API key (or set SUPER_AGENT_API_KEY env var)
  -u, --base-url <url>   Super Agent API base URL (or set SUPER_AGENT_BASE_URL env var)
  -m, --model <model>    AI model to use (e.g., super-agent-code-fast-1, super-agent-4-latest) (or set SUPER_AGENT_MODEL env var)
  -p, --prompt <prompt>  process a single prompt and exit (headless mode)
  --max-tool-rounds <rounds>  maximum number of tool execution rounds (default: 400)
  -h, --help             display help for command

Commands:
  about                                      Show information about the Super Agent CLI
  plugins list/install/uninstall <name/path> Manage plugins for Super Agent CLI
  git                                        Git operations with AI assistance
  mcp                                        Manage MCP servers
  web                                        Start web interface
  serve                                      Start both TUI and web interfaces
```

### Plugin System

Extend Super Agent with custom tools and capabilities through plugins.

#### Installing Plugins

**From GitHub Repository:**

```bash
# Full URL
super-agent plugins install https://github.com/involvex/super-agent-cli-plugins

# Short format (owner/repo)
super-agent plugins install involvex/super-agent-cli-plugins
```

**From Local Directory:**

```bash
super-agent plugins install ./my-plugin
super-agent plugins install /path/to/plugin-directory
```

**From File:**

```bash
super-agent plugins install ./plugin.js
super-agent plugins install /path/to/plugin/dist/index.js
```

#### Managing Plugins

```bash
# List installed plugins
super-agent plugins list

# Uninstall a plugin
super-agent plugins uninstall plugin-name
```

#### Creating Plugins

See the [official plugin repository](https://github.com/involvex/super-agent-cli-plugins) for:

- Example plugins (weather, database, notifications)
- Plugin templates
- Quickstart guide
- API documentation

### Custom Instructions

You can provide custom instructions to tailor Super Agent's behavior to your project or globally. Super Agent CLI supports both project-level and global custom instructions.

#### Project-Level Instructions

Create a `.super-agent/SUPER_AGENT.md` file in your project directory to provide instructions specific to that project:

```bash
mkdir .super-agent
```

Create `.super-agent/SUPER_AGENT.md` with your project-specific instructions:

```markdown
# Custom Instructions for This Project

Always use TypeScript for any new code files.
When creating React components, use functional components with hooks.
Prefer const assertions and explicit typing over inference where it improves clarity.
Always add JSDoc comments for public functions and interfaces.
Follow the existing code style and patterns in this project.
```

#### Global Instructions

For instructions that apply across all projects, create `~/.super-agent/SUPER_AGENT.md` in your home directory:

```bash
mkdir -p ~/.super-agent
```

Create `~/.super-agent/SUPER_AGENT.md` with your global instructions:

```markdown
# Global Custom Instructions for Super Agent CLI

Always prioritize code readability and maintainability.
Use descriptive variable names and add comments for complex logic.
Follow best practices for the programming language being used.
When suggesting code changes, consider performance implications.
```

#### Priority Order

Super Agent will load custom instructions in the following priority order:

1. **Project-level** (`.super-agent/SUPER_AGENT.md` in current directory) - takes highest priority
2. **Global** (`~/.super-agent/SUPER_AGENT.md` in home directory) - fallback if no project instructions exist

If both files exist, project instructions will be used. If neither exists, Super Agent operates with its default behavior.

The custom instructions are added to Super Agent's system prompt and influence its responses across all interactions in the respective context.

## MCP Tools

Super Agent CLI supports MCP (Model Context Protocol) servers, allowing you to extend the AI assistant with additional tools and capabilities.

### Adding MCP Tools

#### Add a custom MCP server:

```bash
# Add an stdio-based MCP server
super-agent mcp add my-server --transport stdio --command "bun" --args server.js

# Add an HTTP-based MCP server
super-agent mcp add my-server --transport http --url "http://localhost:3000"

# Add with environment variables
super-agent mcp add my-server --transport stdio --command "python" --args "-m" "my_mcp_server" --env "API_KEY=your_key"
```

#### Add from JSON configuration:

```bash
super-agent mcp add-json my-server '{"command": "bun", "args": ["server.js"], "env": {"API_KEY": "your_key"}}'
```

### Linear Integration Example

To add Linear MCP tools for project management:

```bash
# Add Linear MCP server
super-agent mcp add linear --transport sse --url "https://mcp.linear.app/sse"
```

This enables Linear tools like:

- Create and manage Linear issues
- Search and filter issues
- Update issue status and assignees
- Access team and project information

### Managing MCP Servers

```bash
# List all configured servers
super-agent mcp list

# Test server connection
super-agent mcp test server-name

# Remove a server
super-agent mcp remove server-name
```

### Available Transport Types

- **stdio**: Run MCP server as a subprocess (most common)
- **http**: Connect to HTTP-based MCP server
- **sse**: Connect via Server-Sent Events

## Development

```bash
# Install dependencies
bun install

# Development mode
bun run dev

# Build project
bun run build

# Run linter
bun run lint

# Type check
bun run typecheck
```

## Architecture

- **Agent**: Core command processing and execution logic
- **Tools**: Text editor and bash tool implementations
- **UI**: Ink-based terminal interface components
- **Types**: TypeScript definitions for the entire system

## License

MIT
