How to install and use Odysseus
Odysseus puts an iPhone-style "dynamic island" at the top of your Windows screen. It shows what's going on: Claude Code sessions, music, focus timers, your day and messages. It opens into cards when you need more.
1. Installing and removing§
Install: run OdysseusSetup-0.1.0.exe, the setup wizard you downloaded. If you don't have it yet, download it here (3.4 MB).
- It needs no admin rights and installs for your Windows account only.
- The wizard asks whether to start Odysseus at sign-in (on by default) and whether to add a desktop shortcut.
- Windows may show "Windows protected your PC" because the installer isn't signed yet. Click More info, then Run anyway.
Find it again: it's in the Start menu as Odysseus, or press Win+R, type atoll and press Enter. It also lives in the system tray.
Remove it: Settings › Apps › Odysseus › Uninstall. Your settings, notes and clipboard history stay, in case you reinstall.
2. The island§
At rest the island is a thin line under the top of the screen. Its colours tell you what's happening, and several things at once split it into segments.
| Colour | Means |
|---|---|
| Claude orange | A Claude Code session is working (amber near the 5-hour limit, red past 95%) |
| Green | A Claude turn just finished, or a focus timer ended |
| Cyan | A focus timer is running |
| Lavender | An important Teams update you haven't opened |
| Blue | The quick chat is answering, or has an answer you haven't read |
| Album colour | Music is playing; the line pulses with the beat |
| Red | An agent is waiting for your approval |
| Grey | Nothing is going on |
Using it
- Hover the island to open Home, a glance at everything.
- Click a coloured segment to open that activity directly.
- Bubbles around the open card are the other pages. Click one, or scroll to move between pages.
- Click anywhere else to close it.
Moving it
Press and drag the island anywhere. It snaps to where you drop it:
- An edge: it rests as a line along that edge, and cards open away from the edge.
- A corner: it becomes a spinning ring. Clicking it opens a small dial with the bubbles around it. Scroll over the dial to turn it like a wheel, and the bubble that lands on the dot opens. The ring's centre shows the most important thing going on, and you choose what that is in Settings.
- Anywhere else: it floats as a small capsule.
It remembers where you left it. To bring it back, use Move island to top in the tray menu.
3. Pages§
| Page | What's on it |
|---|---|
| Home | Today's date and Claude plan usage, then one line each for: Claude session, music (with play/pause), focus timer, what's next today, newest Teams update, morning report |
| Claude | 5-hour and weekly usage rings, when you'll run out at this pace, today's spend, a 3-month activity calendar, streaks, your sessions (click one to bring its window forward) |
| Today | Today's homework blocks and your own daily task list. Focus starts a timer for a block; Done marks it finished (with 4 seconds to undo) |
| Music | Cover, progress and controls, a 3D spectrum in the album's colour, and synced lyrics |
| Clipboard | History of what you copy, with pins and search. Items password managers mark as private are never saved |
| Mood | AI-made music playlists (section 5) |
| Settings (gear) | What the corner ring's centre shows, plus a "Sound, motion & more" card with a slider for every number |
4. Shortcuts§
| Keys | Does |
|---|---|
| Win+Space or Alt+C | Open or close the quick chat |
| Alt+V | Open clipboard history |
| Win+Alt+→ / Win+Alt+← | Next or previous song, in a Mood playlist or any music player |
| Tab (in chat) | Paste your latest clipboard item |
| Esc | Close the chat or picker |
5. Mood playlists§
Open the Mood bubble (the small record).
- Type how you feel ("rainy Sunday, a little nostalgic", "pre-workout, get me hyped") and press Enter.
- For now makes a playlist for the moment with nothing typed.
- Surprise me goes by the music you've liked.
- Set Songs (10, 15, 20 or 30) and Energy (Any, or Calm to Intense).
- An AI picks real songs, finds them on QQ Music and plays them there, one after another. QQ Music must be installed and running.
The playlist card
- Each playlist gets its own card: a vinyl record, cassette, gig ticket, boarding pass, receipt, magazine cover, film strip, radio dial, postcard, setlist, mixing console or polaroid.
- Each card shows the song playing inside the object, such as the tone arm on its groove or the plane along its route.
Buttons
Play, New songs (same mood, different songs), Copy (the list as text), and ▶ on any song to play from there.
Teaching it your taste
- Give a playlist 👍 or 👎, and ♥ songs you love. New playlists learn from these marks.
- Routine switch: when on, the time of day and your work hours guide For now. Set your work hours in
routineand your standing taste inmood_preferencein config.json (section 9).
6. Quick chat§
Press Win+Space. It's an AI chat that:
- searches the web when a question needs current information, and cites the pages it used
- shows formatted answers, including tables, code and maths
- keeps answering while closed: the island shows a blue segment, then a banner when the answer is ready
Type /model (or click the model name) to switch AI models. Keep typing to filter, and press Enter to choose.
Needs: an OpenCode Go API key, and a Serper key for web search (section 8).
7. Other features§
- Focus timer: start one from a Today block. It counts down on the island and turns green when done.
- Claude Code sessions:
- Watching your sessions needs the Odysseus Claude Code plugin, which the installer doesn't include.
- With it, each working session gets a segment; click it for its tasks, tools and subagents.
- A session can also pop out as its own floating bubble. Close glides it back into the island.
- Corner-ring rules (Settings): pick a preset (Balanced, Coding, Deep focus, Music, Quiet), or describe what you want in plain words ("music first, warn me about the limit from 75%"). You can also drag rules to reorder them.
- Sound, motion & more (Settings): sliders for card sound volume, animation speed, hover delay, focus length, clipboard size, and switches for lyrics, beat visuals and more. Each has a reset.
Need the Sisyphus companion service (optional)
- Teams updates: important ones pop up; minor ones show briefly.
- Morning report: a daily summary of homework and tests.
- Review materials: search your class files for a test.
- Study files: click a file and it downloads straight to your Downloads folder.
- Agent approvals: when an AI agent wants to message someone for you, a red card appears. Review opens the panel to approve or reject. A WeChat message request warns you if WeChat on the Mac is logged out.
- Urgent alerts: emergencies in Teams show as a red card that stays until you dismiss it.
8. Setting up optional services§
Keys are stored in Windows Credential Manager: Control Panel › Credential Manager › Windows Credentials › Add a generic credential.
| Feature | Credential name | What to put |
|---|---|---|
| Quick chat | Atoll/opencode-go | Your OpenCode Go API key |
| Web search in chat | Atoll/serper | Your Serper.dev API key |
| Mood playlists | uses the quick chat key | |
| Sisyphus (Teams, report, approvals) | Atoll/sisyphus-digest | Sisyphus's access token, plus digest_url in config.json |
| Homework planner (Aethalides) | Atoll/time-manager | Aethalides's API key, plus planner_url in config.json |
These need nothing extra: the island, Home, music, lyrics, clipboard, focus timer and Settings.
9. Settings file§
Everything is saved in %APPDATA%\Atoll\config.json. Open it from the tray menu (settings file). Useful entries:
| Setting | What it does |
|---|---|
hotkey_chat, hotkey_clipboard, hotkey_next, hotkey_prev | Change shortcuts |
mood_preference | Your standing music taste, e.g. "English songs and instrumentals, about half instrumental" |
routine | Your work hours per day, e.g. "mon": ["19:00-22:00"] |
focus_minutes | Default focus length |
card_sounds, card_volume | Card sounds on or off, and how loud |
lyrics, beat, art_lookup | Lyrics, beat visuals, album art lookup |
digest_url, planner_url | Addresses of Sisyphus and Aethalides (empty means off) |
Most of these are also on the Settings page. Restart Odysseus after editing the file by hand.
10. Troubleshooting§
- The island disappeared: use Move island to top in the tray menu, or start Odysseus from the Start menu.
- Song keys don't work: another app has Win+Alt+arrows. Change
hotkey_nextandhotkey_previn config.json. - Mood playlists don't play: make sure QQ Music is open and signed in.
- The quick chat says there's no key: add
Atoll/opencode-goin Credential Manager (section 8). - Logs:
%LOCALAPPDATA%\Atoll\atoll.log.