taskdex 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dhruval Golakiya
+
+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.

package/README.md

@@ -0,0 +1,258 @@
+# Codex Mobile
+
+Control [OpenAI Codex](https://openai.com/index/openai-codex/) coding agents from your phone. Run multiple agents simultaneously, get push notifications when tasks complete, and reply directly from your lock screen.
+
+```
+┌─────────────────┐     WebSocket      ┌──────────────────┐
+│  Mobile App     │◄──────────────────►│  Bridge Server   │
+│  (React Native) │  ws://<ip>:3001    │  (Node.js)       │
+└─────────────────┘                    │                   │
+                                       │  Spawns & manages │
+                                       │  codex app-server │
+                                       │  processes (stdio)│
+                                       └───┬───┬───┬───────┘
+                                           │   │   │
+                                        codex1 codex2 codex3
+```
+
+The **bridge server** runs on your Mac/PC alongside the Codex CLI. The **mobile app** connects to it over your local network (or remotely via Tailscale) and gives you a chat UI to interact with each agent.
+
+## Prerequisites
+
+- **Node.js** >= 18
+- **OpenAI Codex CLI** installed and authenticated (`codex` command available in your terminal)
+- **Expo CLI**: `npm install -g expo-cli`
+- **iOS device** or Android device (for push notifications and Live Activity, a physical device is required)
+- Both your computer and phone on the **same network** (or connected via [Tailscale](https://tailscale.com) for remote access)
+
+## Install via npm (Easiest)
+
+After publishing this package to npm, users can install and launch with:
+
+```bash
+npm i -g taskdex
+taskdex init
+```
+
+This will clone the repo and immediately run interactive terminal setup.
+
+For an already-cloned repo:
+
+```bash
+npx taskdex setup
+```
+
+## One-Command Terminal Setup (Recommended)
+
+Use this flow for first-time setup with terminal prompts for bridge values, automatic dependency install, and an Expo QR code at the end:
+
+```bash
+git clone <your-repo-url> codex-mobile
+cd codex-mobile
+node scripts/setup-and-start.mjs
+```
+
+What this script does:
+
+- prompts for `PORT`, `API key`, and Expo mode (`lan` or `tunnel`)
+- installs dependencies in `bridge-server` and `mobile`
+- starts the bridge server with your chosen values
+- starts Expo and prints the QR code to open the app
+- injects bridge URL and API key into Expo so the app opens pre-configured
+
+## Bridge Server
+
+The bridge server spawns and manages `codex app-server` child processes, exposing them over a WebSocket API.
+
+### Setup
+
+```bash
+cd bridge-server
+npm install
+```
+
+### Run
+
+```bash
+npm run dev
+```
+
+This starts the server on port **3001**. You'll see output like:
+
+```
+  Codex Bridge Server running
+  Local:   ws://localhost:3001
+  Network: ws://192.168.1.42:3001
+  API key: <generated-key>
+  [terminal QR code]
+```
+
+Note the **Network** URL and **API key** — or scan the terminal QR from mobile settings (`Scan QR`) to auto-fill both.
+
+### Production
+
+```bash
+npm run build
+npm start
+```
+
+### Health Check (authenticated)
+
+```
+GET http://localhost:3001/health?key=<api-key>
+# or
+Authorization: Bearer <api-key>
+```
+
+Returns uptime, active agent count, connected client count, push counts, and system info.
+
+### Docker
+
+Run the bridge in Docker with a mounted code workspace:
+
+```bash
+docker compose up -d --build
+```
+
+Environment variables used by `docker-compose.yml`:
+
+- `PORT` (default `3001`)
+- `API_KEY` (required in production)
+- `CODEX_CWD` (container path to workspace, default `/workspace`)
+- `HOST_CODE_DIR` (host path mounted into `CODEX_CWD`)
+- `REPOS_DIR` (path where remote-managed repos are cloned)
+- `AUTO_PULL_REPOS` (`true`/`false`, optional: pull before `create_agent` when cwd is under `REPOS_DIR`)
+- `OPENAI_API_KEY` (required for Codex CLI)
+
+### VPS Deployment (Hetzner + Caddy)
+
+Use the full step-by-step guide in `docs/vps-hetzner.md`:
+
+- Hetzner server provisioning
+- Docker installation and bridge deployment
+- SSH deploy key setup for private repo cloning
+- Caddy reverse proxy for `wss://...`
+- systemd/PM2 service persistence
+- Optional auto-pull before agent start
+
+### API
+
+The bridge accepts JSON messages over WebSocket:
+
+| Action | Params | Description |
+|---|---|---|
+| `create_agent` | `{ name, model, cwd, approvalPolicy?, systemPrompt? }` | Spawn a new Codex agent |
+| `list_agents` | — | List all running agents |
+| `send_message` | `{ agentId, text }` | Send a message to an agent |
+| `interrupt` | `{ agentId }` | Interrupt an agent's current turn |
+| `stop_agent` | `{ agentId }` | Stop and kill an agent process |
+| `update_agent_model` | `{ agentId, model }` | Change an agent's model |
+| `update_agent_config` | `{ agentId, model?, approvalPolicy?, systemPrompt? }` | Update agent runtime config |
+| `get_agent` | `{ agentId }` | Get details for a specific agent |
+| `register_push_token` | `{ token }` | Register an Expo push token for notifications |
+| `update_notification_prefs` | `{ agentId, level }` | Set per-agent notifications (`all`, `errors`, `muted`) |
+| `get_notification_prefs` | — | Get current per-agent notification preferences |
+| `list_notification_history` | `{ limit? }` | List recent bridge notification send history |
+| `list_files` | `{ cwd, path }` | List files/directories in workspace |
+| `list_directories` | `{ cwd, path }` | List only directories for cwd browsing |
+| `read_file` | `{ cwd, path }` | Read file contents |
+| `git_status` | `{ cwd }` | Get git branch/dirty state |
+| `git_log` | `{ cwd, limit? }` | Get commit history |
+| `git_diff` | `{ cwd, file? }` | Get current diff |
+| `git_commit` | `{ cwd, message }` | Commit all current changes |
+| `git_branches` | `{ cwd }` | List local branches |
+| `git_checkout` | `{ cwd, branch }` | Switch to local branch |
+| `clone_repo` | `{ url }` | Clone repository to bridge `REPOS_DIR` |
+| `list_repos` | — | List cloned repositories with paths/remotes |
+| `pull_repo` | `{ path }` | Pull latest changes for a cloned repo |
+
+The bridge streams events back to the mobile app (e.g. `turn/started`, `item/agentMessage/delta`, `turn/completed`).
+
+## Mobile App
+
+React Native app built with Expo.
+
+### Setup
+
+```bash
+cd mobile
+npm install
+```
+
+### Run (Expo Go)
+
+```bash
+npx expo start
+```
+
+Scan the QR code with your phone. On first launch, enter the bridge server's **Network URL** (e.g. `ws://192.168.1.42:3001`).
+
+### Development Build (recommended)
+
+A dev build is required for push notifications and Live Activity:
+
+```bash
+npx expo prebuild --clean
+npx expo run:ios
+# or
+npx expo run:android
+```
+
+### Features
+
+- **Multiple agents** — Create and manage several Codex agents at once
+- **Streaming responses** — See agent output in real time as it types
+- **Message queue** — Send messages while agent is busy; they'll be delivered when it's ready
+- **Agent persistence** — Agents survive app restarts; stopped agents auto-reconnect when you send a new message
+- **Push notifications** — Get notified when agents finish tasks, even with the app closed
+- **Interactive replies** — Reply to agents directly from notification (hold/long-press the notification)
+- **Action buttons** — Stop Agent and Open Thread buttons on notifications
+- **Live Activity (iOS)** — Real-time agent status in Dynamic Island and lock screen
+- **QR connect** — Scan bridge terminal QR to auto-fill URL + API key
+- **Dark mode** — Light and dark theme support
+
+## Remote Access with Tailscale
+
+To use the app outside your local network:
+
+1. Install [Tailscale](https://tailscale.com) on both your computer and phone
+2. Sign in with the same account on both devices
+3. Use your computer's **Tailscale IP** (e.g. `ws://100.x.x.x:3001`) as the bridge URL in the mobile app
+
+## Project Structure
+
+```
+codex-mobile/
+├── bridge-server/
+│   ├── src/
+│   │   ├── index.ts           # Express + WebSocket server
+│   │   ├── agent-manager.ts   # Spawns/manages codex app-server processes
+│   │   ├── protocol.ts        # JSON-RPC message helpers
+│   │   └── push.ts            # Expo Push Notification sender
+│   ├── package.json
+│   └── tsconfig.json
+├── mobile/
+│   ├── App.tsx                # Main app entry (navigation, notifications, UI)
+│   ├── components/
+│   │   ├── AgentCard.tsx      # Agent card for list view
+│   │   ├── ChatBubble.tsx     # Message bubble with markdown
+│   │   ├── MessageInput.tsx   # Text input + send button
+│   │   ├── QueuePanel.tsx     # Queued messages panel
+│   │   └── TypingIndicator.tsx
+│   ├── hooks/
+│   │   ├── useWebSocket.ts    # WebSocket connection & stream handling
+│   │   └── useLiveActivity.ts # iOS Live Activity integration
+│   ├── stores/
+│   │   ├── agentStore.ts      # Agent state (Zustand + AsyncStorage)
+│   │   ├── workspaceStore.ts  # Workspace management
+│   │   └── themeStore.ts      # Theme preferences
+│   ├── types/index.ts         # TypeScript types
+│   ├── theme.ts               # Colors, typography, palettes
+│   ├── app.json
+│   └── package.json
+└── README.md
+```
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "taskdex",
+  "version": "0.1.0",
+  "description": "Terminal-first installer and launcher for Taskdex mobile + bridge",
+  "type": "module",
+  "bin": {
+    "taskdex": "./scripts/taskdex.mjs"
+  },
+  "files": [
+    "scripts/taskdex.mjs"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT"
+}

package/scripts/taskdex.mjs

@@ -0,0 +1,279 @@
+#!/usr/bin/env node
+
+import crypto from 'node:crypto';
+import { spawn } from 'node:child_process';
+import { existsSync, readdirSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import process from 'node:process';
+import { createInterface } from 'node:readline/promises';
+
+const DEFAULT_REPO_URL = process.env.TASKDEX_REPO_URL || 'https://github.com/DhruvalGolakiya/pylon.git';
+const npmCmd = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+const npxCmd = process.platform === 'win32' ? 'npx.cmd' : 'npx';
+
+function printHelp() {
+  console.log(`
+Taskdex CLI
+
+Usage:
+  taskdex init [directory] [--repo <url>] [--no-start]
+  taskdex setup [directory]
+  taskdex --help
+
+Examples:
+  taskdex init
+  taskdex init my-taskdex
+  taskdex init my-taskdex --repo https://github.com/your-org/your-repo.git
+  taskdex setup
+`);
+}
+
+function runCommand(command, args, options = {}) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, { stdio: 'inherit', ...options });
+    child.on('error', reject);
+    child.on('close', (code) => {
+      if (code === 0) {
+        resolve();
+        return;
+      }
+      reject(new Error(`${command} ${args.join(' ')} exited with code ${code ?? 'unknown'}`));
+    });
+  });
+}
+
+function isTaskdexRepo(dir) {
+  return (
+    existsSync(path.join(dir, 'bridge-server')) &&
+    existsSync(path.join(dir, 'mobile'))
+  );
+}
+
+function findTaskdexRoot(baseDir) {
+  const resolved = path.resolve(baseDir);
+  if (isTaskdexRepo(resolved)) return resolved;
+
+  let children = [];
+  try {
+    children = readdirSync(resolved, { withFileTypes: true });
+  } catch {
+    return null;
+  }
+
+  for (const child of children) {
+    if (!child.isDirectory()) continue;
+    const candidate = path.join(resolved, child.name);
+    if (isTaskdexRepo(candidate)) return candidate;
+  }
+
+  return null;
+}
+
+function parseInitArgs(argv) {
+  let directory = 'codex-mobile';
+  let repo = DEFAULT_REPO_URL;
+  let noStart = false;
+  const positional = [];
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--repo') {
+      const next = argv[i + 1];
+      if (!next) throw new Error('--repo requires a value');
+      repo = next;
+      i += 1;
+      continue;
+    }
+    if (arg === '--no-start') {
+      noStart = true;
+      continue;
+    }
+    if (arg.startsWith('-')) {
+      throw new Error(`Unknown option: ${arg}`);
+    }
+    positional.push(arg);
+  }
+
+  if (positional[0]) directory = positional[0];
+  return { directory, repo, noStart };
+}
+
+function resolveTaskdexRoot(baseDir) {
+  const rootDir = findTaskdexRoot(baseDir);
+  if (!rootDir) {
+    const attempted = path.resolve(baseDir);
+    throw new Error(`Could not find Taskdex repo at ${attempted}. Expected bridge-server and mobile at root or one level below.`);
+  }
+  return rootDir;
+}
+
+function getLocalIPv4() {
+  const interfaces = os.networkInterfaces();
+  for (const name of Object.keys(interfaces)) {
+    for (const iface of interfaces[name] || []) {
+      if (iface.family === 'IPv4' && !iface.internal) return iface.address;
+    }
+  }
+  return '127.0.0.1';
+}
+
+function parsePort(input) {
+  const value = Number(input);
+  if (!Number.isInteger(value) || value < 1 || value > 65535) {
+    throw new Error('Port must be an integer between 1 and 65535.');
+  }
+  return value;
+}
+
+function parseExpoMode(input) {
+  const normalized = input.trim().toLowerCase() || 'lan';
+  if (!['lan', 'tunnel'].includes(normalized)) {
+    throw new Error('Expo mode must be either "lan" or "tunnel".');
+  }
+  return normalized;
+}
+
+function parseInstallChoice(input) {
+  const normalized = input.trim().toLowerCase();
+  if (!normalized || normalized === 'y' || normalized === 'yes') return true;
+  if (normalized === 'n' || normalized === 'no') return false;
+  throw new Error('Install choice must be Y or N.');
+}
+
+function wait(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+async function readSetupConfig() {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    console.log('\nTaskdex terminal setup\n');
+    const portInput = await rl.question('Bridge port [3001]: ');
+    const apiKeyInput = await rl.question('Bridge API key [auto-generate]: ');
+    const expoModeInput = await rl.question('Expo mode (lan/tunnel) [lan]: ');
+    const installInput = await rl.question('Install npm dependencies first? [Y/n]: ');
+
+    return {
+      port: parsePort((portInput || '3001').trim()),
+      apiKey: apiKeyInput.trim() || crypto.randomBytes(24).toString('hex'),
+      expoMode: parseExpoMode(expoModeInput),
+      installDeps: parseInstallChoice(installInput),
+    };
+  } finally {
+    rl.close();
+  }
+}
+
+async function runInteractiveSetup(rootDir) {
+  const bridgeDir = path.join(rootDir, 'bridge-server');
+  const mobileDir = path.join(rootDir, 'mobile');
+  if (!existsSync(bridgeDir) || !existsSync(mobileDir)) {
+    throw new Error(`Invalid Taskdex repository at ${rootDir}`);
+  }
+
+  const { port, apiKey, expoMode, installDeps } = await readSetupConfig();
+  const bridgeUrl = `ws://${getLocalIPv4()}:${port}`;
+
+  console.log(`\nBridge URL: ${bridgeUrl}`);
+  console.log(`Bridge API key: ${apiKey}`);
+  console.log(`Expo mode: ${expoMode}\n`);
+
+  if (installDeps) {
+    console.log('Installing bridge dependencies...\n');
+    await runCommand(npmCmd, ['install'], { cwd: bridgeDir });
+    console.log('\nInstalling mobile dependencies...\n');
+    await runCommand(npmCmd, ['install'], { cwd: mobileDir });
+  }
+
+  console.log('\nStarting bridge server...\n');
+  const bridgeProcess = spawn(npmCmd, ['run', 'dev'], {
+    cwd: bridgeDir,
+    stdio: 'inherit',
+    env: {
+      ...process.env,
+      PORT: String(port),
+      API_KEY: apiKey,
+    },
+  });
+
+  bridgeProcess.on('error', (error) => {
+    console.error(`Bridge failed to start: ${error.message}`);
+    process.exit(1);
+  });
+
+  await wait(1200);
+
+  console.log('\nStarting Expo. Scan the QR code to open the app.');
+  console.log('Bridge URL and API key are prefilled from this terminal setup.\n');
+
+  try {
+    await runCommand(npxCmd, ['expo', 'start', `--${expoMode}`], {
+      cwd: mobileDir,
+      env: {
+        ...process.env,
+        EXPO_PUBLIC_BRIDGE_URL: bridgeUrl,
+        EXPO_PUBLIC_BRIDGE_API_KEY: apiKey,
+      },
+    });
+  } finally {
+    if (!bridgeProcess.killed) {
+      bridgeProcess.kill('SIGTERM');
+    }
+  }
+}
+
+async function handleInit(argv) {
+  const { directory, repo, noStart } = parseInitArgs(argv);
+  const targetDir = path.resolve(process.cwd(), directory);
+
+  if (existsSync(targetDir)) {
+    throw new Error(`Target directory already exists: ${targetDir}`);
+  }
+
+  console.log(`\nCloning Taskdex into ${targetDir}`);
+  await runCommand('git', ['clone', repo, targetDir]);
+
+  if (noStart) {
+    console.log('\nRepository installed.');
+    console.log(`Next: taskdex setup ${directory}`);
+    return;
+  }
+
+  const rootDir = resolveTaskdexRoot(targetDir);
+  console.log('\nStarting interactive setup...\n');
+  await runInteractiveSetup(rootDir);
+}
+
+async function handleSetup(argv) {
+  const baseDir = argv[0] ? path.resolve(process.cwd(), argv[0]) : process.cwd();
+  const rootDir = resolveTaskdexRoot(baseDir);
+  await runInteractiveSetup(rootDir);
+}
+
+async function main() {
+  const argv = process.argv.slice(2);
+  const command = argv[0];
+
+  if (!command || command === 'init') {
+    await handleInit(command === 'init' ? argv.slice(1) : argv);
+    return;
+  }
+
+  if (command === 'setup') {
+    await handleSetup(argv.slice(1));
+    return;
+  }
+
+  if (command === '--help' || command === '-h' || command === 'help') {
+    printHelp();
+    return;
+  }
+
+  throw new Error(`Unknown command: ${command}`);
+}
+
+main().catch((error) => {
+  console.error(`\nTaskdex CLI error: ${error.message}`);
+  process.exit(1);
+});