super-agent-cli

An open-source AI agent that brings the power of Super Agent directly into your terminal

public

Forked

              @involvex/super-agent-cli

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

Features

undefined🤖 Conversational AI: Natural language interface powered by Super Agent-3
undefined📝 Smart File Operations: AI automatically uses tools to view, create, and edit files
undefined⚡ Bash Integration: Execute shell commands through natural conversation
undefined🔧 Automatic Tool Selection: AI intelligently chooses the right tools for your requests
undefined🚀 Morph Fast Apply: Optional high-speed code editing at 4,500+ tokens/sec with 98% accuracy
undefined🔌 MCP Tools: Extend capabilities with Model Context Protocol servers (Linear, GitHub, etc.)
undefined💬 Interactive UI: Beautiful terminal interface built with Ink
undefined🌍 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:

undefinedAPI Key: Your Super Agent API key
undefinedBase URL: Custom API endpoint (if needed)
undefinedDefault Model: Your preferred model (e.g., gemini-3.0-flash)
undefinedAvailable Models: List of models you can use

undefinedExample:undefined

{
  "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:

undefinedCurrent Model: The model currently in use for this project
undefinedMCP Servers: Model Context Protocol server configurations

undefinedExample:undefined

{
  "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

undefinedGlobal Defaults: User-level settings provide your default preferences
undefinedProject Override: Project-level settings override defaults for specific projects
undefinedDirectory-Specific: When you change directories, project settings are loaded automatically
undefinedFallback 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

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

undefinedPopular Providers:

undefinedGoogle (Gemini): https://generativelanguage.googleapis.com/v1beta/openai (default)
undefinedOpenAI: https://api.openai.com/v1
undefinedOpenRouter: https://openrouter.ai/api/v1
undefinedGroq: https://api.groq.com/openai/v1

undefinedExample with OpenRouter:

{
  "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:

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

Or specify a working directory:

super-agent -d /path/to/project

Interactive Features

Super Agent CLI provides several interactive features to enhance your workflow:

undefinedShell Mode: Press shift+! to toggle shell mode for direct command execution
undefinedAgent Modes: Press shift+tab to cycle through modes (plan, code, debug)
undefinedCommand Palette: Press ctrl+p to open a quick command palette
undefinedAuto-Edit Toggle: Press ctrl+y to toggle auto-edit mode
undefinedConfigurable Hotkeys: All hotkeys can be customized in settings
undefinedFile Mentions: Reference files using @filename in your prompts
undefinedFolder Mentions: Reference entire folders using @folder in your prompts

Headless Mode

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

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:

undefinedCI/CD pipelines: Automate code analysis and file operations
undefinedScripting: Integrate AI assistance into shell scripts
undefinedTerminal benchmarks: Perfect for tools like Terminal Bench that need non-interactive execution
undefinedBatch 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:

# 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

undefinedUse Cases:

undefinedFast responses: Lower limits (10-50) for simple queries
undefinedComplex automation: Higher limits (500+) for comprehensive tasks
undefinedResource control: Prevent runaway executions in automated environments

Model Selection

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

Method 1: Command Line Flag

# 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:

{
  "active_provider": "gemini",
  "providers": {
    "gemini": {
      "id": "gemini",
      "provider": "gemini",
      "model": "gemini-3-pro-preview",
      "api_key": "YOUR_API_KEY",
      "default_model": "gemini-3-pro-preview"
    }
  }
}

undefinedModel Priority: --model flag > user default model > system default (gemini-3-pro-preview)

Command Line Options

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

undefinedNote: In addition to these command-line commands, all slash commands (e.g., /init, /config, /models, /chat, /plugin, /help) are available in interactive mode. See the Command Reference section for a complete list of available slash commands.

Web Interface

Super Agent CLI provides a web interface for a more visual and accessible experience.

Starting the Web Interface

# Start only the web interface
super-agent web

# Start both the TUI (terminal UI) and web interfaces
super-agent serve

Web Interface Features

The web interface offers:

undefinedModern Browser-Based UI: Access the AI assistant through any modern web browser
undefinedReal-Time Chat: Engage in conversational AI interactions with streaming responses
undefinedFile Explorer: Browse and manage project files visually
undefinedTool Visualization: See tools being used in real-time with detailed output
undefinedChat History: View and manage conversation history
undefinedResponsive Design: Works seamlessly on desktop, tablet, and mobile devices
undefinedMulti-Session Support: Run multiple sessions simultaneously
undefinedPersistent Connection: Maintains connection state across interactions

The web interface provides all the functionality of the TUI with the added convenience of a graphical interface, making it easier to visualize file operations, tool usage, and complex workflows.

Command Reference

Super Agent CLI provides a comprehensive set of commands to manage your AI assistant sessions.

Project Setup

/init           # Create AGENTS.md in project root with template instructions

Configuration

/config         # Configure API keys, models, base URLs, and other settings

Model Management

/models                    # List all available models
/models <model>            # Switch to a specific model
/models <model> <prompt>   # Switch to a model and immediately run a prompt

Chat Management

/chat                       # Show current chat information
/chat save <chat_name>      # Save the current chat
/chat load <chat_name>      # Load a saved chat
/chat list                  # List all saved chats
/chat delete <chat_name>    # Delete a saved chat
/chat clear                 # Clear the current chat history

Plugin Management

/plugin install <plugin_name>    # Install a plugin from GitHub, local path, or file
/plugin list                    # List all installed plugins
/plugin delete <plugin_name>     # Delete an installed plugin

MCP Tools

/mcp add <name> [options]    # Add a new MCP server
/mcp list                    # List all configured MCP servers
/mcp test <name>             # Test a MCP server connection
/mcp remove <name>           # Remove a MCP server

General Commands

/help           # Show help information and available commands
/clear          # Clear the current chat history
/exit           # Exit the CLI

Usage Examples

# Initialize project with agent instructions
/init

# Switch to Gemini Flash and run a prompt
/models gemini-2.5-flash "explain this codebase"

# Save current chat session
/chat save feature-development

# Load a previous chat session
/chat load feature-development

# Install a plugin from GitHub
/plugin install involvex/super-agent-cli-plugins

# Configure API settings
/config

Plugin System

Extend Super Agent with custom tools and capabilities through plugins.

Installing Plugins

undefinedFrom GitHub Repository:undefined

# 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

undefinedFrom Local Directory:undefined

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

undefinedFrom File:undefined

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

Managing Plugins

# List installed plugins
super-agent plugins list

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

Creating Plugins

See the official plugin repository 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 reads agent and skill configurations from multiple locations.

Agent Instructions (AGENTS.md)

Super Agent CLI reads agent instructions from these locations, in order of priority:

AGENTS.md in project root - highest priority
.super-agent/AGENTS.md in project directory
.super-agent/agents/*.md - individual agent files
~/.super-agent/AGENTS.md in home directory
~/.super-agent/agents/*.md - global agent files

Create project-specific agent instructions:

mkdir -p .super-agent

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

# Custom Agent 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.

Skill Instructions (SKILLS.md)

Skill configurations follow the same priority order:

SKILLS.md in project root - highest priority
.super-agent/SKILLS.md in project directory
.super-agent/skills/*.md - individual skill files
~/.super-agent/SKILLS.md in home directory
~/.super-agent/skills/*.md - global skill files

Global Instructions

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

mkdir -p ~/.super-agent

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

# Global Agent 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:

undefinedProject-level files take highest priority
undefinedGlobal files serve as fallback if no project instructions exist
undefinedIndividual files (*.md) are merged into a single instruction set

If multiple files exist, they are combined with project instructions taking precedence. 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:

# 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:

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:

# 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

# 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

undefinedstdio: Run MCP server as a subprocess (most common)
undefinedhttp: Connect to HTTP-based MCP server
undefinedsse: Connect via Server-Sent Events

Development

# 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

undefinedAgent: Core command processing and execution logic
undefinedTools: Text editor and bash tool implementations
undefinedUI: Ink-based terminal interface components
undefinedTypes: TypeScript definitions for the entire system

License

MIT

Find me

[beta]v0.3.0

super-agent-cli

Features

Installation

Prerequisites

Configuration Files

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

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

How It Works

Using Other API Providers

Usage

Interactive Mode

Interactive Features

Headless Mode

Tool Execution Control

Model Selection

Method 1: Command Line Flag

Method 2: User Settings File

Command Line Options

Web Interface

Starting the Web Interface

Web Interface Features

Command Reference

Project Setup

Configuration

Model Management

Chat Management

Plugin Management

MCP Tools

General Commands

Usage Examples

Plugin System

Installing Plugins

Managing Plugins

Creating Plugins

Custom Instructions

Agent Instructions (AGENTS.md)

Skill Instructions (SKILLS.md)

Global Instructions

Priority Order

MCP Tools

Adding MCP Tools

Add a custom MCP server:

Add from JSON configuration:

Linear Integration Example

Managing MCP Servers

Available Transport Types

Development

Architecture

License

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

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