Skip to content

Getting Started

Install AI Sleepwalker as a uv tool - this keeps it isolated and available everywhere:

uv tool install git+https://github.com/safurrier/ai-sleepwalker.git

Or clone and install locally:

git clone https://github.com/safurrier/ai-sleepwalker.git
cd ai-sleepwalker
uv tool install .

Set Up API Keys

Choose an AI provider to generate dreams:

  1. Get a free API key from Google AI Studio
  2. Add to your shell profile (~/.bashrc, ~/.zshrc, etc.):
export GEMINI_API_KEY="your-actual-key-here"
  1. Reload your shell: source ~/.zshrc

OpenAI

  1. Get an API key from OpenAI
  2. Set the environment variable:
export OPENAI_API_KEY="sk-your-actual-key-here"

Anthropic (Claude)

  1. Get an API key from Anthropic Console
  2. Set the environment variable:
export ANTHROPIC_API_KEY="sk-ant-your-key-here"

Ollama (Local/Private)

For completely private, offline use:

  1. Install Ollama
  2. Pull a model: ollama pull llama3.2
  3. Use the model directly: sleepwalker ~/Documents --model ollama/llama3.2

First Run

Start sleepwalking in a safe directory:

sleepwalker ~/Documents

The sleepwalker will: 1. Wait for 5 minutes of inactivity (configurable) 2. Prevent your computer from sleeping 3. Explore the directory you specified 4. Generate dreams about what it finds 5. Save them to ~/.sleepwalker/dreams/

Common Options

# Custom idle timeout (seconds)
sleepwalker ~/Documents --idle-timeout 600

# Multiple directories
sleepwalker ~/Documents ~/Projects ~/Photos

# Specify AI model
sleepwalker ~/Documents --model gpt-4o-mini

# Dry run (no AI calls)
sleepwalker ~/Documents --dry-run

Troubleshooting

"No API key found"

Make sure you've set the environment variable and reloaded your shell.

"Permission denied" errors

The sleepwalker can only read files you have access to. This is normal for system directories.

Dreams aren't saving

Check that ~/.sleepwalker/dreams/ exists and is writable. The sleepwalker should create it automatically.

Computer still goes to sleep

Some systems require additional permissions for sleep prevention. The sleepwalker will log warnings if it can't prevent sleep.

What's Next?

Development Setup

Want to contribute? See the Developer Guide for setup instructions and contribution guidelines.