LifeOS - AI-Powered Life Management System

Your AI-powered personal assistant for tasks, calendar, and projects

Demo • Features • Quick Start • Documentation • Architecture

Overview

LifeOS is a complete AI-powered life management system built for the Amazon Alexa+ Hackathon. It demonstrates the full potential of the Model Context Protocol (MCP) for autonomous agent orchestration.

Key Highlights:

• 🤖 12 MCP Tools - Custom server for task, calendar, and project management

• 🔄 Real-Time Agent Streaming - Watch AI think and act in real-time via SSE

• 🎯 Smart Planning - Multi-provider AI (OpenAI/Anthropic) with rule-based fallback

• 🗣️ Voice-Ready - Alexa simulator demonstrates conversational interface

• 🏗️ Production-Ready - TypeScript monorepo with PostgreSQL, tested and documented

Related MCP server: Todoist MCP Server

Demo

Live Demo User: Alex Chen

LifeOS includes a fully seeded demo persona to showcase realistic workflows:

Profile:

• Product Manager at a tech startup

• Managing 3 active projects (product launch, hiring, Q1 planning)

• 8 pending tasks across different priorities

• Busy calendar with 8 events this week

Try These Commands

Open the Alexa simulator at http://localhost:3000/alexa and try:

"What should I focus on today?"
→ Agent analyzes tasks + calendar and provides prioritized recommendations

"Schedule a design review meeting for next Tuesday at 2pm"
→ Agent finds availability, books meeting, and confirms

"Create a high priority task to finalize pricing strategy, due Friday"
→ Agent creates task, links to relevant project, and confirms

"Help me prepare for the product launch next week"
→ Agent generates multi-step action plan with concrete next steps

Visual Tour

Dashboard: Integrated view of tasks, calendar, projects, and live agent activity

Alexa Simulator: Voice-first conversational interface with real-time streaming

Agent Activity Panel: Transparent view into AI decision-making and tool execution

Features

🎯 Intelligent Task Management

• Natural Language Input - "Create a task to review design docs by Friday"

• Smart Prioritization - AI recommends what to work on based on deadlines and calendar

• Project Linking - Automatic categorization into relevant projects

• Status Tracking - Todo, In Progress, Completed, Cancelled

📅 Contextual Calendar

• Time-Block Visualization - See available gaps for task scheduling

• Smart Scheduling - "Find time for a 1-hour meeting next week"

• Conflict Detection - Agent avoids double-booking

• Event Management - Create, move, and delete events via natural language

🤖 Autonomous Agent

• Multi-Tool Orchestration - Chains multiple MCP tools to achieve goals

• Transparent Decision-Making - Real-time streaming of thoughts and actions

• Error Recovery - Handles failures gracefully with retry logic

• Context Awareness - Remembers conversation history and learns patterns

🗣️ Voice-First Design

• Alexa Simulator - Test conversational flows before Alexa integration

• Natural Responses - Conversational language optimized for voice

• Multi-Turn Dialogs - Agent maintains context across exchanges

• Proactive Suggestions - "You have 3 tasks due tomorrow. Want me to reschedule?"

🔧 Developer Experience

• TypeScript Monorepo - Shared types, schemas, and utilities via pnpm workspaces

• Type-Safe API - Zod validation from database to frontend

• Hot Reload - Instant updates during development

• Comprehensive Testing - 65+ unit tests, integration tests ready

Quick Start

Prerequisites

Ensure you have these installed:

• Node.js 18+ (download)

• Docker Desktop (download)

• pnpm 8+ (install: npm install -g pnpm)

Installation (5 minutes)

1. Clone and Install Dependencies

cd "c:\Users\admin\Desktop\Amazon Developer"
pnpm install

2. Start PostgreSQL Database

docker compose up -d

Verify database is running:

docker compose ps
# Should show lifeos-db as "running"

3. Run Database Migrations

pnpm --filter @lifeos/database db:migrate

This creates all tables (User, Project, Task, CalendarEvent, AgentSession, ActionLog).

4. Seed Demo Data

pnpm --filter @lifeos/database db:seed

This creates Alex Chen demo user with 3 projects, 8 tasks, and 8 calendar events.

5. Start Development Servers

Open two terminal windows:

# Terminal 1: Start MCP Server (port 3001)
pnpm --filter @lifeos/mcp-server dev

# Terminal 2: Start Web App (port 3000)
pnpm --filter @lifeos/web dev

6. Access the Application

• Landing Page: http://localhost:3000

• Dashboard: http://localhost:3000/dashboard

• Alexa Simulator: http://localhost:3000/alexa

Verify Installation

Check that both servers are healthy:

# MCP Server health
curl http://localhost:3001/health
# Expected: {"status":"ok","toolsRegistered":12}

# Web App health
curl http://localhost:3000/api/health
# Expected: {"status":"ok"}

Configuration

Environment Variables

The project uses .env.local for configuration. Default values are provided for quick start, but you can customize:

# Database
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/lifeos

# MCP Server
MCP_SECRET=dev-secret-replace-with-32-char-minimum-for-production-use
MCP_SERVER_URL=http://localhost:3001

# AI Provider (optional - uses rule-based fallback if not set)
AI_PROVIDER=openai              # or "anthropic"
AI_MODEL=gpt-4o                 # or "claude-3-5-sonnet-20241022"
AI_API_KEY=                     # Add your API key here for LLM-powered planning

# Demo Mode
DEMO_MODE=true                  # Set to false for production
DEMO_USER_ID=00000000-0000-0000-0000-000000000001

# NextAuth (for production authentication)
NEXTAUTH_URL=http://localhost:3000
NEXTAUTH_SECRET=dev-nextauth-secret-change-for-production

Adding AI Provider

For better agent responses, add your AI provider API key:

OpenAI:

AI_PROVIDER=openai
AI_MODEL=gpt-4o
AI_API_KEY=sk-proj-...

Anthropic:

AI_PROVIDER=anthropic
AI_MODEL=claude-3-5-sonnet-20241022
AI_API_KEY=sk-ant-...

Then restart both servers to apply changes.

Architecture

LifeOS is built as a TypeScript monorepo using pnpm workspaces:

lifeos/
├── packages/
│   ├── shared/         # Shared schemas, types, error classes
│   ├── database/       # Prisma schema, migrations, seed
│   ├── ai/             # AI provider abstraction, agent orchestrator
│   └── ui/             # Design tokens and shared UI utilities
│
├── apps/
│   ├── mcp-server/     # Express MCP server with 12 tools
│   └── web/            # Next.js 14 web application
│
├── docs/               # Documentation and compliance
├── .env.local          # Environment configuration
├── docker-compose.yml  # PostgreSQL container
└── pnpm-workspace.yaml # Monorepo configuration

Technology Stack

Backend:

• MCP Server: Express.js with Streamable HTTP transport

• Database: PostgreSQL 16 with Prisma ORM

• AI: OpenAI GPT-4o / Anthropic Claude with abstraction layer

• Validation: Zod schemas for type-safe APIs

• Logging: Winston with structured JSON logs

Frontend:

• Framework: Next.js 14 with App Router

• UI: React 18, TailwindCSS 3

• State: Zustand with persistence

• Real-Time: Server-Sent Events (SSE) for agent streaming

• Icons: Lucide React

Development:

• Language: TypeScript 5.3

• Package Manager: pnpm 8

• Testing: Vitest (unit), Playwright (e2e, planned)

• Linting: ESLint + Prettier

• Version Control: Git

Data Flow

User Input (Natural Language)
    ↓
Next.js Web App (/alexa or /dashboard)
    ↓
API Route (/api/mcp) with SSE streaming
    ↓
MCP Server (Express on port 3001)
    ↓
Agent Orchestrator (AI planning + tool selection)
    ↓
MCP Tools (12 tools for CRUD operations)
    ↓
PostgreSQL Database (Prisma ORM)
    ↓
Response (Natural Language + Structured Data)
    ↓
Real-Time UI Update (SSE stream + Zustand state)

MCP Tools

The system includes 12 production-ready MCP tools:

Documentation

Comprehensive documentation is available in the docs/ directory:

• HACKATHON_COMPLIANCE.md - Full compliance proof for Amazon Alexa+ Hackathon

• ARCHITECTURE.md - Detailed system design and technical decisions

• API_REFERENCE.md - Complete API documentation for MCP tools and web endpoints

• DEPLOYMENT.md - Production deployment guide (AWS, Vercel, Docker)

• DEVELOPMENT.md - Development guidelines and contribution guide

• ALEXA_INTEGRATION.md - Step-by-step guide to integrate with Alexa

Development

Project Structure

packages/shared/
├── src/
│   ├── schemas/      # Zod validation schemas
│   ├── types/        # TypeScript type definitions
│   └── errors/       # Custom error classes
└── __tests__/        # Schema validation tests

packages/database/
├── prisma/
│   ├── schema.prisma # Database schema
│   ├── migrations/   # SQL migrations
│   └── seed.ts       # Demo data seed script
└── src/
    └── client.ts     # Prisma client singleton

packages/ai/
├── src/
│   ├── providers/    # OpenAI and Anthropic adapters
│   ├── orchestrator/ # Agent loop and planning
│   └── mcp/          # MCP client wrapper
└── __tests__/        # Orchestrator tests

apps/mcp-server/
├── src/
│   ├── tools/        # 12 MCP tool implementations
│   ├── middleware/   # Auth, logging, error handling
│   └── server.ts     # Express app and MCP endpoint
└── __tests__/        # Server integration tests (planned)

apps/web/
├── src/
│   ├── app/          # Next.js App Router pages
│   ├── components/   # React components
│   ├── hooks/        # Custom React hooks
│   ├── stores/       # Zustand state stores
│   └── lib/          # Utilities and helpers
└── e2e/              # Playwright tests (planned)

Common Commands

# Install dependencies
pnpm install

# Type checking
pnpm typecheck

# Linting
pnpm lint
pnpm lint:fix

# Testing
pnpm test                                   # All tests
pnpm --filter @lifeos/shared test          # Schema tests only
pnpm --filter @lifeos/ai test              # Orchestrator tests only

# Database operations
pnpm --filter @lifeos/database db:migrate  # Run migrations
pnpm --filter @lifeos/database db:seed     # Seed demo data
pnpm --filter @lifeos/database db:reset    # Reset database (WARNING: deletes data)
pnpm --filter @lifeos/database db:studio   # Open Prisma Studio UI

# Development servers
pnpm --filter @lifeos/mcp-server dev       # Start MCP server
pnpm --filter @lifeos/web dev              # Start web app

# Production build
pnpm build                                  # Build all packages and apps

Adding a New MCP Tool

1. Create tool file in apps/mcp-server/src/tools/:

// apps/mcp-server/src/tools/myNewTool.ts
import { z } from 'zod';
import { prisma } from '@lifeos/database';

export const myNewTool = {
  name: 'my_new_tool',
  description: 'Description of what the tool does',
  parameters: z.object({
    userId: z.string().uuid(),
    // Add your parameters here
  }),
  handler: async (params: z.infer<typeof myNewTool.parameters>) => {
    try {
      // Your implementation here
      const result = await prisma.someModel.findMany({
        where: { userId: params.userId }
      });
      
      return {
        success: true,
        data: result
      };
    } catch (error) {
      return {
        success: false,
        error: {
          code: 'MY_TOOL_ERROR',
          message: error.message
        }
      };
    }
  }
};

2. Register tool in apps/mcp-server/src/tools/index.ts:

import { myNewTool } from './myNewTool';

export const tools: MCPTool[] = [
  // ... existing tools
  myNewTool
];

3. Add tests in apps/mcp-server/__tests__/tools/myNewTool.test.ts

4. Restart MCP server and verify:

curl http://localhost:3001/health
# Should show toolsRegistered: 13

Database Schema Changes

1. Edit packages/database/prisma/schema.prisma

2. Create migration: pnpm --filter @lifeos/database db:migrate --name my_change

3. Update seed script if needed: packages/database/prisma/seed.ts

4. Regenerate Prisma Client: pnpm --filter @lifeos/database build

Testing

Current Test Coverage

• Schema Validation: 51 tests (100% coverage of Zod schemas)

• Agent Orchestrator: 14 tests (core planning and execution logic)

• Total: 65 unit tests

Run tests:

pnpm test

Planned Tests

Integration Tests:

• MCP server API endpoints

• Database operations with test database

• Error handling and edge cases

End-to-End Tests (Playwright):

• User flows: landing → dashboard → create task

• Natural language agent interactions

• Calendar event creation and rescheduling

• Demo reset functionality

Deployment

Quick Deploy (Vercel + Railway)

1. Deploy Web App to Vercel:

# Install Vercel CLI
npm install -g vercel

# Deploy
cd apps/web
vercel --prod

2. Deploy Database to Railway:

1. Visit railway.app

2. Create new project → PostgreSQL

3. Copy DATABASE_URL from Railway dashboard

4. Add to Vercel environment variables

3. Deploy MCP Server to Railway:

# Create railway.json in apps/mcp-server/
{
  "build": {
    "builder": "NIXPACKS"
  },
  "deploy": {
    "startCommand": "node dist/index.js",
    "restartPolicyType": "ON_FAILURE"
  }
}

# Deploy via Railway CLI or GitHub integration

4. Configure Environment Variables:

• Add all .env.local variables to Vercel and Railway

• Update MCP_SERVER_URL in Vercel to point to Railway MCP server

• Set DEMO_MODE=false for production

Full Production Deployment

See docs/DEPLOYMENT.md for comprehensive guides:

• AWS ECS/Fargate deployment

• Docker multi-stage builds

• CI/CD with GitHub Actions

• Database backup strategies

• Monitoring and observability setup

Troubleshooting

Database Connection Issues

Problem: Error: P1001: Can't reach database server

Solution:

# Check if PostgreSQL container is running
docker compose ps

# If not running, start it
docker compose up -d

# Verify connection
docker compose exec db psql -U postgres -d lifeos -c "SELECT 1;"

MCP Server Not Starting

Problem: Error: Cannot find module '@lifeos/database'

Solution:

# Rebuild all packages
pnpm install --force
pnpm build

Web App Shows "Failed to Fetch"

Problem: Agent queries fail with network error

Solution:

1. Verify MCP server is running: curl http://localhost:3001/health

2. Check MCP_SERVER_URL in .env.local matches server address

3. Ensure MCP_SECRET matches between web app and MCP server

4. Check browser console for detailed error messages

Agent Responses Are Generic

Problem: Agent gives basic responses instead of intelligent suggestions

Solution: You're in demo mode using rule-based planning. For AI-powered responses:

1. Get an API key from OpenAI or Anthropic

2. Add to .env.local:

   AI_PROVIDER=openai
   AI_API_KEY=sk-proj-...

3. Restart both servers

4. Test with same queries - responses should be more contextual

Port Already in Use

Problem: Error: listen EADDRINUSE: address already in use :::3000

Solution:

# Find process using port 3000
netstat -ano | findstr :3000

# Kill the process (replace PID with actual process ID)
taskkill /PID <PID> /F

# Or use a different port
PORT=3002 pnpm --filter @lifeos/web dev

Contributing

LifeOS was built for the Amazon Alexa+ Hackathon as a solo project, but contributions are welcome!

Development Setup

1. Fork the repository

2. Clone your fork: git clone https://github.com/yourusername/lifeos.git

3. Create a branch: git checkout -b feature/my-feature

4. Make changes and test thoroughly

5. Run linting and tests: pnpm lint && pnpm test

6. Commit with clear messages: git commit -m "feat: add new feature"

7. Push and create PR: git push origin feature/my-feature

Code Style

• Use TypeScript for all new code

• Follow existing patterns and conventions

• Add Zod schemas for new data types

• Write tests for new features

• Update documentation as needed

Commit Convention

Follow Conventional Commits:

• feat: - New feature

• fix: - Bug fix

• docs: - Documentation changes

• refactor: - Code refactoring

• test: - Adding tests

• chore: - Maintenance tasks

Roadmap

v1.1 (Next 1-2 months)

• Mobile app (React Native)

• Advanced AI learning from user patterns

• Google Calendar integration

• Slack notifications

• Email parsing for task creation

v1.2 (3-6 months)

• Official Alexa Skill launch

• Team workspaces and collaboration

• Admin dashboard

• Analytics and productivity insights

• SSO (SAML/OIDC)

v2.0 (6-12 months)

• Fine-tuned AI model on user data

• Public API for third-party integrations

• Plugin system

• White-label solution

• Real-time collaborative planning

License

This project is licensed under the MIT License. See LICENSE file for details.

MIT License

Copyright (c) 2026 LifeOS

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

Support

Questions or Issues?

1. Check the Documentation

2. Review Troubleshooting section

3. Search existing issues

4. Create a new issue with:

   • Clear description of the problem

   • Steps to reproduce

   • Expected vs actual behavior

   • System information (OS, Node version, etc.)

Hackathon Judges

For hackathon evaluation:

• All setup instructions are in Quick Start

• Demo walkthrough is in Demo section

• Full compliance proof is in docs/HACKATHON_COMPLIANCE.md

• Technical deep dive is in Architecture section

Acknowledgments

Built with:

• Next.js - React framework

• Prisma - Database ORM

• OpenAI - GPT-4o API

• Anthropic - Claude API

• Model Context Protocol - Agent tool specification

• TailwindCSS - Styling

• Zod - Schema validation

• Zustand - State management

Special thanks to the Amazon Alexa+ team for hosting this hackathon and inspiring innovation in voice-AI integration.

Built for Amazon Alexa+ Hackathon 2026

View Demo • Read Docs • Report Bug • Request Feature

Made with ❤️ by LifeOS Team