diff options
Diffstat (limited to 'makima/daemon/README.md')
| -rw-r--r-- | makima/daemon/README.md | 353 |
1 files changed, 0 insertions, 353 deletions
diff --git a/makima/daemon/README.md b/makima/daemon/README.md deleted file mode 100644 index 7c577c5..0000000 --- a/makima/daemon/README.md +++ /dev/null @@ -1,353 +0,0 @@ -# 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) |