SeekClaw

<h1 align="center">SeekClaw</h1> <div align="center"> [](https://opensource.org/licenses/MIT) [](https://dotnet.microsoft.com/) [](https://github.com/umr-xiaomai/SeekClaw/stargazers) [](https://github.com/umr-xiaomai/SeekClaw/network/members) [](https://github.com/umr-xiaomai/SeekClaw/issues) [](https://github.com/umr-xiaomai/SeekClaw/pulls) [](https://github.com/umr-xiaomai/SeekClaw/actions) **Modern, High-Performance AI Agent Runtime** SeekClaw is a high-performance AI Agent runtime built on .NET 10.0, adopting clean architecture and event-driven design. It provides a complete platform for building AI-driven coding assistants, supporting multiple LLM providers, tool execution, session management, and smooth terminal interaction. [English](README_EN.md) • [Getting Started](#installation) • [Features](#features) • [Contribution Guide](#contribution-guide) </div> ## ✨ Features ### 🚀 Runtime First Architecture - **Clean Architecture**: With `seekclaw_runtime` as the core, `seekclaw_cli` as the default frontend, and separated concerns - **Plugin System**: Scalability through Tools, Skills, and MCP (Model Context Protocol) - **Event-Driven**: Decoupled rendering and business logic through event bus ### 🤖 Multi-Provider Support - **OpenAI Compatible**: GPT-5.5, GPT-5.5-mini, and all OpenAI compatible APIs - **Anthropic**: Claude Opus, Claude Sonnet, Claude Haiku - **Google**: Gemini Pro, Gemini Flash - **Local Models**: Ollama, LM Studio - **Intelligent Routing**: Fast, balanced, quality, economical, offline, and more strategies - **Failover**: Automatic retries, exponential backoff, and circuit breaker mechanism ### 🛠️ Tool Ecosystem - **Built-in Tools**: File operations (read/write/edit), search (grep/glob), bash execution - **MCP Support**: stdio and SSE transport, automatic discovery of tools/prompts/resources - **Skill System**: Directory-based skill system, supporting prompt injection and workflow ### 💻 Modern Terminal Experience - **Game-like Rendering**: 30-60 FPS refresh rate, double buffering technique - **Streaming Output**: Real-time token streaming, displaying thinking/inference process - **Real-time UI**: Loading animation, progress bar, tool status, and Markdown rendering - **Incremental Updates**: Flicker-free, scroll-free, smooth animation ### 📁 Workspace Management - **Project Recognition**: Automatic recognition of Git, .NET, Node.js, Python, Rust, Go, Unity, Vue projects - **Isolated Configuration**: Independent configuration, session, cache, and memory for each workspace - **Automatic Initialization**: Automatic creation of `.seekclaw/` directory structure ### 🔧 Developer Experience - **Session Management**: JSONL-based session persistence and recovery - **Memory System**: Workspace-specific memory, automatic context injection - **Verification Mechanism**: Automatic build/check/fix cycle after code modification - **Hot Reload**: Prompts and configuration can be reloaded without restarting ## 📦 Installation ### Prerequisites - .NET 10.0 SDK or higher - Git (for workspace detection) ### Build from Source ```bash git clone https://github.com/umr-xiaomai/SeekClaw.git cd SeekClaw dotnet build ``` ### Run ```bash # Interactive chat mode dotnet run --project seekclaw_cli # Single prompt dotnet run --project seekclaw_cli -- "Explain the architecture of this project" # Continue previous session dotnet run --project seekclaw_cli -- --continue # Resume specific session dotnet run --project seekclaw_cli -- --resume <session-id> # Override model dotnet run --project seekclaw_cli -- --model "openai/gpt-5.5" ``` ## 🏗️ Architecture Design ```mermaid flowchart TD subgraph Frontends[Frontends] CLI[seekclaw_cli<br/>System.CommandLine + Rendering Engine] GUI[GUI / Web / IDE<br/>Future] end subgraph Runtime[seekclaw_runtime] Facade[SeekClawRuntime<br/>Composition Root / Facade] Agent[Agent Main Loop] Bus[(EventBus)] subgraph Provider[Provider Layer] PM[ProviderManager<br/>Routing · Retries · Failover · Circuit Breaker] MR[ModelRegistry] OAI[OpenAiCompatibleClient] ANT[AnthropicClient] HC[HealthChecker] UT[UsageTracker] end subgraph Plugins[Plugin System] TR[ToolRegistry] PR[PromptRegistry] SK[SkillManager] MCP[McpManager<br/>stdio / SSE] end PP[PromptProvider<br/>File-based · Hot Loading · Variables] WS[WorkspaceManager] SS[SessionStore] VF[BuildVerifier] CFG[ConfigStore<br/>~/.seekclaw/config.json] DMN[DaemonServer<br/>Named Pipe / Unix Socket] end CLI --> Facade GUI -. daemon protocol .-> DMN DMN --> Agent Facade --> Agent Agent --> PM Agent --> TR Agent --> VF Agent --> SS Agent --> Bus PM --> MR PM --> OAI PM --> ANT PM --> UT SK --> PR MCP --> TR MCP --> PR Agent --> PP PP --> PR WS --> CFG Bus --> CLI ``` ## 📁 Project Structure ``` SeekClaw/ ├── seekclaw_cli/ # CLI Frontend │ ├── Commands/ # CLI Commands (provider, model, profile, etc.) │ ├── Ui/ # Terminal Rendering Engine │ └── Program.cs # Entry Point ├── seekclaw_runtime/ # Core Runtime │ ├── Agents/ # Agent Loop and Context Planning │ ├── Configuration/ # Configuration Management │ ├── Events/ # Event Bus System │ ├── Mcp/ # MCP Client Implementation │ ├── Prompts/ # Prompt Loading and Composition │ ├── Providers/ # LLM Provider Integration │ ├── Sessions/ # Session Persistence │ ├── Skills/ # Skill Management │ ├── Tools/ # Tool Registration and Implementation │ ├── Verification/ # Build Verification │ └── Workspaces/ # Workspace Detection and Management ├── seekclaw_tests/ # Unit Tests ├── docs/ # Documentation ├── prompts/ # Prompt Templates (Future) ├── skills/ # Skill Definitions (Future) └── mcp/ # MCP Server Configuration (Future) ``` ## ⚙️ Configuration ### Global Configuration Located at `~/.seekclaw/config.json`: ```json { "providers": { "openai": { "apiKey": "sk-...", "baseUrl": "https://api.openai.com/v1" }, "anthropic": { "apiKey": "sk-ant-..." } }, "profiles": { "default": { "provider": "openai", "model": "gpt-5.5" } }, "agent": { "maxSteps": 10, "maxRepairAttempts": 3, "autoVerify": true } } ``` ### Workspace Configuration Each project can override in `.seekclaw/config.json`: - Provider and model selection - Temperature and context settings - Tool permissions - Skill configuration - MCP server settings ## 🎯 Usage Examples ### Interactive Chat ```bash seekclaw chat # or directly seekclaw ``` ### Single Task ```bash seekclaw "Refactor the authentication module to use JWT" seekclaw "Write unit tests for the UserService class" seekclaw "Fix build errors in the project" ``` ### Provider Management ```bash seekclaw provider list seekclaw provider add openai --api-key sk-... seekclaw provider test openai seekclaw provider use anthropic ``` ### Model Management ```bash seekclaw model list seekclaw model use openai/gpt-5.5 seekclaw model info claude-opus seekclaw model search "fast coding model" ``` ### Session Management ```bash seekclaw session list seekclaw session resume <session-id> seekclaw session export <session-id> --format json ``` ### Health Check ```bash seekclaw doctor ``` ## 🔌 Extending SeekClaw ### Add Tool Implement `ITool` interface: ```csharp public class MyTool : ITool { public string Name => "my_tool"; public string Description => "Perform useful operation"; public JsonElement ParameterSchema => /* JSON schema */; public bool Mutating => false; public string StatusLabel => "Running my tool"; public async Task<ToolResult> ExecuteAsync( JsonObject args, ToolContext ctx, CancellationToken ct) { // Implementation } } ``` ### Create Skill Create in `skills/` directory: ``` skills/ my-skill/ skill.yaml # Metadata and configuration prompt.txt # Prompt template tools/ # Optional tool implementation ``` ### MCP Server Configure in `mcp/servers.json`: ```json { "servers": { "my-server": { "command": "node", "args": ["path/to/server.js"], "transport": "stdio" } } } ``` ## 🧪 Tests ```bash # Run all tests dotnet test seekclaw_tests # Run specific test class dotnet test seekclaw_tests --filter "ClassName=ProviderTests" ``` ## 📊 Monitoring SeekClaw includes built-in monitoring: - **Usage Statistics**: Token count, cost, response time - **Health Check**: Provider availability and latency - **Circuit Breaker**: Automatic failure detection and recovery - **Session Analysis**: Conversation history and patterns ## 🤝 Contribution Guide 1. Fork this repository 2. Create a feature branch (`git checkout -b feature/amazing-feature`) 3. Commit changes (`git commit -m 'Add amazing feature'`) 4. Push to branch (`git push origin feature/amazing-feature`) 5. Create a Pull Request ### Development Guidelines - Follow SOLID principles - Keep clean architecture - Write unit tests for new features - Store prompts in external files (no hardcoded strings) - Use event-driven pattern for UI updates ## 📄 License This project is licensed under the MIT License - see [LICENSE](LICENSE) file for details. ## 🙏 Acknowledgements - Built with .NET 10.0 and System.CommandLine - Uses Spectre.Console for terminal rendering - Follows clean architecture and vertical slice pattern - Adopts Native AOT-friendly design principles --- **SeekClaw** - Modern .NET-based high-performance AI Agent Runtime.