@involvex/super-agent-cli 0.0.50 → 0.0.59

package/@plugins/README.md

@@ -0,0 +1,106 @@
+# Super Agent CLI Plugins
+
+Official plugin repository for [Super Agent CLI](https://github.com/involvex/super-agent-cli).
+
+Extend your Super Agent CLI with custom tools, integrations, and capabilities through a simple plugin system.
+
+## 🚀 Quick Start
+
+See [QUICKSTART.md](./QUICKSTART.md) for a step-by-step guide to creating your first plugin.
+
+## 📦 Available Examples
+
+Explore fully-functional example plugins in the `examples/` directory:
+
+- **[weather](./examples/weather/)** - External API integration with weather data
+- **[database](./examples/database/)** - Database query tools with state management
+- **[notify](./examples/notify/)** - System notifications and cross-platform integration
+
+## 🎨 Templates
+
+Get started quickly with our templates in the `templates/` directory:
+
+- **[basic](./templates/basic/)** - Minimal single-tool plugin
+- **[advanced](./templates/advanced/)** - Full-featured plugin with tests and CI
+
+## 📖 Plugin API
+
+All plugins must export a `SuperAgentPlugin` object:
+
+```typescript
+export interface SuperAgentPlugin {
+  name: string; // Unique plugin identifier
+  version: string; // Semantic version
+  description?: string; // Human-readable description
+  tools?: SuperAgentTool[]; // Tools provided by this plugin
+  onInit?: (context: PluginContext) => Promise<void>;
+  onShutdown?: () => Promise<void>;
+}
+```
+
+### Tool Definition
+
+```typescript
+export interface SuperAgentTool {
+  type: "function";
+  function: {
+    name: string;
+    description: string;
+    parameters?: {
+      type: "object";
+      properties: Record<string, any>;
+      required?: string[];
+    };
+    executor: (args: any, context: any) => Promise<string>;
+  };
+}
+```
+
+## 🔧 Installing Plugins
+
+### From this repository:
+
+```bash
+super-agent plugins install @plugins/examples/weather
+```
+
+### From local file:
+
+```bash
+super-agent plugins install ./my-plugin.js
+super-agent plugins install /path/to/plugin/dist/index.js
+```
+
+### List installed plugins:
+
+```bash
+super-agent plugins list
+```
+
+### Remove a plugin:
+
+```bash
+super-agent plugins uninstall weather
+```
+
+## 📝 Contributing
+
+We welcome plugin contributions! Please see our [Contributing Guidelines](CONTRIBUTING.md) for details.
+
+### Plugin Submission Checklist
+
+- [ ] Plugin follows the API specification
+- [ ] Includes README with usage examples
+- [ ] TypeScript types are properly defined
+- [ ] Error handling is implemented
+- [ ] Code is tested (for advanced plugins)
+
+## 📄 License
+
+MIT - See [LICENSE](LICENSE) for details.
+
+## 🔗 Links
+
+- [Super Agent CLI Documentation](https://github.com/involvex/super-agent-cli)
+- [Plugin Quickstart Guide](./QUICKSTART.md)
+- [Report Issues](https://github.com/involvex/super-agent-cli-plugins/issues)

package/@plugins/examples/notify/README.md

@@ -0,0 +1,43 @@
+# Notification Plugin
+
+Send desktop notifications from Super Agent CLI.
+
+## Features
+
+- Cross-platform support (macOS, Windows, Linux)
+- Urgency levels (low, normal, critical)
+- Simple, single-tool example
+
+## Installation
+
+```bash
+super-agent plugins install @plugins/examples/notify
+```
+
+## Usage
+
+```
+> Notify me when this is done
+> Send a notification saying the build is complete
+> Alert me with "Meeting in 5 minutes"
+```
+
+## Platform Requirements
+
+- **macOS**: Built-in (uses `osascript`)
+- **Windows**: Built-in (uses PowerShell)
+- **Linux**: Requires `notify-send` (usually pre-installed)
+
+## Example
+
+```typescript
+{
+  "title": "Build Complete",
+  "message": "Your project build finished successfully!",
+  "urgency": "normal"
+}
+```
+
+## License
+
+MIT

package/@plugins/examples/notify/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@involvex/super-agent-plugin-notify",
+  "version": "1.0.0",
+  "description": "Desktop notification plugin for Super Agent CLI",
+  "keywords": [
+    "super-agent",
+    "plugin",
+    "notifications",
+    "desktop"
+  ],
+  "license": "MIT",
+  "author": "InvolveX",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist",
+    "dev": "tsc --watch"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.0.0"
+  },
+  "peerDependencies": {
+    "@involvex/super-agent-cli": ">=0.0.58"
+  }
+}

package/@plugins/examples/weather/README.md

@@ -0,0 +1,76 @@
+# Weather Plugin
+
+Get weather information for any city using the OpenWeatherMap API.
+
+## Features
+
+- Current weather conditions
+- Temperature in Celsius/Fahrenheit
+- Humidity, wind speed, and conditions
+- Simple, single-tool example
+
+## Installation
+
+```bash
+super-agent plugins install @plugins/examples/weather
+```
+
+## Configuration
+
+Add your API key to `~/.super-agent/settings.json`:
+
+```json
+{
+  "plugins": ["@plugins/examples/weather"],
+  "pluginConfigs": {
+    "weather": {
+      "apiKey": "your-openweathermap-api-key",
+      "units": "metric"
+    }
+  }
+}
+```
+
+Get a free API key at [OpenWeatherMap](https://openweathermap.org/api).
+
+## Usage
+
+Simply ask Super Agent about the weather:
+
+```
+> What's the weather in London?
+> Is it raining in Tokyo?
+> What's the temperature in New York?
+```
+
+## Implementation Details
+
+This plugin demonstrates:
+
+- **External API integration** - Makes HTTP requests to OpenWeatherMap
+- **Configuration handling** - Reads API key from plugin config
+- **Error handling** - Gracefully handles API errors and missing config
+- **Parameter validation** - Validates city name input
+
+## Code Structure
+
+```
+weather/
+├── src/
+│   └── index.ts       # Main plugin code
+├── package.json       # Dependencies
+├── tsconfig.json      # TypeScript config
+└── README.md          # This file
+```
+
+## Development
+
+```bash
+npm install
+npm run build
+npm run dev   # Watch mode
+```
+
+## License
+
+MIT

package/@plugins/examples/weather/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@involvex/super-agent-plugin-weather",
+  "version": "1.0.0",
+  "description": "Weather plugin for Super Agent CLI",
+  "keywords": [
+    "super-agent",
+    "plugin",
+    "weather",
+    "openweathermap"
+  ],
+  "license": "MIT",
+  "author": "InvolveX",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist",
+    "dev": "tsc --watch"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.0.0"
+  },
+  "peerDependencies": {
+    "@involvex/super-agent-cli": ">=0.0.58"
+  }
+}

package/@plugins/shared/types.ts

@@ -0,0 +1,27 @@
+export interface PluginContext {
+  agent: any; // SuperAgent instance
+  config: any; // Plugin-specific configuration
+}
+
+export interface SuperAgentTool {
+  type: "function";
+  function: {
+    name: string;
+    description: string;
+    parameters?: {
+      type: "object";
+      properties: Record<string, any>;
+      required?: string[];
+    };
+    executor: (args: any, context: any) => Promise<string>;
+  };
+}
+
+export interface SuperAgentPlugin {
+  name: string;
+  version: string;
+  description?: string;
+  tools?: SuperAgentTool[];
+  onInit?: (context: PluginContext) => Promise<void>;
+  onShutdown?: () => Promise<void>;
+}

package/@plugins/templates/basic/README.md

@@ -0,0 +1,50 @@
+# Basic Plugin Template
+
+A minimal template for creating Super Agent CLI plugins.
+
+## Quick Start
+
+1. **Copy this template:**
+
+   ```bash
+   cp -r templates/basic my-plugin
+   cd my-plugin
+   ```
+
+2. **Customize `src/index.ts`:**
+   - Change plugin name, version, description
+   - Replace `example_tool` with your own tool
+   - Update the tool's name, description, and parameters
+
+3. **Build:**
+
+   ```bash
+   npm install
+   npm run build
+   ```
+
+4. **Install:**
+   ```bash
+   super-agent plugins install ./dist/index.js
+   ```
+
+## Structure
+
+```
+basic/
+├── src/
+│   └── index.ts       # Plugin implementation
+├── package.json       # Dependencies
+├── tsconfig.json      # TypeScript configuration
+└── README.md          # This file
+```
+
+## Next Steps
+
+- See [QUICKSTART.md](../../QUICKSTART.md) for detailed guide
+- Check [examples/](../../examples/) for more complex plugins
+- Use [advanced template](../advanced/) for full-featured plugins
+
+## License
+
+MIT

package/@plugins/templates/basic/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@involvex/super-agent-plugin-template",
+  "version": "1.0.0",
+  "description": "Basic template for Super Agent CLI plugins",
+  "keywords": [
+    "super-agent",
+    "plugin"
+  ],
+  "license": "MIT",
+  "author": "Your Name",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist",
+    "dev": "tsc --watch"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.0.0"
+  },
+  "peerDependencies": {
+    "@involvex/super-agent-cli": ">=0.0.58"
+  }
+}

package/README.md

@@ -1,8 +1,8 @@
 # @involvex/super-agent-cli
 
-A conversational AI CLI tool powered by Super Agent with intelligent text editor capabilities and tool usage.
+![Super Agent CLI Banner](docs/banner.png)
 
-<img width="980" height="435" alt="Screenshot 2025-07-21 at 13 35 41" src="assets/splash.png" />
+A conversational AI CLI tool powered by Super Agent with intelligent text editor capabilities and tool usage.
 
 ## Features
 
@@ -219,8 +219,59 @@ Commands:
   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.