# 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)
