A hybrid AI assistant with two distinct operating modes:
- Desktop Mode: Electron app with full native file system access
- Remote Mode: Docker-contained web app with controlled workspace access
- Multi-Provider LLM Support: Claude API and OpenRouter integration
- Tool Execution: File operations, bash commands, search, and more
- Vector Memory: ChromaDB integration for context persistence
- Real-time Streaming: Live response streaming via WebSocket
- Voice Interface: Speech-to-text and text-to-speech support
- Browser Automation: Web scraping and automation via Playwright
| Category | Technology |
|---|---|
| Runtime | Bun |
| Desktop | Electron + Svelte 5 |
| Web | SvelteKit |
| API | Fastify + WebSocket |
| Language | TypeScript (strict) |
| Build | Turborepo + pnpm |
| Testing | Vitest |
| Container | Docker + Docker Compose |
| Package | Description |
|---|---|
@shell/core |
Shared business logic (LLM, memory, tools, agent) |
@shell/ui |
Shared Svelte components and stores |
@shell/electron |
Desktop app (native, full file access) |
@shell/web |
Web app (SvelteKit, runs in Docker) |
@shell/api |
API server (Docker, controlled access) |
| Mode | Access Level | Description |
|---|---|---|
| Desktop | Full System | Can access any file on your computer |
| Remote | Workspace Only | Can only access mounted /workspace volume |
# Clone the repository
git clone <repository-url>
cd shell-monorepo
# Install dependencies
pnpm install
# Configure environment
cp .env.example .env
# Edit .env with your API keys
# Build all packages
bun run build
# Run tests
bun run test
# Start desktop app (development)
cd packages/@shell/electron && bun run devCreate a .env file from .env.example:
# Required - Choose at least one
ANTHROPIC_API_KEY=sk-ant-... # Claude API
OPENROUTER_API_KEY=sk-or-... # OpenRouter
# Optional
OPENAI_API_KEY=sk-... # For embeddings
ELEVENLABS_API_KEY=... # For TTS
CHROMADB_URL=http://localhost:8000# Development mode (all packages)
bun run dev
# Build all packages
bun run build
# Run tests
bun run test
# Type checking
bun run typecheck
# Clean build artifacts
bun run clean# Desktop app
cd packages/@shell/electron
bun run dev # Development
bun run package # Build distributables
# API server
cd packages/@shell/api
bun run dev # Development
bun run start # Production
# Web app
cd packages/@shell/web
bun run dev # Development
bun run build # Production build# Build and start all services
docker-compose up -d --build
# View logs
docker-compose logs -f
# Stop services
docker-compose downServices:
- Web UI: http://localhost:3000
- API: http://localhost:3001
- ChromaDB: http://localhost:8000
shell-monorepo/
├── packages/
│ └── @shell/
│ ├── core/ # Shared business logic
│ ├── ui/ # Shared Svelte components
│ ├── electron/ # Desktop app
│ ├── web/ # Web app
│ └── api/ # API server
├── docker/ # Docker configuration
├── docs/ # Documentation
├── .github/ # CI/CD workflows
└── docker-compose.yml # Remote deployment
# Run all tests
bun run test
# Run specific package tests
cd packages/@shell/core && bun run test
# Watch mode
cd packages/@shell/core && bun run test:watch- Architecture - System design and data flow
- Setup Guide - Installation and configuration
- API Reference - REST and WebSocket APIs
- Deployment - Docker and production deployment
- File Access - Security model for file operations
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
MIT