Initial Control system

1 files changed, 353 insertions, 0 deletions

diff --git a/makima/daemon/README.md b/makima/daemon/README.md
new file mode 100644
index 0000000..7c577c5
--- /dev/null
+++ b/makima/daemon/README.md
@@ -0,0 +1,353 @@
+# Makima Daemon
+
+The Makima daemon connects to the Makima server and executes tasks using Claude Code in isolated git worktrees.
+
+## Installation
+
+```bash
+cd makima/daemon
+cargo build --release
+```
+
+The binary will be at `target/release/makima-daemon`.
+
+## Quick Start
+
+```bash
+# Set required environment variables
+export MAKIMA_API_KEY="your-api-key"
+export MAKIMA_DAEMON_SERVER_URL="ws://localhost:8080"
+
+# Run the daemon
+makima-daemon
+```
+
+## Configuration
+
+Configuration is loaded from multiple sources in order of precedence (highest first):
+
+1. CLI arguments
+2. Environment variables
+3. `./makima-daemon.toml` (current directory)
+4. `~/.config/makima-daemon/config.toml` (user config)
+5. `/etc/makima-daemon/config.toml` (system config, Linux only)
+
+### Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `MAKIMA_API_KEY` | API key for authentication (preferred) |
+| `MAKIMA_DAEMON_SERVER_URL` | WebSocket URL of the Makima server |
+| `MAKIMA_DAEMON_SERVER_APIKEY` | Alternative to MAKIMA_API_KEY |
+| `MAKIMA_DAEMON_PROCESS_MAXCONCURRENTTASKS` | Max concurrent tasks |
+
+### CLI Arguments
+
+```
+makima-daemon [OPTIONS]
+
+Options:
+  -c, --config <PATH>        Path to config file
+  -s, --server-url <URL>     WebSocket URL of makima server
+  -k, --api-key <KEY>        API key for authentication
+  -m, --max-tasks <N>        Maximum concurrent tasks
+  -l, --log-level <LEVEL>    Log level (trace, debug, info, warn, error)
+      --repos-dir <PATH>     Directory for cloned repositories
+      --worktrees-dir <PATH> Directory for worktrees
+  -h, --help                 Print help
+  -V, --version              Print version
+```
+
+---
+
+## Configuration File Reference
+
+Below is a complete configuration file with all options and their defaults.
+
+```toml
+# =============================================================================
+# Server Connection
+# =============================================================================
+[server]
+# WebSocket URL of the Makima server (required)
+url = "ws://localhost:8080"
+
+# API key for authentication (required)
+# Can also be set via MAKIMA_API_KEY environment variable
+api_key = "your-api-key"
+
+# Heartbeat interval in seconds (default: 30)
+heartbeat_interval_secs = 30
+
+# Reconnect interval after connection loss in seconds (default: 5)
+reconnect_interval_secs = 5
+
+# Maximum reconnect attempts before giving up (default: 0 = infinite)
+max_reconnect_attempts = 0
+
+# =============================================================================
+# Worktree Settings
+# =============================================================================
+[worktree]
+# Base directory for task worktrees (default: ~/.makima/worktrees)
+base_dir = "/home/user/.makima/worktrees"
+
+# Directory for cached repository clones (default: ~/.makima/repos)
+repos_dir = "/home/user/.makima/repos"
+
+# Branch prefix for task branches (default: "makima/task-")
+branch_prefix = "makima/task-"
+
+# Clean up old worktrees on daemon start (default: false)
+cleanup_on_start = false
+
+# Default target repository for pushing completed branches
+# Used when task.target_repo_path is not set
+default_target_repo = "/home/user/projects/my-repo"
+
+# =============================================================================
+# Process Settings (Claude Code)
+# =============================================================================
+[process]
+# Path or command for Claude Code CLI (default: "claude")
+claude_command = "claude"
+
+# Additional arguments to pass to Claude Code (after default arguments)
+# Default arguments are: --output-format=stream-json --input-format=stream-json
+#                        --verbose --dangerously-skip-permissions
+claude_args = ["--model", "opus"]
+
+# Arguments to pass before default arguments (for overriding defaults)
+claude_pre_args = []
+
+# Enable Claude's permission system (default: false)
+# When true, removes --dangerously-skip-permissions flag
+enable_permissions = false
+
+# Disable verbose output (default: false)
+# When true, removes --verbose flag
+disable_verbose = false
+
+# Maximum concurrent tasks (default: 4)
+max_concurrent_tasks = 4
+
+# Default timeout for tasks in seconds (default: 0 = no timeout)
+default_timeout_secs = 0
+
+# Additional environment variables to pass to Claude Code
+[process.env_vars]
+ANTHROPIC_API_KEY = "sk-ant-..."
+CUSTOM_VAR = "value"
+
+# =============================================================================
+# Repository Auto-Clone
+# =============================================================================
+[repos]
+# Directory to clone repositories into (default: ~/.makima/home)
+home_dir = "/home/user/.makima/home"
+
+# List of repositories to auto-clone on startup
+# Repositories that already exist are skipped
+
+# Simple format - just URLs
+auto_clone = [
+  "https://github.com/user/repo1.git",
+  "https://github.com/user/repo2.git",
+]
+
+# Shorthand format supported:
+#   github:user/repo  -> https://github.com/user/repo.git
+#   gitlab:user/repo  -> https://gitlab.com/user/repo.git
+auto_clone = [
+  "github:anthropics/claude-code",
+  "gitlab:company/project",
+]
+
+# Detailed format with options (use [[repos.auto_clone]] for each entry)
+[[repos.auto_clone]]
+url = "github:user/repo"
+name = "custom-directory-name"  # Optional: override directory name
+branch = "develop"              # Optional: checkout specific branch
+shallow = true                  # Optional: shallow clone (--depth 1)
+
+[[repos.auto_clone]]
+url = "https://github.com/org/large-repo.git"
+shallow = true  # Faster clone for large repos
+
+# =============================================================================
+# Local Database
+# =============================================================================
+[local_db]
+# Path to local SQLite database (default: ~/.makima/daemon.db)
+path = "/home/user/.makima/daemon.db"
+
+# =============================================================================
+# Logging
+# =============================================================================
+[logging]
+# Log level: trace, debug, info, warn, error (default: "info")
+level = "info"
+
+# Log format: "pretty" or "json" (default: "pretty")
+format = "pretty"
+```
+
+---
+
+## Examples
+
+### Minimal Configuration
+
+```toml
+[server]
+url = "ws://localhost:8080"
+api_key = "your-api-key"
+```
+
+### Production Configuration
+
+```toml
+[server]
+url = "wss://api.makima.example.com/daemon"
+api_key = "prod-api-key"
+heartbeat_interval_secs = 30
+reconnect_interval_secs = 10
+max_reconnect_attempts = 0
+
+[worktree]
+base_dir = "/var/lib/makima/worktrees"
+repos_dir = "/var/lib/makima/repos"
+cleanup_on_start = true
+
+[process]
+max_concurrent_tasks = 8
+default_timeout_secs = 3600  # 1 hour timeout
+
+[logging]
+level = "info"
+format = "json"
+```
+
+### Development with Custom Claude
+
+```toml
+[server]
+url = "ws://localhost:8080"
+api_key = "dev-key"
+
+[process]
+# Use a specific claude binary
+claude_command = "/usr/local/bin/claude-dev"
+
+# Add custom arguments
+claude_args = ["--model", "sonnet", "--max-turns", "50"]
+
+# Enable permission prompts for testing
+enable_permissions = true
+
+[process.env_vars]
+ANTHROPIC_API_KEY = "sk-ant-dev-..."
+DEBUG = "1"
+
+[logging]
+level = "debug"
+```
+
+### Auto-Clone Team Repositories
+
+```toml
+[server]
+url = "ws://localhost:8080"
+api_key = "team-key"
+
+[repos]
+home_dir = "/home/dev/.makima/projects"
+
+# Clone all team repos on startup
+[[repos.auto_clone]]
+url = "github:myteam/frontend"
+branch = "main"
+
+[[repos.auto_clone]]
+url = "github:myteam/backend"
+branch = "main"
+
+[[repos.auto_clone]]
+url = "github:myteam/shared-libs"
+shallow = true  # Only need latest commit
+```
+
+---
+
+## Directory Structure
+
+After running, the daemon creates the following directories:
+
+```
+~/.makima/
+├── daemon.db          # Local state database
+├── worktrees/         # Task worktrees (temporary)
+│   └── task-abc123/   # Individual task worktree
+├── repos/             # Cached repository clones
+│   └── repo-name/     # Bare clone for worktree creation
+└── home/              # Auto-cloned repositories
+    └── my-repo/       # Full repository clone
+```
+
+---
+
+## Troubleshooting
+
+### Connection Issues
+
+```bash
+# Check server connectivity
+curl -I http://localhost:8080/health
+
+# Run with debug logging
+makima-daemon --log-level debug
+```
+
+### Claude Code Not Found
+
+```bash
+# Verify claude is installed and in PATH
+which claude
+claude --version
+
+# Or specify full path in config
+[process]
+claude_command = "/full/path/to/claude"
+```
+
+### Permission Errors
+
+If Claude Code requires permissions, either:
+
+1. Use `--dangerously-skip-permissions` (default behavior)
+2. Set `enable_permissions = true` and handle permission prompts
+3. Pre-configure Claude Code permissions in `~/.claude/`
+
+### Task Timeouts
+
+Set an appropriate timeout for long-running tasks:
+
+```toml
+[process]
+default_timeout_secs = 7200  # 2 hours
+```
+
+---
+
+## Environment Variable Reference
+
+All configuration options can be set via environment variables using the pattern:
+`MAKIMA_DAEMON_<SECTION>_<KEY>`
+
+Examples:
+- `MAKIMA_DAEMON_SERVER_URL` -> `server.url`
+- `MAKIMA_DAEMON_PROCESS_MAXCONCURRENTTASKS` -> `process.max_concurrent_tasks`
+- `MAKIMA_DAEMON_LOGGING_LEVEL` -> `logging.level`
+
+Special case:
+- `MAKIMA_API_KEY` -> `server.api_key` (preferred method)