Add README.md with comprehensive documentation

Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com>
2026-03-19 13:44:39 +01:00
parent 5dd7c652c5
commit d4cebe21c7
1 changed files with 211 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,211 @@
+# svibe
+
+**Agentic CLI tool with hierarchical agents, multi-provider support, and MCP protocol**
+
+svibe is an intelligent command-line assistant that uses AI agents to help with development tasks. It coordinates multiple AI models, provides built-in development tools, and supports the Model Context Protocol (MCP) for extensibility.
+
+## Features
+
+- **Multi-Provider Support**: OpenAI (cloud) and Ollama (local) with bearer/basic authentication
+- **Hierarchical Agents**: Supervisor agent coordinates specialized sub-agents
+- **Smart Model Routing**: Different models for different task types (chat, code, planning)
+- **Built-in Tools**: File operations, shell commands, git operations
+- **MCP Protocol**: Connect to external MCP servers for additional tools/resources
+- **Project Configs**: Local `.svibe/config.toml` overrides global settings
+
+## Quick Start
+
+### Installation
+
+```bash
+# Build from source
+git clone https://github.com/yourusername/svibe.git
+cd svibe
+cargo build --release
+
+# Binary location
+./target/release/svibe --help
+```
+
+### Setup
+
+```bash
+# Initialize global configuration
+svibe init
+
+# Set your API key
+export OPENAI_API_KEY=your-api-key
+
+# Or initialize with local project config
+svibe init --local
+```
+
+### Usage
+
+```bash
+# Interactive REPL mode
+svibe repl
+
+# Run a single task
+svibe run "Fix the bug in main.rs"
+
+# Use specific agent
+svibe -a code run "Write a function to parse JSON"
+
+# Show status
+svibe status
+
+# List tools
+svibe tools
+```
+
+## Configuration
+
+### Config Locations
+
+| Type | Path | Priority |
+|------|------|----------|
+| Global | `~/.config/svibe/config.toml` | 1 (lowest) |
+| Local | `.svibe/config.toml` | 2 (overrides global) |
+| Env Vars | `OPENAI_API_KEY`, `OLLAMA_HOST` | 3 (highest) |
+
+### Example Configuration
+
+```toml
+# ~/.config/svibe/config.toml
+
+[providers.openai]
+api_key = "sk-..."  # Or set OPENAI_API_KEY env var
+base_url = "https://api.openai.com/v1"
+default_model = "gpt-4o"
+
+[providers.ollama]
+base_url = "http://localhost:11434"
+default_model = "llama3"
+# Bearer token auth (for cloud-hosted Ollama-compatible APIs)
+bearer_token = "your-token"
+# OR Basic auth
+# username = "user"
+# password = "pass"
+
+[agents.default]
+description = "Default general-purpose agent"
+system_prompt = "You are a helpful AI assistant."
+tools = ["file", "shell", "git"]
+
+[agents.default.models]
+chat = "ollama/llama3"
+code = "openai/gpt-4o"
+planning = "openai/gpt-4o"
+tool_use = "openai/gpt-4o"
+default = "ollama/llama3"
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `svibe init` | Initialize global configuration |
+| `svibe init --local` | Create project-specific config |
+| `svibe repl` | Start interactive REPL mode |
+| `svibe run "<task>"` | Execute a single task |
+| `svibe status` | Show agent and provider status |
+| `svibe tools` | List available tools |
+| `svibe agents` | List available agents |
+| `svibe health` | Health check providers |
+| `svibe mcp list` | List connected MCP servers |
+| `svibe mcp connect <name> <cmd>` | Connect MCP server |
+
+## REPL Mode
+
+```bash
+svibe repl
+```
+
+REPL commands:
+- `/help` - Show help
+- `/clear` - Clear screen
+- `/status` - Show agent status
+- `/exit`, `/quit`, `:q` - Exit REPL
+
+## Built-in Tools
+
+### File Tools
+- `read` - Read file contents
+- `write` - Write content to file
+- `edit` - Edit file at specific line
+- `search` - Search for pattern in file
+- `list` - List directory contents
+
+### Shell Tools
+- Execute shell commands with safety checks
+- Blocks dangerous patterns (rm -rf, etc.)
+- Configurable timeout
+
+### Git Tools
+- `status`, `diff`, `commit`
+- `branch`, `checkout`, `merge`, `rebase`
+- `log`, `add`
+
+## MCP Support
+
+Connect to Model Context Protocol servers for additional tools:
+
+```bash
+# List connected servers
+svibe mcp list
+
+# Connect a server
+svibe mcp connect filesystem npx -y @modelcontextprotocol/server-filesystem /path/to/allow
+
+# Disconnect
+svibe mcp disconnect filesystem
+```
+
+## Architecture
+
+```
+svibe/
+├── src/
+│   ├── main.rs           # CLI entry point
+│   ├── config/           # Configuration system
+│   ├── providers/        # AI model providers
+│   ├── tools/            # Built-in tools
+│   ├── mcp/              # MCP protocol
+│   ├── agents/           # Agent system
+│   └── cli/              # CLI interface
+```
+
+## Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `OPENAI_API_KEY` | OpenAI API key | - |
+| `OLLAMA_HOST` | Ollama host URL | `http://localhost:11434` |
+| `RUST_LOG` | Logging level | `svibe=info` |
+
+## Development
+
+```bash
+# Build debug
+cargo build
+
+# Build release
+cargo build --release
+
+# Run with args
+cargo run -- run "test task"
+
+# Run tests
+cargo test
+
+# Format code
+cargo fmt
+
+# Lint
+cargo clippy
+```
+
+## License
+
+MIT