path: root/makima/daemon/README.md

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