Project Data Format

Khaos Machine stores projects using KSPD (Khaos Screenplay Data) — a plain-file format designed to be readable, portable, and easy to back up.

Where Data Lives

By default, projects are stored under ~/.khaos/projects/. Each project is a directory:

~/.khaos/projects/my-screenplay/
├── screenplay.fountain       # Original screenplay file
├── elements/                 # Extracted entities
│   ├── scenes/               # One JSON file per scene
│   ├── characters/           # One JSON file per character
│   └── locations/            # One JSON file per location
├── analysis/                 # AI analysis results
│   ├── openai/               # Results from OpenAI
│   │   ├── scenes/
│   │   ├── characters/
│   │   └── locations/
│   └── ollama/               # Results from Ollama
│       ├── scenes/
│       ├── characters/
│       └── locations/
├── audio/                    # Generated dialogue audio
└── events.jsonl              # Event log

Key Characteristics

• Plain files — everything is JSON, JSONL, or the original screenplay format. No database.
• Per-provider analysis — results from different AI providers are stored separately, never overwritten.
• Portable — copy the directory anywhere and it works. No registry, no hidden state.
• Git-friendly — JSON files are text, so they diff and merge cleanly.
• iCloud-compatible — works with file sync services without conflicts.

Backing Up

Since KSPD projects are plain directories, back them up with any method:

# Simple copy
cp -r ~/.khaos/projects/my-screenplay ~/backups/

# Archive
tar czf my-screenplay-backup.tar.gz ~/.khaos/projects/my-screenplay/

# Sync to external drive
rsync -av ~/.khaos/projects/ /Volumes/Backup/khaos-projects/

Settings and Configuration

Global settings are stored separately from projects:

File	Purpose
~/.khaos/config.json	Application settings (provider, model, preferences)
~/.khaos/keys.json	API keys (0600 permissions)
~/.khaos/runtime.json	Daemon runtime state (port, PID) — ephemeral
~/.khaos/logs/	Log files

Data Privacy

• All data stays on your machine — there is no cloud sync, no telemetry, no analytics.
• When using cloud AI providers (OpenAI, Anthropic, etc.), screenplay text is sent to their API for analysis. See each provider's privacy policy.
• When using local providers (Ollama, LM Studio), nothing leaves your machine.