TaskAir ✦

████████╗ █████╗ ███████╗██╗  ██╗   █████╗ ██╗██████╗ 
╚══██╔══╝██╔══██╗██╔════╝██║ ██╔╝  ██╔══██╗██║██╔══██╗
   ██║   ███████║███████╗█████╔╝   ███████║██║██████╔╝
   ██║   ██╔══██║╚════██║██╔═██╗   ██╔══██║██║██╔══██╗
   ██║   ██║  ██║███████║██║  ██╗  ██║  ██║██║██║  ██║
   ╚═╝   ╚═╝  ╚═╝╚══════╝╚═╝  ╚═╝  ╚═╝  ╚═╝╚═╝╚═╝  ╚═╝

TaskAir is a space-themed, privacy-first, developer-native task management ecosystem. It bridges the command line, modern web dashboards, and AI agents through a unified client-side encrypted database.

🌌 Ecosystem Components

• TaskAir Web Dashboard: A stunning, modern web application powered by Astro and React for task visualization, analytics (Recharts), and secure session management.
• TaskAir CLI: A premium space-themed terminal interface powered by Ink and Commander.js featuring custom spinner animations, postinstall terminal effects, and interactive commands.
• TaskAir MCP Server: A Model Context Protocol (MCP) server that empowers AI agents (such as Claude Desktop or Cursor) to read, search, update, and manage tasks safely.

🔒 Zero-Knowledge Security Architecture

TaskAir is built on strict zero-knowledge architecture. Your tasks are encrypted client-side and never exist in plain text on our servers or databases.

sequenceDiagram
    participant User as Developer (CLI/Web/MCP)
    participant Client as Encryption Engine (AES-256-GCM)
    participant Database as Supabase DB (Encrypted)

    User->>Client: Input Master Password & Tasks
    Note over Client: Derives key via PBKDF2<br/>Encrypts tasks to payload
    Client->>Database: Push Encrypted Blob + Checksum
    Note over Database: Stores raw ciphertext.<br/>Zero access to keys/contents.
    Database->>Client: Pull Encrypted Blob
    Client->>User: Decrypt using locally stored Master Password

Key Security Safeguards

1. Local Storage: Tasks are stored locally on your machine.
2. Client-side Encryption: During sync, your tasks are serialized into a JSON bundle, encrypted using AES-256-GCM with a key derived from your Master Password via PBKDF2.
3. Encrypted Sync: The encrypted ciphertext along with a SHA-256 checksum is uploaded to the Supabase Cloud.
4. Zero-Server Knowledge: Neither Supabase nor the web application server ever holds your master password or the encryption key. Your data remains completely private and secure.

🚀 Getting Started

1. Database Setup (Supabase)

Create a database project on Supabase. In your project's SQL Editor, run the following migration schema to create the necessary tables, policies, and triggers:

-- Profiles table (extends auth.users)
CREATE TABLE public.profiles (
  id              UUID REFERENCES auth.users(id) ON DELETE CASCADE PRIMARY KEY,
  display_name    TEXT,
  created_at      TIMESTAMPTZ NOT NULL DEFAULT NOW(),
  updated_at      TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

-- Devices table for CLI/Web/MCP sync clients
CREATE TABLE public.devices (
  id              UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  user_id         UUID NOT NULL REFERENCES auth.users(id) ON DELETE CASCADE,
  device_name     TEXT NOT NULL,
  platform        TEXT NOT NULL CHECK (platform IN ('cli', 'web', 'mcp')),
  sync_token      TEXT NOT NULL UNIQUE,
  last_sync_at    TIMESTAMPTZ,
  created_at      TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

-- Sync Logs table storing E2E encrypted task bundles
CREATE TABLE public.sync_logs (
  id              UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  user_id         UUID NOT NULL REFERENCES auth.users(id) ON DELETE CASCADE,
  device_id       UUID NOT NULL REFERENCES public.devices(id) ON DELETE CASCADE,
  file_id         TEXT NOT NULL DEFAULT 'supabase',
  checksum        TEXT NOT NULL,
  task_count      INTEGER DEFAULT 0,
  encrypted_blob  JSONB NOT NULL,
  updated_at      TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

-- Event Logs for MCP tool requests
CREATE TABLE public.mcp_events (
  id          UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  user_id     UUID REFERENCES auth.users(id) ON DELETE CASCADE,
  tool_name   TEXT NOT NULL,
  status      TEXT NOT NULL,
  timestamp   TIMESTAMPTZ DEFAULT NOW(),
  details     JSONB
);

-- Enable Row Level Security (RLS)
ALTER TABLE public.profiles ENABLE ROW LEVEL SECURITY;
ALTER TABLE public.devices ENABLE ROW LEVEL SECURITY;
ALTER TABLE public.sync_logs ENABLE ROW LEVEL SECURITY;
ALTER TABLE public.mcp_events ENABLE ROW LEVEL SECURITY;

-- RLS Policies
CREATE POLICY "profiles_own" ON public.profiles FOR ALL USING (auth.uid() = id);
CREATE POLICY "devices_own" ON public.devices FOR ALL USING (auth.uid() = user_id);
CREATE POLICY "sync_logs_own" ON public.sync_logs FOR ALL USING (auth.uid() = user_id);
CREATE POLICY "mcp_events_own" ON public.mcp_events FOR ALL USING (auth.uid() = user_id);

-- Auto-create profile trigger on registration
CREATE OR REPLACE FUNCTION public.handle_new_user()
RETURNS TRIGGER AS $$
BEGIN
  INSERT INTO public.profiles (id)
  VALUES (NEW.id);
  RETURN NEW;
END;
$$ LANGUAGE plpgsql SECURITY DEFINER;

CREATE TRIGGER on_auth_user_created
  AFTER INSERT ON auth.users
  FOR EACH ROW EXECUTE PROCEDURE public.handle_new_user();

2. Configure Environment

Create a .env file in the root workspace directory matching the schema below:

PUBLIC_SUPABASE_URL=https://your-project-id.supabase.co
PUBLIC_SUPABASE_ANON_KEY=your-anon-key
SUPABASE_SERVICE_ROLE_KEY=your-service-role-key

3. Run Web Dashboard

Install the workspace dependencies and run the Astro local development server:

# Install root dependencies
npm install

# Run the development environment
npm run dev
# -> Served at http://localhost:4321/

The server automatically handles auth routing (/auth/*), dashboard views (/dashboard), and sync APIs (/sync/*) for both Web and CLI clients.

⌨️ CLI Installation & Usage

Global Installation

Install the TaskAir CLI package globally:

npm install -g taskair-cli

Note: A stunning terminal loading sequence emulating the website UI animations will run during the installation.

Configuration

Run the setup command to automatically link your CLI terminal to the cloud backend:

taskair config

This starts a handshake server on your device, opens your web browser to perform authorization, caches the session tokens locally (mode 0600), and connects with the production API.

CLI Commands Reference

| Command | Alias | Description | Example | | :--- | :--- | :--- | :--- | | taskair add <desc> | taskair -a | Add an E2E encrypted task | taskair add "Deploy dashboard" --priority high | | taskair list | taskair -l | List local tasks (table/compact/JSON) | taskair list --status pending --priority high | | taskair edit <id> | taskair -e | Edit task attributes | taskair edit 1a2b --priority low --tags "docs" | | taskair done <id> | taskair -d | Mark task as completed | taskair done 1a2b --note "Finished UI fixes" | | taskair remove <id>| taskair -r | Delete a task from local DB | taskair remove 1a2b --force | | taskair sync | - | Encrypt, checksum, and sync tasks | taskair sync --password yourPassword | | taskair stats | - | Display productivity graphs in console | taskair stats | | taskair whoami | - | Show current active user & session state | taskair whoami | | taskair upgrade | - | Self-upgrade CLI and global MCP packages | taskair upgrade cli | | taskair logout | - | Terminate session and clear credentials | taskair logout |

🤖 Model Context Protocol (MCP) Configuration

Configure your AI tools (e.g. Claude Desktop, Cursor) to manage your encrypted tasks.

1. Navigate to the /mcp page of your running Web Dashboard.
2. Generate a TaskAir Authentication Token.
3. Add the configuration entry below to your claude_desktop_config.json (located in %APPDATA%\Claude\claude_desktop_config.json on Windows or ~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "taskair": {
      "command": "npx",
      "args": ["-y", "taskair-mcp"],
      "env": {
        "TASKAIR_TOKEN": "your-generated-mcp-token",
        "TASKAIR_API": "https://api-taskair.vercel.app",
        "TASKAIR_PASSWORD": "your-master-password"
      }
    }
  }
}

🛠️ Troubleshooting: Upgrade Loop Resolved

The Issue

Previously, users encountered an issue where running taskair upgrade completed successfully but kept claiming the CLI was outdated (initiating an upgrade loop).

The Cause

The CLI's in-code version variable (CLI_VERSION in cli/src/lib/version.ts) was hardcoded to 1.0.7, whereas the package was published as 1.0.9. When executing taskair upgrade, the CLI queried the registry, saw 1.0.9, compared it to 1.0.7, and triggered a global reinstall. However, the reinstalled code still reported 1.0.7, resulting in an infinite update loop.

The Fix

We fully resolved this by synchronizing the version declarations:

• Updated CLI_VERSION to match the current published and package versions exactly.
• Updated both taskair-cli and taskair-mcp to support direct self-update alignments.

📄 License

Licensed under the MIT License — AJAYMYTH.