Odysseus Companion (for Obsidian)

Bring your self-hosted Odysseus AI workspace into Obsidian — chat and agent over your vault, voice, agent profiles, memory, research, and a full set of vault tools the agent can drive.

[!IMPORTANT] Some features need a modified Odysseus server. Core chat, vault tools, research, memory, and skills work against stock Odysseus. Agent Profiles and Voice (STT/TTS) rely on server-side additions that aren't in upstream — they live in the maintainer's fork (eskyso/odysseus, branch clean-features). On a stock server, those controls still appear, but they won't do anything until the server side is in place.

(The STT/TTS HTTP endpoints exist in upstream Odysseus; what the fork adds is the provider/model configuration UI plus read-aloud fixes. Without it you'd have to wire up voice providers by hand.)

Features

Chat & agent

• Sidebar chat panel — chat / agent mode, session picker, optional live streaming.
• Toolbar chips for the active Persona, Workspace, and Agent Profile, shown above the input (pickers tucked in the ⌃ menu; click a chip to change).
• Agent mode runs Odysseus's tool-using agent against your vault via the built-in MCP server (below).
• Context-aware session names — plugin chats are named from the opening message (and active note) so they're easy to find in Odysseus's session list.

Agent Profiles (needs the server fork)

Named agent identities = behavior prompt + pinned toolset + memory/skills modes + an optional per-profile model. Ships with an Obsidian Agent profile tuned to operate on the vault. Created/edited in the Odysseus web UI; picked from the chat toolbar chip.

Voice — STT / TTS (needs the server fork)

• Dictate into the chat box, Quick Ask, or directly into a note.
• Read aloud any reply or note (re-listen on demand).
• Hands-free mode — auto-send after you stop talking (pause length configurable) and auto-read the answer, for fully voice-driven asking.

Vault tools (MCP server)

The plugin runs a local MCP server that exposes your vault to Odysseus's agent:

• Read/discovery — search vault, read note, list files/folders, metadata, backlinks, tags, recent/active notes.
• Surgical writes — create/overwrite, append, insert-under-heading, replace, set frontmatter, add/remove tag, create folder, move, daily-note append, open note.
• By-reference transfers — copy_note, copy_section, move_section, split_note: move content between notes server-side without loading it into the model's context (great for partitioning large files cheaply).
• Obsidian commands — list_commands / run_command let the agent trigger any Obsidian command.

Quick actions

• Quick Ask (command palette) — one-shot question, answer inserted at the cursor; web search auto-triggers on keywords (great for voice) or via a manual 🌐 toggle.
• Right-click on a selection — Polish, Rewrite, Simplify, Fix grammar, Expand (web), Shorten, Make a list/heading, Continue writing, Translate, Fact-check (with sources), Run prompt template, Run skill, Save as memory.
• Right-click on a note / commands — Summarize, Polish, Split note by headings, Deep research, Save/append last reply to a note, Import PDF to Odysseus, Index a folder into Odysseus RAG.
• Note actions — read-aloud and dictate buttons on the open note.

Context & attachments

• Context picker — attach notes, folders, web pages, the active note, or recent notes as context for the next message.
• Attach external files — PDF, Word, Excel, images, etc. from anywhere on disk (per-file size cap configurable; the real limit is the model's context window).
• Prompt templates — reusable prompts with variable substitution ({}, {activeNote}, {[[Note]]}, {date}, …).

Setup

1. Run Odysseus somewhere reachable (default http://localhost:7000). For Agent Profiles and Voice, run the eskyso/odysseus fork.
2. Issue an API token in the Odysseus admin UI (starts with ody_…) or log in with your credentials.
3. Build & install the plugin:
   • npm install then npm run build, and copy main.js, manifest.json, and styles.css into your vault's .obsidian/plugins/odysseus/ folder; or
   • run the bundled deploy.bat (builds + copies into the vault; remembers your vault path; deploy.bat --reset to change it).
4. Enable the plugin in Obsidian, then open Settings → Odysseus Companion, set the server URL + API token, and hit Ping.

How it talks to Odysseus

• Most requests use Obsidian's requestUrl (no CORS issues). Streaming uses fetch, which needs Odysseus to allow the Obsidian origin via CORS (app://obsidian.md); if streaming fails it falls back to non-streaming automatically.
• Session ownership — Odysseus treats Bearer-token callers (this plugin) as a separate api user, so the plugin chats in sessions it created. Picking a session created in the web UI as another user may return "No model selected." Use New session to start a fresh one.

Status

Early personal-project quality — expect rough edges. All features were tested with admin access to Odysseus. Odysseus is changing fast, expect things to break, feel free to let me know of any issues, but as stated, this was created for personal use, I can't guarantee support.