Skip to main content

Frequently Asked Questions

Does my screenplay data stay private?​

With local providers (Ollama, LM Studio), yes — everything runs on your machine and nothing leaves your disk. With cloud providers (OpenAI, Anthropic, Mistral, Groq), screenplay text is sent to their API servers for processing. Review each provider's privacy policy for details.

Can I use Khaos Machine offline?​

Yes. Install Ollama and pull a model while online. After that, all analysis runs locally with no internet connection required.

What screenplay formats are supported?​

Fountain (.fountain), Final Draft (.fdx), ScriptBuilder (.sbx), Markdown (.md), PDF (.pdf), and plain text (.txt). PDF requires pdftotext installed on your system.

Which AI provider should I start with?​

Ollama is recommended for getting started — it's free, runs locally, and requires no API key. Install Ollama and pull qwen3:8b for a good balance of quality and speed. See AI Providers for all options.

Can I use multiple AI providers?​

Yes. Analysis results are stored per-provider, so you can analyze with Ollama first, then re-analyze with OpenAI and compare both sets of results. Switching providers never overwrites previous analysis.

Where is my data stored?​

Projects are stored in ~/.khaos/projects/ by default. Settings in ~/.khaos/config.json. API keys in ~/.khaos/keys.json. All plain files — no database.

How do I back up my projects?​

Copy the project directory. KSPD projects are plain files on disk:

cp -r ~/.khaos/projects/my-project ~/backups/

See Project Data Format for details on the directory structure.

Do I need an account to use Khaos Machine?​

No. Khaos Machine has no accounts, no sign-up, and no telemetry. If you use a cloud AI provider, you need an API key from that provider — but Khaos Machine itself requires nothing.

What platforms are supported?​

  • macOS — Apple Silicon (arm64), signed .pkg installer
  • Linux — amd64 and arm64, .deb and .rpm packages
  • Windows — amd64, .zip archive

How do I update to the latest version?​

Download the latest installer from khaosmachine.com and run it. The installer replaces existing binaries. Your projects and settings are preserved.

Why does character analysis require scene analysis first?​

Character and location analysis use scene analysis as context — they build on the understanding of how each character appears and behaves across scenes. This produces more accurate and nuanced character profiles.

Can I export analysis results?​

Analysis results are stored as JSON files in your project directory (analysis/ subdirectory). You can read them directly or use the CLI:

khaos-tools query characters ~/my-project

The analysis seems wrong. What should I do?​

AI analysis provides one perspective — it's a starting point, not the final word. If results don't match your intent:

  • Try a different AI provider or model for comparison.
  • Use signals to mark feedback as "ignored" if it's not relevant.
  • Trust your creative instincts over AI suggestions.