genieceo 0.1.0

package/DEVELOPMENT.md

@@ -0,0 +1,240 @@
+# Development Guide
+
+## Project Structure
+
+```
+genieceo/
+├── src/
+│   ├── agent/              # Agent core logic
+│   │   ├── context.ts      # System prompt builder
+│   │   ├── index.ts        # Agent initialization
+│   │   ├── loop.ts         # Main agent loop (Vercel AI SDK)
+│   │   └── subagent.ts     # Background task delegation
+│   ├── cli/                # CLI interface
+│   │   ├── commands/       # Command implementations
+│   │   │   ├── chat.ts     # Chat command (interactive/single)
+│   │   │   ├── init.ts     # Initialize command
+│   │   │   └── status.ts   # Status command
+│   │   └── index.ts        # CLI entry point (Commander)
+│   ├── config/             # Configuration system
+│   │   ├── manager.ts      # Config loading/saving
+│   │   └── schema.ts       # Zod schemas
+│   ├── providers/          # LLM providers
+│   │   └── llm.ts          # Vercel AI SDK wrapper
+│   ├── skills/             # Skill system
+│   │   ├── builtin/        # Built-in skills (markdown)
+│   │   │   ├── coding/
+│   │   │   ├── debugging/
+│   │   │   └── planning/
+│   │   └── loader.ts       # Skill loading & management
+│   ├── tools/              # Tool implementations
+│   │   ├── base.ts         # Tool registry & interface
+│   │   ├── filesystem.ts   # readFile, writeFile, listDir
+│   │   ├── shell.ts        # executeCommand (with safety)
+│   │   ├── spawn.ts        # spawnSubagent
+│   │   └── web.ts          # webSearch (multi-provider)
+│   ├── types/              # TypeScript types
+│   │   └── index.ts        # Shared types
+│   └── workspace/          # Workspace management
+│       └── manager.ts      # Workspace initialization
+├── package.json
+├── tsconfig.json
+├── README.md
+└── LICENSE
+```
+
+## Code Statistics
+
+- **Total Lines**: ~1,941 lines of TypeScript
+- **Files**: 19 TypeScript files + 3 skill markdown files
+- **Architecture**: Clean, modular, easy to extend
+
+## Building
+
+```bash
+npm run build     # Compile TypeScript to dist/
+npm run dev       # Watch mode for development
+```
+
+## Testing Locally
+
+```bash
+# Build
+npm run build
+
+# Link for global use
+npm link
+
+# Test commands
+genieceo init
+genieceo status
+genieceo chat -m "Hello!"
+```
+
+## Key Design Patterns
+
+### 1. Tool Registry Pattern
+All tools are registered in a central registry and converted to Vercel AI SDK format:
+
+```typescript
+const registry = new ToolRegistry();
+registry.register(readFileTool);
+const vercelTools = registry.toVercelTools();
+```
+
+### 2. Vercel AI SDK Integration
+Using `generateText()` with automatic tool calling loop:
+
+```typescript
+const result = await generateText({
+  model: getModel(),
+  messages,
+  tools,
+  maxSteps: 15  // Automatic iteration
+});
+```
+
+### 3. Configuration with Zod
+Type-safe configuration with runtime validation:
+
+```typescript
+const ConfigSchema = z.object({
+  workspace: z.string(),
+  model: z.string(),
+  // ...
+});
+```
+
+### 4. Skill System
+Markdown files with YAML frontmatter:
+
+```markdown
+---
+name: skill-name
+description: What it does
+---
+# Skill content
+```
+
+## Adding a New Tool
+
+1. Create tool file in `src/tools/`:
+
+```typescript
+import { z } from 'zod';
+import type { Tool } from '../types';
+
+export const myTool: Tool = {
+  name: 'myTool',
+  description: 'What the tool does',
+  parameters: z.object({
+    param: z.string(),
+  }),
+  execute: async (params) => {
+    // Implementation
+    return { success: true };
+  },
+};
+```
+
+2. Register in `src/agent/index.ts`:
+
+```typescript
+import { myTool } from '../tools/mytool';
+toolRegistry.register(myTool);
+```
+
+## Adding a New LLM Provider
+
+1. Install SDK:
+```bash
+npm install @ai-sdk/anthropic
+```
+
+2. Update `src/providers/llm.ts`:
+
+```typescript
+import { createAnthropic } from '@ai-sdk/anthropic';
+
+case 'anthropic':
+  const anthropicProvider = createAnthropic({
+    apiKey: this.config.llm.anthropic.apiKey,
+  });
+  return anthropicProvider(model);
+```
+
+3. Update config schema in `src/config/schema.ts`
+
+## Adding a New Skill
+
+Create directory in `src/skills/builtin/`:
+
+```
+src/skills/builtin/myskill/
+└── SKILL.md
+```
+
+The skill will be automatically loaded on startup.
+
+## Architecture Benefits
+
+1. **Vercel AI SDK**: Automatic tool calling, provider-agnostic
+2. **Modular**: Each component is independent and testable
+3. **Type-safe**: TypeScript + Zod for runtime validation
+4. **Extensible**: Easy to add tools, skills, providers
+5. **Clean**: ~2000 lines vs nanobot's ~4000 lines (50% smaller!)
+
+## Publishing to npm
+
+1. Update version in `package.json`
+2. Build: `npm run build`
+3. Test: `npm link` and verify
+4. Publish: `npm publish`
+
+## Configuration
+
+All configuration is managed through `~/.genieceo/config.json`. No environment variables are used.
+
+Edit the config file directly to set:
+- **llm.openai.apiKey**: OpenAI API key
+- **model**: Model (e.g., "openai:gpt-4o")
+- **workspace**: Workspace path
+- **tools.webSearch.provider**: Search provider ("auto", "brave", "tavily", or "browser")
+- **tools.webSearch.tavily.apiKey**: Tavily Search API key (optional, recommended)
+- **tools.webSearch.brave.apiKey**: Brave Search API key (optional)
+
+## Troubleshooting
+
+### Build Errors
+- Run `npm install` to ensure dependencies are installed
+- Check TypeScript version: `npm list typescript`
+
+### Runtime Errors
+- Verify config: `genieceo status`
+- Check API keys are set
+- Ensure workspace is initialized: `genieceo init`
+
+### Tool Errors
+- Check tool parameters match Zod schema
+- Verify workspace path exists
+- Check shell command safety patterns
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch: `git checkout -b feature-name`
+3. Make your changes
+4. Build and test: `npm run build && genieceo status`
+5. Commit: `git commit -m "Description"`
+6. Push: `git push origin feature-name`
+7. Create pull request
+
+## Philosophy
+
+- **Simplicity over complexity**
+- **Readability over cleverness**
+- **Modularity over monoliths**
+- **Type safety over duck typing**
+- **Convention over configuration**
+
+Keep the codebase small, clean, and understandable!

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 genieceo contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,443 @@
+# genieceo 🐱
+
+**Ultra-lightweight AI agent CLI assistant** inspired by [nanobot](https://github.com/HKUDS/nanobot)
+
+genieceo is a powerful yet minimalist AI agent that helps you with tasks through natural language. It features a workspace for persistent memory, a skill system for specialized capabilities, and a subagent system for handling complex tasks in parallel.
+
+## ✨ Features
+
+- 🪶 **Lightweight**: Clean TypeScript codebase, easy to understand and extend
+- 🛠️ **Rich Toolset**: File operations, shell commands, web search, and more
+- 🎯 **Skill System**: Teach the agent new capabilities through markdown files
+- 🤖 **Subagents**: Delegate complex tasks to background agents
+- 🔄 **Provider-Agnostic**: Uses @mariozechner/pi-ai - supports 15+ providers with automatic model discovery
+- 💾 **Workspace**: Persistent workspace for files, skills, and configuration
+
+## 📦 Installation
+
+### From npm (coming soon)
+
+```bash
+npm install -g genieceo
+```
+
+### From source (development)
+
+```bash
+git clone https://github.com/yourusername/genieceo.git
+cd genieceo
+npm install
+npm run build
+npm link
+```
+
+## 🚀 Quick Start
+
+### 1. Initialize
+
+```bash
+genieceo init
+```
+
+This creates:
+- Configuration file at `~/.genieceo/config.json`
+- Workspace directory at `~/.genieceo/workspace/`
+
+### 2. Configure
+
+#### Option A: Interactive Setup (Recommended)
+
+Run the onboarding wizard to configure everything step-by-step:
+
+```bash
+genieceo onboard
+```
+
+The wizard will guide you through:
+- **LLM Configuration**: Select provider (OpenAI, Anthropic, etc.) and enter API key
+- **Model Selection**: Choose from available models for your provider
+- **Health Check**: Verify your LLM setup is working correctly
+- **Web Search**: Configure search providers (Tavily, Brave, or browser-based)
+
+#### Option B: Manual Configuration
+
+Edit `~/.genieceo/config.json` to add your API keys:
+
+```json
+{
+  "workspace": "~/.genieceo/workspace",
+  "model": "openai:gpt-4o",
+  "maxIterations": 15,
+  "llm": {
+    "openai": {
+      "apiKey": "sk-..."
+    }
+  },
+  "tools": {
+    "webSearch": {
+      "provider": "auto",
+      "tavily": {
+        "apiKey": "tvly-..."
+      },
+      "brave": {
+        "apiKey": "BSA..."
+      }
+    }
+  }
+}
+```
+
+**Note:** Web search will work even without API keys by using the browser fallback. However, for better results, configure at least one search provider (Tavily or Brave).
+
+### 3. Chat!
+
+**Single message:**
+```bash
+genieceo chat -m "What is 2+2?"
+```
+
+**Interactive mode:**
+```bash
+genieceo chat
+```
+
+## 🛠️ Available Tools
+
+genieceo comes with powerful built-in tools:
+
+### File Operations
+- **readFile**: Read file contents
+- **writeFile**: Create or overwrite files
+- **listDir**: List directory contents
+
+### Shell
+- **executeCommand**: Run shell commands (with safety checks)
+
+### Web
+- **webSearch**: Search the web using multiple providers (Tavily, Brave, or browser fallback)
+
+### Subagents
+- **spawnSubagent**: Create background agents for complex tasks
+
+## 🎯 Skills
+
+Skills teach the agent how to handle specialized tasks. Built-in skills:
+
+- **planning**: Break down complex tasks systematically
+- **debugging**: Debug code and systems methodically
+- **coding**: Best practices for writing quality code
+
+### Adding Custom Skills
+
+Create a skill in `~/.genieceo/workspace/skills/`:
+
+```
+~/.genieceo/workspace/skills/
+└── myskill/
+    └── SKILL.md
+```
+
+**SKILL.md format:**
+```markdown
+---
+name: myskill
+description: What this skill does
+metadata:
+  always: false
+  requires:
+    bins: []
+    config: []
+---
+
+# My Skill
+
+Detailed instructions for the agent on how to use this skill...
+```
+
+The `requires.config` field specifies config paths that must be set (e.g., `["llm.openai.apiKey", "tools.webSearch.apiKey"]`).
+
+## 🔧 Configuration
+
+Configuration file: `~/.genieceo/config.json`
+
+All configuration is managed through this file. No environment variables are used.
+
+```json
+{
+  "workspace": "~/.genieceo/workspace",
+  "model": "openai:gpt-4o",
+  "maxIterations": 15,
+  "llm": {
+    "openai": {
+      "apiKey": "sk-..."
+    }
+  },
+  "tools": {
+    "webSearch": {
+      "provider": "auto",
+      "tavily": {
+        "apiKey": "tvly-..."
+      },
+      "brave": {
+        "apiKey": "BSA..."
+      }
+    },
+    "shell": {
+      "timeout": 30000,
+      "allowDangerous": false
+    }
+  }
+}
+```
+
+### Configuration Options
+
+#### Core Settings
+- **workspace**: Directory for agent files and skills (default: `~/.genieceo/workspace`)
+- **model**: LLM model in format `provider:model` (e.g., `openai:gpt-4o`)
+- **maxIterations**: Maximum agent loop iterations (default: 15)
+
+#### LLM Configuration
+- **llm.openai.apiKey**: OpenAI API key (required)
+
+#### Web Search Configuration
+- **tools.webSearch.provider**: Search provider to use (options: `auto`, `brave`, `tavily`, `browser`)
+  - `auto` (default): Tries providers in order (Tavily → Brave → Browser)
+  - `brave`: Use Brave Search API only
+  - `tavily`: Use Tavily Search API only
+  - `browser`: Use browser-based fallback only (free, no API key needed)
+- **tools.webSearch.tavily.apiKey**: Tavily API key (optional but recommended)
+  - Get your free API key at [tavily.com](https://tavily.com)
+  - Free tier: 1,000 searches/month
+  - Recommended for best search quality
+- **tools.webSearch.brave.apiKey**: Brave Search API key (optional)
+  - Note: Brave now requires payment
+  - Get API key at [brave.com/search/api](https://brave.com/search/api)
+
+**Browser Fallback**: If no API keys are configured, web search automatically uses a browser-based fallback (DuckDuckGo HTML). This works out-of-the-box with no configuration needed.
+
+#### Shell Configuration
+- **shell.timeout**: Command timeout in milliseconds (default: 30000)
+- **shell.allowDangerous**: Allow dangerous commands (default: false)
+
+## 🔍 Web Search
+
+genieceo supports multiple web search providers with automatic fallback:
+
+### Search Providers
+
+1. **Tavily** (Recommended)
+   - High-quality search results optimized for AI agents
+   - Free tier: 1,000 searches/month
+   - Get API key: [tavily.com](https://tavily.com)
+   - Config: `tools.webSearch.tavily.apiKey`
+
+2. **Brave Search**
+   - Premium search API (now requires payment)
+   - Get API key: [brave.com/search/api](https://brave.com/search/api)
+   - Config: `tools.webSearch.brave.apiKey`
+
+3. **Browser Fallback** (Always Available)
+   - Free, no API key required
+   - Uses DuckDuckGo HTML search
+   - Automatically used when no API keys configured
+   - Good enough for most use cases
+
+### Configuration Examples
+
+**Auto mode** (tries providers in order):
+```json
+{
+  "tools": {
+    "webSearch": {
+      "provider": "auto",
+      "tavily": { "apiKey": "tvly-..." }
+    }
+  }
+}
+```
+
+**Specific provider**:
+```json
+{
+  "tools": {
+    "webSearch": {
+      "provider": "tavily",
+      "tavily": { "apiKey": "tvly-..." }
+    }
+  }
+}
+```
+
+**Browser-only** (no API key needed):
+```json
+{
+  "tools": {
+    "webSearch": {
+      "provider": "browser"
+    }
+  }
+}
+```
+
+**Note**: The config format shown above is the current format. If you're using an older development version with `tools.webSearch.apiKey`, update to the new nested format shown in the examples.
+
+## 🤖 Using Subagents
+
+Subagents run in the background and handle tasks independently:
+
+```bash
+genieceo chat -m "Spawn a subagent to research the history of AI, while you create a summary document"
+```
+
+The agent will:
+1. Spawn a background subagent for research
+2. Continue with creating the summary
+3. Integrate the research results when the subagent completes
+
+## 📚 Examples
+
+### File Operations
+
+```bash
+genieceo chat -m "Create a hello.txt file with 'Hello, World!'"
+```
+
+### Web Search
+
+```bash
+genieceo chat -m "Search for the latest TypeScript features and summarize them"
+```
+
+### Shell Commands
+
+```bash
+genieceo chat -m "List all JavaScript files in the current directory"
+```
+
+### Complex Task with Subagents
+
+```bash
+genieceo chat -m "Create a Node.js web server with Express. Spawn subagents to create routes, middleware, and tests in parallel"
+```
+
+## 🎨 CLI Commands
+
+### `genieceo init`
+Initialize workspace and configuration
+
+### `genieceo onboard`
+Interactive setup wizard for configuring LLM and web search
+
+This command guides you through:
+- **LLM Provider Selection**: Choose from available providers (OpenAI, Anthropic, Google, etc.)
+- **API Key Configuration**: Enter your API keys securely
+- **Model Selection**: Pick from available models for your provider
+- **Health Check**: Test your LLM configuration with a real API call
+- **Web Search Setup**: Configure search providers (Tavily, Brave, or browser-based)
+
+Example:
+```bash
+genieceo onboard
+```
+
+### `genieceo chat`
+Start interactive chat mode
+
+**Options:**
+- `-m, --message <text>` - Send single message instead of interactive mode
+
+### `genieceo status`
+Show configuration and workspace status
+
+## 🏗️ Architecture
+
+```
+genieceo/
+├── src/
+│   ├── cli/            # CLI interface
+│   ├── agent/          # Agent loop, context, subagents
+│   ├── tools/          # Tool implementations
+│   ├── skills/         # Skill system & built-in skills
+│   ├── workspace/      # Workspace management
+│   ├── config/         # Configuration system
+│   └── providers/      # LLM provider (@mariozechner/pi-ai)
+```
+
+## 🔄 Switching LLM Providers
+
+genieceo uses @mariozechner/pi-ai, which provides:
+- **Automatic model discovery** - no hardcoded model lists
+- **15+ providers** - OpenAI, Anthropic, Google, Azure, Bedrock, Mistral, Groq, xAI, OpenRouter, and more
+- **Cross-provider handoffs** - switch models mid-conversation
+- **Unified interface** - same API for all providers
+
+### Available Providers
+
+To see all available providers and their models:
+
+```bash
+# The library automatically discovers all available models at runtime
+# Simply configure your provider and model in config.json
+```
+
+To use a different provider, simply update your config:
+
+```json
+{
+  "model": "anthropic:claude-3-5-sonnet-20241022",
+  "llm": {
+    "anthropic": {
+      "apiKey": "sk-ant-..."
+    }
+  }
+}
+```
+
+**Supported providers (examples):**
+- **OpenAI**: `openai:gpt-4o`, `openai:gpt-4o-mini`, `openai:o1`
+- **Anthropic**: `anthropic:claude-3-5-sonnet-20241022`, `anthropic:claude-3-5-haiku-20241022`
+- **Google**: `google:gemini-2.0-flash-exp`, `google:gemini-1.5-pro`
+- **Mistral**: `mistral:mistral-large-latest`, `mistral:mistral-small-latest`
+- **Groq**: `groq:llama-3.3-70b-versatile`, `groq:mixtral-8x7b-32768`
+- **xAI**: `xai:grok-beta`
+- **OpenRouter**: `openrouter:anthropic/claude-3.5-sonnet`
+- **Azure OpenAI**: Configure via environment variables
+- **Amazon Bedrock**: `bedrock:anthropic.claude-3-5-sonnet-20241022-v2:0`
+- **Cerebras**: `cerebras:llama3.3-70b`
+- **And 15+ more!**
+
+The model list is automatically discovered from each provider's API, so you always have access to the latest models without updating genieceo.
+
+## 🛡️ Safety
+
+- **Command blocking**: Dangerous commands (rm -rf, format, etc.) are blocked by default
+- **Workspace isolation**: Agent works in `~/.genieceo/workspace/files/` by default
+- **Timeout limits**: Commands have 30s timeout (configurable)
+- **API key security**: Keys stored in config file with restricted permissions
+
+## 🤝 Contributing
+
+Contributions welcome! The codebase is intentionally small and readable.
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Submit a pull request
+
+## 📝 License
+
+MIT License - see LICENSE file for details
+
+## 🙏 Acknowledgments
+
+Inspired by [nanobot](https://github.com/HKUDS/nanobot) - the ultra-lightweight Clawdbot alternative
+
+## 📞 Support
+
+- Issues: [GitHub Issues](https://github.com/yourusername/genieceo/issues)
+- Discussions: [GitHub Discussions](https://github.com/yourusername/genieceo/discussions)
+
+---
+
+Made with ❤️ for developers who want a lightweight, extensible AI agent