Friday Assistant v1

A terminal-native voice assistant powered by Google Gemini AI. Talk naturally, control apps, search the web, and manage files — all from your terminal or browser.

Features

• 🎤 Voice & Text Input — Use speech-to-text in the browser or type commands directly
• 🤖 Gemini AI Chat — Real-time responses via Google's Gemini 2.0 Flash model
• 📱 App Control — Open and close applications on Windows (e.g., Spotify, Calculator, Notepad)
• 🌐 Web Actions — Open websites, search Google, and search YouTube
• 📁 File System — Create directories and write files directly from conversation
• 🎨 3D Visualizer — Animated particle sphere that responds to connection and speech state
• 💻 Terminal-First Aesthetic — Clean, hacker-style UI in both web and CLI modes
• 🧠 Conversation Memory — Remembers context across sessions (last 15 exchanges)

Installation

# Clone the repository
git clone <your-repo-url>
cd friday-assistant

# Install dependencies
npm install

# Build the UI and CLI
npm run build

Usage

CLI Mode (Recommended)

# First run — setup wizard will guide you through API key and voice selection
node dist/cli.js

# Or after linking globally
npm link
friday

The setup wizard will:

1. Prompt for your Google Gemini API key
2. Let you choose a voice personality (Lyra or Puck)
3. Launch the server and open the web interface

Development Mode

# Start the dev server (auto-reloads on changes)
npm run dev

# Or run the UI dev server separately
npm run dev:ui

Production Build

npm run build
npm start

Configuration

Configuration is stored at ~/.friday-config.json:

{
  "apiKey": "AIza...",
  "voice": "Lyra"
}

Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | GOOGLE_API_KEY | Gemini API key | (set by wizard) | | FRIDAY_VOICE | Voice personality (Lyra/Puck) | Lyra | | NODE_ENV | Runtime environment | production | | FRIDAY_PRODUCTION | Production flag | true |

API

Library Usage

import { startFridayVoice, stopFridayVoice } from "friday-assistant";
import { loadConfig, saveConfig } from "friday-assistant";
import { addMemory, getMemory } from "friday-assistant/memory";
import { Server } from "socket.io";

// Start the voice agent with a Socket.IO server
const io = new Server();
await startFridayVoice(io);

// Load saved configuration
const config = loadConfig();
console.log(`Voice: ${config?.voice}`);

// Access conversation memory
const history = getMemory();

Tool Modules

import {
  handleAppAction,
  handleBrowserAction,
  handleNexusFs,
} from "friday-assistant/tools";

Docker

# Build and run with Docker
docker compose up --build

# Or manually
docker build -t friday-assistant .
docker run -p 7788:7788 \
  -e GOOGLE_API_KEY=your_key_here \
  -v ./data:/usr/src/app/data \
  friday-assistant

Note: Microphone input and Windows app control will not work inside Docker containers.

Testing

# Run all tests
npm test

# Watch mode
npm run test:watch

The test suite covers:

• Memory module (CRUD operations, limits, serialization)
• Port picker (availability detection)
• Tool execution (file system operations)
• Type definitions

Project Structure

friday-assistant/
├── bin/
│   └── friday.ts              # CLI entry point
├── src/
│   ├── index.ts                # Library entry point
│   ├── types.ts                # Shared type definitions
│   ├── cli/
│   │   ├── banner.ts           # ASCII art banner
│   │   ├── setup.ts            # First-run config wizard
│   │   └── logger.ts           # Terminal output utilities
│   ├── server/
│   │   ├── main.ts             # Express + Socket.IO server
│   │   ├── agent/
│   │   │   └── friday-voice.ts # Gemini AI voice agent
│   │   ├── tools/
│   │   │   ├── index.ts        # Barrel exports
│   │   │   ├── app-agent.ts    # App control
│   │   │   ├── browser-agent.ts# Browser/web actions
│   │   │   └── nexus-agent.ts  # File system operations
│   │   ├── utils/
│   │   │   ├── memory.ts       # Conversation memory
│   │   │   ├── port-picker.ts  # Port availability
│   │   │   └── config.ts       # Server config
│   │   └── constants/
│   │       └── StreamConfig.ts # Stream config
│   ├── client/                 # React/Vite frontend
│   │   ├── App.tsx
│   │   ├── main.tsx
│   │   ├── index.css
│   │   ├── views/Friday.tsx
│   │   └── utils/VisualCore.tsx
│   └── config/
│       └── dot-env.ts
├── test/
│   ├── setup.test.ts
│   ├── memory.test.ts
│   ├── port-picker.test.ts
│   └── tools.test.ts
├── build.js                    # CLI bundle script
├── vite.config.ts
├── Dockerfile
├── docker-compose.yml
├── tsconfig.json
└── package.json

Commands

| Command | Description | |---------|-------------| | npm run dev | Start dev server with auto-reload | | npm run dev:ui | Start Vite UI dev server | | npm start | Start production server | | npm run build:ui | Build React UI bundle | | npm run build:cli | Bundle CLI to dist/cli.js | | npm run build | Build both UI and CLI | | npm run release | Full build and pack | | npm test | Run test suite | | npm run typecheck | TypeScript type checking |

Tech Stack

• Runtime: Node.js 24+
• Language: TypeScript
• AI: Google Gemini 2.0 Flash (@google/genai)
• Web Server: Express + Socket.IO
• Frontend: React 19, Vite, Tailwind CSS 4
• 3D Graphics: Three.js, React Three Fiber
• CLI: Inquirer, Chalk
• Build: esbuild, Vite

License

MIT