darwin.diy 0.1.0

package/README.md

@@ -0,0 +1,355 @@
+# Darwin
+
+A multi-agent management system for creating and managing evolving AI agents. Darwin allows you to configure multiple OpenAI-compatible providers and create specialized agents with their own tools and instructions.
+
+## Features
+
+- **Multi-Agent Management**: Create and manage multiple specialized AI agents
+- **Multi-Provider Support**: Configure multiple OpenAI-compatible providers (OpenAI, OpenRouter, Anthropic, local models, etc.)
+- **Agent-Specific Tools**: Each agent has its own tools directory for custom capabilities
+- **Self-Evolving Agents**: Agents can create and modify their own tools
+- **Interactive CLI**: Beautiful command-line interface built with Clack
+- **Flexible Model Selection**: Use format `<provider-id>/<model>` (e.g., `openai/gpt-4`, `openrouter/anthropic/claude-sonnet-4`)
+- **Custom Agent Instructions**: Each agent can have its own `AGENTS.md` instructions file
+
+## Installation
+
+```bash
+# Install Bun if you haven't already
+curl -fsSL https://bun.sh/install | bash
+
+# Clone and install dependencies
+git clone <repo-url>
+cd darwin
+bun install
+```
+
+## Quick Start
+
+### 1. Configure a Provider
+
+First, add an OpenAI-compatible provider:
+
+```bash
+bun start config
+```
+
+You'll be prompted for:
+- **Provider ID**: Unique identifier (e.g., `openai`, `openrouter`)
+- **Provider Name**: Display name (e.g., `OpenAI`)
+- **Base URL**: API endpoint (e.g., `https://api.openai.com/v1`)
+- **API Key**: Your API key
+
+### 2. Create an Agent
+
+Create a new agent:
+
+```bash
+bun start create
+```
+
+You'll be prompted for:
+- **Agent Name**: Display name (e.g., `My Assistant`)
+- **Provider**: Select from configured providers
+- **Model**: Model name (e.g., `gpt-4`, `anthropic/claude-sonnet-4`)
+- **Description**: Optional description
+
+### 3. Chat with an Agent
+
+Start chatting with an agent:
+
+```bash
+# Interactive selection
+bun start chat
+
+# Direct chat with specific agent
+bun start chat my-assistant
+```
+
+## Commands
+
+### `darwin config`
+
+Manage OpenAI-compatible providers:
+- Add/Update Provider
+- List Providers
+- Delete Provider
+
+### `darwin create`
+
+Create a new agent with:
+- Custom name
+- Provider selection
+- Model specification
+- Optional description
+
+### `darwin chat`
+
+Chat with agents:
+- `darwin chat` - Interactive agent selection menu
+- `darwin chat <agent-id>` - Chat directly with a specific agent
+
+## Configuration Structure
+
+Darwin stores configuration in `~/.config/darwin.diy/`:
+
+```
+~/.config/darwin.diy/
+├── providers.json       # Provider configurations (array)
+├── agents.json          # Agent configurations (array)
+└── agents/              # Agent-specific directories
+    └── <agent-id>/
+        ├── tools/       # Agent-specific custom tools
+        │   └── *.ts
+        └── AGENTS.md    # Agent-specific instructions
+```
+
+### Provider Configuration
+
+`providers.json`:
+```json
+[
+  {
+    "id": "openai",
+    "name": "OpenAI",
+    "baseURL": "https://api.openai.com/v1",
+    "apiKey": "sk-..."
+  },
+  {
+    "id": "openrouter",
+    "name": "OpenRouter",
+    "baseURL": "https://openrouter.ai/api/v1",
+    "apiKey": "sk-or-..."
+  }
+]
+```
+
+### Agent Configuration
+
+`agents.json`:
+```json
+[
+  {
+    "id": "my-assistant",
+    "name": "My Assistant",
+    "model": "openai/gpt-4",
+    "description": "A helpful general-purpose assistant"
+  },
+  {
+    "id": "code-reviewer",
+    "name": "Code Reviewer",
+    "model": "openrouter/anthropic/claude-sonnet-4",
+    "description": "Specialized in code review"
+  }
+]
+```
+
+## Model Format
+
+Models use the format: `<provider-id>/<model>`
+
+Examples:
+- `openai/gpt-4` - Uses `gpt-4` model with the `openai` provider
+- `openai/gpt-3.5-turbo` - Uses `gpt-3.5-turbo` with the `openai` provider
+- `openrouter/anthropic/claude-sonnet-4` - Uses `anthropic/claude-sonnet-4` with the `openrouter` provider
+- `local/llama-3` - Uses `llama-3` model with a local provider
+
+## Built-in Agent Tools
+
+Each agent comes with built-in self-modification tools:
+
+### `create_tool`
+
+Create a new tool for the agent.
+
+**Arguments:**
+- `name`: Tool name (becomes the filename)
+- `description`: What the tool does
+- `code`: Complete TypeScript code
+
+**Example:**
+```typescript
+{
+  name: "hello",
+  description: "Say hello",
+  code: `import { tool } from "@opencode-ai/plugin";
+
+export default tool({
+  description: "Say hello to someone",
+  args: {
+    name: tool.schema.string().describe("Name to greet"),
+  },
+  async execute(args, context) {
+    return \`Hello, \${args.name}!\`;
+  },
+});`
+}
+```
+
+### `reload_agent`
+
+Reload all tools and the AGENTS.md file. Called automatically after creating tools, but can be invoked manually.
+
+## Creating Custom Tools
+
+Tools are TypeScript files in the agent's `tools/` directory following the OpenCode tool specification:
+
+```typescript
+import { tool } from "@opencode-ai/plugin";
+
+export default tool({
+  description: "Tool description",
+  args: {
+    param: tool.schema.string().describe("Parameter description"),
+  },
+  async execute(args, context) {
+    // Tool implementation
+    // context contains: agent, sessionID, messageID, abort
+    return "result";
+  },
+});
+```
+
+### Multiple Tools Per File
+
+You can export multiple tools from a single file:
+
+```typescript
+import { tool } from "@opencode-ai/plugin";
+
+export const add = tool({
+  description: "Add two numbers",
+  args: {
+    a: tool.schema.number().describe("First number"),
+    b: tool.schema.number().describe("Second number"),
+  },
+  async execute(args) {
+    return args.a + args.b;
+  },
+});
+
+export const multiply = tool({
+  description: "Multiply two numbers",
+  args: {
+    a: tool.schema.number().describe("First number"),
+    b: tool.schema.number().describe("Second number"),
+  },
+  async execute(args) {
+    return args.a * args.b;
+  },
+});
+```
+
+This creates tools named `filename_add` and `filename_multiply`.
+
+## Agent Instructions
+
+Each agent can have custom instructions in its `AGENTS.md` file. This content is loaded into the agent's system prompt.
+
+Example `~/.config/darwin.diy/agents/code-reviewer/AGENTS.md`:
+
+```markdown
+# Code Review Agent
+
+You are a specialized code review agent. When reviewing code:
+
+1. Check for potential bugs and security issues
+2. Verify code style and best practices
+3. Suggest improvements for readability
+4. Identify performance optimizations
+
+Be thorough but constructive in your feedback.
+```
+
+## Example Workflow
+
+```bash
+# 1. Configure OpenAI provider
+bun start config
+# Select: Add/Update Provider
+# ID: openai
+# Name: OpenAI
+# Base URL: https://api.openai.com/v1
+# API Key: sk-...
+
+# 2. Configure OpenRouter provider
+bun start config
+# Select: Add/Update Provider
+# ID: openrouter
+# Name: OpenRouter
+# Base URL: https://openrouter.ai/api/v1
+# API Key: sk-or-...
+
+# 3. Create a general assistant
+bun start create
+# Name: General Assistant
+# Provider: openai
+# Model: gpt-4
+# Description: General purpose assistant
+
+# 4. Create a code reviewer
+bun start create
+# Name: Code Reviewer
+# Provider: openrouter
+# Model: anthropic/claude-sonnet-4
+# Description: Specialized code reviewer
+
+# 5. Chat with code reviewer
+bun start chat code-reviewer
+```
+
+## Development
+
+```bash
+# Run in development mode with auto-reload
+bun run dev
+
+# Run directly
+bun run src/index.ts
+
+# Type checking
+bun run typecheck
+
+# Linting
+bun run lint
+
+# Both checks
+bun run check
+```
+
+## How It Works
+
+1. **Provider Configuration**: Configure multiple OpenAI-compatible API providers
+2. **Agent Creation**: Create specialized agents with specific models and providers
+3. **Tool Loading**: Each agent loads tools from its own `agents/<agent-id>/tools/` directory
+4. **System Prompt**: Each agent loads its own `AGENTS.md` file for custom instructions
+5. **Chat Loop**: User interacts with selected agent via chat interface
+6. **Tool Execution**: Agent can call tools, including self-modification tools
+7. **Reload**: After creating/editing tools, agent reloads without losing conversation history
+
+## Troubleshooting
+
+**Tools not loading:**
+- Check that tool files are valid TypeScript
+- Ensure they use the `tool()` helper from `@opencode-ai/plugin`
+- Check console for error messages
+- Verify tools are in the correct agent's tools directory
+
+**API errors:**
+- Verify your provider base URL is correct
+- Check that your API key is valid
+- Ensure the model name matches your provider's available models
+- Check the model format is `<provider-id>/<model>`
+
+**Agent not found:**
+- Run `darwin config` to list configured providers
+- Check `~/.config/darwin.diy/agents.json` for agent configuration
+- Verify the agent ID matches (use the sanitized version of the name)
+
+**Permission errors:**
+- Make sure `~/.config/darwin.diy/` is writable
+- Check file permissions in agent directories
+
+## License
+
+GPL 3.0 or later