# Khaos Machine - Getting Started

## What Was Installed

| Tool | Description |
|------|-------------|
| **khaosd** | Control plane daemon — REST API, web dashboard, project management (GUI embedded) |
| **Khaos Machine** | Menu bar app for daemon status and control (macOS) |
| `khaos-tui` | Terminal UI for screenplay analysis (alternative interface) |
| `khaos-tools` | CLI utilities for screenplay parsing and AI analysis |
| `khaos-wfl` | Background daemon for continuous project monitoring |
| `khaosd-ctl` | Daemon lifecycle helper (start/stop/restart/status/logs) |

**macOS/Linux:** Binaries are installed to `/usr/local/bin/`. Prompt templates are synced
to `~/.khaos/prompts/`. The menu bar app is installed to `/Applications/` (macOS only).

**Windows:** Extract the zip to a folder (e.g., `C:\khaos\`) and add it to your PATH.
Copy the included `prompts\` folder to `%USERPROFILE%\.khaos\prompts\`.

## Quick Start

### 1. Open the Dashboard

**macOS**: Click the **K** icon in the menu bar → **Projects**. The menu
bar app discovers the daemon automatically from `~/.khaos/runtime.json`.

**Linux**: Launch **Khaos Machine** from your application menu.

From the dashboard you can:
- Browse and manage your screenplay projects
- Import new projects
- Configure settings and AI providers
- View analysis dashboards

**Alternative: Terminal UI**

If you prefer a terminal interface:
```
khaos-tui
```

From the TUI:
- Press `c` to import a screenplay project
- Press `g` to configure your AI provider
- Press `?` for full keybinding help

### 2. Configure an AI Provider

Open **Settings** from the menu bar app or TUI (`g` key).

Supported providers:

- **ollama** — local inference, free, no API key needed
- **lm studio** — local inference via LM Studio, free, no API key needed (supports speculative decoding for 2-3x speedup)
- **openai** — GPT models via OpenAI API
- **anthropic** — Claude models via Anthropic API
- **mistral** — Mistral models via Mistral API
- **groq** — fast inference via Groq API

### 3. Daemon Management

**macOS/Linux:** The **khaosd** daemon starts automatically on login and auto-restarts
if it crashes — no manual intervention needed.

**Windows:** The daemon does not auto-start. Use `khaosd-ctl start` to start it
manually, or create a Windows Scheduled Task for automatic startup.

```
khaosd-ctl status            Check if running
khaosd-ctl stop              Graceful stop
khaosd-ctl start             Start immediately
khaosd-ctl restart           Stop + start
khaosd-ctl logs              Follow console log
khaosd-ctl logs --errors     Show recent errors only
```

### 4. Enable the WFL Background Watcher

The WFL daemon monitors your project for changes and runs analysis
automatically:

```
khaos-wfl-user-agent-enable /path/to/your/project
```

To disable:

```
khaos-wfl-user-agent-disable
```

## Key Paths

| Path | Purpose |
|------|---------|
| `~/.khaos/config.json` | khaosd settings (provider, model, projects root) |
| `~/.khaos/keys.json` | Provider API keys (restricted permissions) |
| `~/.khaos/runtime.json` | khaosd runtime metadata (port, PID) |
| `~/.khaos/prompts/` | Prompt templates used by khaos-tools |
| `~/.khaos/logs/` | Daemon and component logs |
| `~/.config/khaos-tui/config.json` | TUI configuration (AI provider, etc.) |
| `~/.config/khaos-wfl/daemon.env` | WFL daemon environment config |

## CLI Reference

```
khaos-tui                              Launch the terminal UI
khaos-tools --help                     Show CLI tool usage
khaos-wfl --help                       Show daemon usage
khaos-wfl-user-agent-enable <path>     Enable background daemon
khaos-wfl-user-agent-disable           Disable background daemon
khaosd                                 Start the control plane daemon
khaosd --version                       Show khaosd version
khaosd-ctl start                       Start daemon via system service manager
khaosd-ctl stop                        Stop the daemon
khaosd-ctl restart                     Restart the daemon
khaosd-ctl status                      Show daemon status (PID, port, version)
khaosd-ctl logs                        Follow console log
khaosd-ctl logs --errors               Show recent errors only
```

## Learn More

- Download page: <https://preview.khaosmachine.com>
- This file is saved at `~/.khaos/GETTING-STARTED.md`
