# koku (刻)

A cron daemon written in Rust. Single binary that manages and runs scheduled jobs.

## Install

```sh
just install
```

This builds a release binary and symlinks `ku` as an alias.

## Quick start

```sh
ku init                  # scaffold ~/.config/koku/config.toml
ku check                 # validate config, preview schedule
ku daemon start          # start the daemon
ku status                # view job states
```

## Config

`~/.config/koku/config.toml`

```toml
[[job]]
name = "backup"
cron = "0 2 * * *"
command = "bash backup.sh"
dir = "/home/user/scripts"
on_error = "backoff"      # continue | backoff | stop (default: continue)
overlap = false           # allow concurrent runs (default: false)
timeout = "30m"           # kill after duration (optional)

[[job]]
name = "cleanup"
cron = "*/15 * * * *"
command = "python3 cleanup.py"
```

### Error policies

- **continue** — ignore failures, keep scheduling (default)
- **backoff** — exponential backoff on failure (2^n seconds, capped at ~17 min)
- **stop** — disable after 3 consecutive failures, requires `ku resume`

## CLI

```
ku init              scaffold config with examples
ku check             validate config, preview next-run times
ku daemon start      start daemon in background
ku daemon stop       stop daemon
ku daemon run        run daemon in foreground
ku status            table of all jobs with state/timing
ku status --json     machine-readable output
ku run <name>        trigger one-off run
ku pause <name>      pause a job
ku resume <name>     resume a paused/stopped job
ku reload            reload config without restarting
```

## Web dashboard

Use [kagaya](https://github.com/anomalyco/kagaya) (`ky serve`) for a web UI. kagaya connects to koku's Unix socket and provides cron status, one-off runs, and pause/resume from the browser.

## Dependencies

- [muzan](https://github.com/anomalyco/muzan) — daemon lifecycle (Unix socket IPC, PID management)
- [croner](https://crates.io/crates/croner) — cron expression parsing
- [tokio](https://crates.io/crates/tokio) — async runtime
