Sheila

Local-first research copilot with voice — fork of Roxanne

Talk to your Zotero library and Obsidian vaults via voice or text using Anthropic Claude, OpenAI GPT, or local Ollama models. Sheila indexes and embeds your entire research database, then uses agentic MCP to search, read, and update your knowledge base—all offline and private.

Features at a Glance

• Multi-model inference — Claude (Bedrock), GPT-4, Ollama (local) via unified interface
• Voice input/output — STT (Unmute) + TTS (AWS Bedrock) for hands-free research
• Zotero integration — Search your library, pull annotations, cite papers inline via MCP
• Obsidian integration — Query your vault, link notes, surface connections via MCP
• Offline-first — Vector embeddings indexed locally (FastEmbed), no cloud dependency for search
• Streaming responses — Server-Sent Events for real-time generation
• Conversation persistence — Full chat history with search and export
• Cross-platform — macOS, Windows, Linux (Electron + Python backend)

Screenshots

Screenshots coming soon. The app includes:

• Chat interface with model selector, streaming markdown rendering, and citation links
• Voice mode with real-time STT indicator and TTS playback controls
• Research panel showing Zotero results, Obsidian note connections, and web search
• Settings for model configuration, voice engine selection, and index management

How It Differs from Roxanne

Sheila is forked from Roxanne with significant additions:

Area	Roxanne	Sheila
LLM support	OpenAI only	Claude (Bedrock) + GPT-4 + Ollama with runtime switching
Voice	None	Full STT/TTS pipeline (Unmute + AWS Bedrock TTS)
Tool system	Hardcoded integrations	MCP-based agentic orchestration (Zotero, Obsidian)
Search	Cloud-dependent	FastEmbed local vector indexing, offline-first
Architecture	Monolithic backend	Modular router-based FastAPI with separated concerns
Streaming	Polling	SSE-based real-time responses

Fork Improvements

This fork adds substantial enhancements to the upstream Roxanne research copilot:

Phase 1: Component Architecture Refactor

• Refactored App.tsx into focused, reusable component modules
• Improved code organization and maintainability
• Enhanced separation of concerns across the React UI layer

Phase 2: Voice Integration

• Extracted voice and text-to-speech logic into a useVoiceMode custom hook
• Integrated Unmute library for robust audio input
• Added AWS Bedrock TTS for high-quality voice output
• Simplified voice feature management and testing

Phase 3: Multi-Model Support

• Implemented dynamic model dropdown from OpenAI-compatible endpoints
• Added support for Claude Bedrock, GPT-4, and local Ollama models
• Model selection persisted across sessions
• Runtime model switching without app restart

Phase 4: Backend Architecture Cleanup

• Split monolithic main.py into focused router modules
• Separated concerns: orchestration, embedding, search, Zotero MCP, Obsidian MCP
• Improved testability and maintainability of backend services
• Cleaner error handling and logging across routes

Phase 5: Agentic Features

• Enhanced MCP orchestration for multi-step research workflows
• Improved Zotero and Obsidian integration with agentic capabilities
• Better handling of complex document retrieval and processing

Phase 6: Debug & Stability

• Fixed debug logging across frontend and backend
• Corrected transcription callback behavior
• Improved error messages and stack traces for troubleshooting

Architecture

┌─────────────────────────────────────────────────────────────┐
│                     Electron Shell                          │
│                    (Main Process)                           │
└────────────────────────┬────────────────────────────────────┘
                         │
┌────────────────────────▼────────────────────────────────────┐
│                    React UI Layer                           │
│  ┌──────────────────┬──────────────────┬─────────────────┐  │
│  │  Voice Input     │  Text Interface  │  Model Selector │  │
│  │  (useVoiceMode)  │  (Chat UI)       │  (Dropdown)     │  │
│  └──────────────────┴──────────────────┴─────────────────┘  │
└────────────────────────┬────────────────────────────────────┘
                         │ HTTP
┌────────────────────────▼────────────────────────────────────┐
│              FastAPI Backend (Python)                       │
│  ┌────────────┬──────────────┬─────────────┬──────────────┐ │
│  │ Orchestr.  │ Embeddings   │ Zotero MCP  │ Obsidian MCP │ │
│  │ Router     │ Router       │ Router      │ Router       │ │
│  └────────────┴──────────────┴─────────────┴──────────────┘ │
│                         │                                    │
│  ┌──────────────────────▼──────────────────────────────────┐ │
│  │  FastEmbed (Vector Database)                           │ │
│  │  Local Index of Zotero + Obsidian Content              │ │
│  └──────────────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────────┘
                         │
        ┌────────────────┼────────────────┐
        │                │                │
   ┌────▼────┐    ┌─────▼──────┐  ┌──────▼──────┐
   │ Anthropic│    │  OpenAI    │  │ Ollama      │
   │ Bedrock  │    │  (GPT-4)   │  │ (Local)     │
   └──────────┘    └────────────┘  └─────────────┘

Install

The install scripts pull the latest published Sheila release for your platform and install it for you.

macOS or Linux

curl -fsSL https://raw.githubusercontent.com/jlynshue/Sheila/main/scripts/install.sh | bash

Windows PowerShell

irm https://raw.githubusercontent.com/jlynshue/Sheila/main/scripts/install-windows.ps1 | iex

Optional Install Flags

Install a specific version:

SHEILA_VERSION=v0.2.0 curl -fsSL https://raw.githubusercontent.com/jlynshue/Sheila/main/scripts/install.sh | bash

Install without auto-opening the app:

SHEILA_NO_OPEN=1 curl -fsSL https://raw.githubusercontent.com/jlynshue/Sheila/main/scripts/install.sh | bash

After install, launch from your terminal:

sheila

On macOS and Linux, the launcher is installed into ~/.local/bin. Add it to your PATH if needed.

Develop Locally

Prerequisites

• Python 3.10+
• Node.js 20+
• Optional: Ollama for local models

Clone the Repo

git clone https://github.com/jlynshue/Sheila.git
cd Sheila

Quick Setup

npm run setup

This creates apps/backend/.venv, installs the editable backend with test dependencies, and installs desktop dependencies.

Manual Setup

Backend:

python3 -m venv apps/backend/.venv
source apps/backend/.venv/bin/activate
pip install -e "./apps/backend[test]"

Windows PowerShell:

py -3 -m venv apps/backend/.venv
.\apps\backend\.venv\Scripts\Activate.ps1
pip install -e ".\apps\backend[test]"

Frontend:

npm install

Run in Development

Full app:

npm run open:desktop

Separate processes (easier debugging):

npm run debug:backend       # FastAPI backend with reload
npm run debug:frontend      # React dev server
npm run debug:desktop       # Electron shell (needs backend running)
npm run debug:full          # Backend + Electron together

Build the App

Ensure backend dependencies include build tools:

source apps/backend/.venv/bin/activate
pip install -e "./apps/backend[build]"

Build unpacked release:

SHEILA_PYTHON_BIN="$PWD/apps/backend/.venv/bin/python3" npm run pack:desktop

Build installer for your platform:

SHEILA_PYTHON_BIN="$PWD/apps/backend/.venv/bin/python3" npm run dist:desktop

Outputs go to apps/desktop/release.

Run Tests

Backend tests:

source apps/backend/.venv/bin/activate
python -m pytest apps/backend/tests -m "not slow and not integration"

Desktop type-check:

npm --workspace apps/desktop run lint

Tech Stack

Layer	Technology	Purpose
Desktop	Electron	Cross-platform app shell
UI	React + TypeScript	Component-based interface with type safety
Backend	FastAPI (Python)	REST API and orchestration
Embeddings	FastEmbed	Fast, local vector embeddings
Vector DB	Built-in	Indexed embeddings of research library
LLM	Claude (Bedrock) / GPT-4 / Ollama	Multi-model inference
Voice	Unmute + AWS Bedrock TTS	Audio input and speech synthesis
Research Integration	MCP (Model Context Protocol)	Agentic Zotero and Obsidian access
Package Manager	npm (frontend) + pip (backend)	Dependency management

Project Layout

apps/
  backend/            FastAPI backend, indexing, orchestration, routers
  desktop/            Electron shell and React renderer
scripts/
  build-backend-binary.mjs
  install.sh
  install-windows.ps1
docs/assets/
  banner.png

Credits

Forked from Roxanne by Tyler Illman

This fork extends Roxanne with voice integration, multi-model support, and architectural improvements for production use.

Author

Jonathan Lyn-Shue — Fractional CIO/CTO | Data & AI Executive

---

License

MIT — See LICENSE file for details.