I live above your taskbar. When your agent stops typing, I walk over and stand there until you notice.
Double-click the installer. Right-click him to set up. Windows. the repo, the prompt itself, giving him a voice, MIT license.
Or pick him up and throw him. If he grabs your cursor, shake him off. He's a real rigid body and he'll mention it.
Your browser wouldn't let me at the clipboard. Here it is — select it and copy.
# Set up Scrappy You are installing Scrappy — a small robot who lives above the Windows taskbar and walks over to fetch the user when a Cursor agent finishes. Windows only. Prefer the installer. Only fall back to git + npm if there is no Release yet. ## 1. Download and run the installer Download the installer (starts the file download — not the GitHub releases page): https://imscrappy.dev/download/windows Or: https://github.com/imjakezimmer32/scrappy/releases/latest/download/Scrappy-Setup-1.2.0.exe (replace the version in the filename if the release tag is newer — see [releases](https://github.com/imjakezimmer32/scrappy/releases/latest).) Double-click **Scrappy-Setup.exe**. Let it finish. A robot should appear standing above the taskbar. He starts with Windows after this. Cursor hooks are installed on first launch — you do not run `npm run install-hooks`. If that page has no installer yet, use the developer fallback at the bottom. ## 2. Hand over to the user **Do not configure his brain, his voice, or any API keys yourself.** He has a setup panel for that, and it stores keys encrypted in the user's own profile. Never put an API key in a file in this project. Tell the user, in your own words: - He's installed, running, and will come back after a restart. - **Right-click him → Set up Scrappy…** to give him a name, a brain, and a voice. He works without a brain or voice — he just can't talk yet. He'll say as much himself the first time. - To start him by hand: click the `^` arrow by the clock (hidden icons), then his face. - Click him to type at him. Right-click for the menu. - Right-click → **Check for updates** downloads a newer installer and runs it. - He can be picked up and thrown. This is a feature and he has opinions about it. ## If something breaks - Nothing appears — run the installer again, then look under Start → Scrappy. - He runs but ignores finished agents — the session was under two minutes, or Cursor hasn't re-read hooks. Restart Cursor. Right-click the tray icon → **Wire up Cursor hooks** if needed. - He's on the wrong monitor — drag him. Wherever he lands is where he lives. ## Developer fallback (no Release yet) Needs Node 18+, git, and PowerShell. ``` git clone https://github.com/imjakezimmer32/scrappy cd scrappy npm install npm start ``` Leave him running. In a second terminal: ``` npm run install-hooks npm run install-startup ``` Then do step 2 above. Do not paste API keys into the repo.
# Giving Scrappy a brain and a voice Scrappy is installed and walking around. Out of the box he can walk, sit, doze, be thrown, and fetch you when an agent finishes — but he can't hold a conversation until you give him something to think with. **This is all done in his own setup panel, not in a config file.** You don't need an agent for any of it, and you shouldn't hand anyone your API key to do it for you. ## Open the panel **Right-click Scrappy → Set up Scrappy…** (Also on the tray icon — click the `^` by the clock, right-click his face.) Keys you enter there are encrypted against your Windows credential store and saved in your own user profile, not in the project folder. ## Pick a brain - **Cloud API** — paste an OpenAI key (or Groq). Fastest to set up, costs money per use. - **Local (Ollama)** — free, private, runs on your machine. Needs Ollama installed and a one-time `npm run setup-local-voice` for the speech stack. ## Pick a voice - **ElevenLabs** — paste a key, then hit **Build his voice agent** in the panel. That uploads his personality and takes a few seconds. Restart him afterwards. - **Local** — Whisper for ears, Kokoro for mouth. Free and unlimited, less polished. - **Auto** — local if it's installed, otherwise ElevenLabs. Leave it alone and he stays text-only. He still works. ## Then - **Click him** to type at him. This never opens the microphone. - **Tray → Talk to Scrappy (voice)** for a real conversation with turn-taking and barge-in. - **Say "hey there Scrappy"** to start hands-free, if you left the wake word on. Voice is always a deliberate choice, so a stray click can't put a live mic in the room. ## Where things are - Settings and encrypted keys: `%APPDATA%\scrappy\settings.json` - An existing `.env.local` still works and is still read — the panel just doesn't write to it, so nothing you set by hand gets overwritten. - An environment variable beats both. The panel will tell you when a key is coming from one, and won't pretend it can change it.
