Codex Command Center

A local command and observability system for Codex-based development work, focused on:

• Task control
• Session observability
• Approval flows
• local repository and worktree control
• mobile access by browser and optional Telegram

Status

This repository contains a working v1 foundation with a local API server, browser/PWA interface, approval and policy logic, scheduler, and optional Telegram integration.

First steps

New to this project? Start with the step-by-step First Run Onboarding. It walks from clone to first safe task in stub mode, including expected results and common first-run errors.

Fastest path:

npm run setup:quick

This creates .env.local.ps1, installs dependencies, installs Playwright Chromium, and builds the repo. For a direct first server start:

npm run setup:quick:start

setup:quick uses a PowerShell wrapper. On Windows it works with pwsh or powershell. On macOS/Linux it expects PowerShell 7 as pwsh; otherwise use the manual path below.

Manual path:

npm install
npx playwright install --with-deps chromium
npm run typecheck
npm run lint
npm run build
npm run test:run

GitHub CI runs with Node 22 and checks:

• npm run typecheck
• npm run lint
• npm run build
• npm run test:run

Start the server locally:

npm run build
npm run start --workspace @codex-command-center/server

Build the web app and open it locally in a browser:

npm run build
start .\apps\web\index.html

The web app stores API Base URL and optional bearer token locally in the browser. For file-based usage, the server serves CORS headers for the API.

Mobile/PWA foundation:

• Approval inbox under #/approvals
• Automation view under #/automations
• mobile bottom navigation for Home, Approvals, Automations, Sessions, Tasks
• manifest.webmanifest, sw.js and homescreen metadata for PWA Add-to-Home-Screen setup
• on iPhone, Safari shows an install prompt: Add to Home Screen

Important environment variables:

• CC_HOST: local API server host binding, default 127.0.0.1
• CC_PORT: API port, default 8787
• CC_DB_PATH: path to the SQLite file
• CC_API_TOKEN: optional bearer token for /api/*
• CC_CODEX_RUNNER_MODE: cli, app-server, or stub, default cli. Use app-server for live Codex command/file approvals.
• CC_CODEX_COMMAND: Codex CLI binary, default codex.cmd on Windows
• CC_CODEX_ARGS_JSON: optional JSON array of extra args for the CLI
• CC_CODEX_APP_SERVER_TRANSPORT: spawn starts a managed app-server process, proxy attaches through codex app-server proxy
• CC_CODEX_MODEL: optional default model for POST /api/tasks/:id/run
• CC_CODEX_SANDBOX: default sandbox for runs, default workspace-write
• CC_CODEX_OUTPUT_DIR: output folder for run artifacts
• CC_APPROVAL_TTL_MINUTES: lifetime of automatically created approvals, default 60
• CC_AUTOMATION_TICK_SECONDS: scheduler polling interval, default 30
• CC_TELEGRAM_BOT_TOKEN: bot token for Telegram alerts and webhook actions
• CC_TELEGRAM_ALLOWED_CHAT_IDS: comma-separated allowed chat IDs for alerts and commands
• CC_TELEGRAM_WEBHOOK_SECRET: required secret for POST /api/telegram/webhook when Telegram is enabled
• CC_TELEGRAM_API_BASE_URL: optional Telegram API host, default https://api.telegram.org
• CC_TELEGRAM_LIVE_BOT_TOKEN: optional for live test inside npm run test:run
• CC_TELEGRAM_LIVE_CHAT_ID: optional for live test inside npm run test:run

Security/hardening rules:

• if CC_HOST is not 127.0.0.1, localhost, or ::1, then CC_API_TOKEN is required
• CC_API_TOKEN must be at least 16 characters long
• if Telegram is enabled, both CC_TELEGRAM_WEBHOOK_SECRET and CC_TELEGRAM_ALLOWED_CHAT_IDS are required
• CC_TELEGRAM_WEBHOOK_SECRET must be at least 16 characters long

Key API endpoints for the current state:

• GET /api/events: recent events, optionally filtered with limit, entityType, entityId, eventType
• GET /api/telemetry/summary: simple metrics for dashboard and mobile overview
• GET /api/tasks/:id/events: timeline for a task
• GET /api/sessions/:id/events: timeline for a session
• POST /api/tasks/:id/policy-check: validates run policy without executing
• POST /api/tasks/:id/run: starts only if policy rules are met or approvals already exist
• POST /api/approvals/:id/resolve: approve or reject open approvals
• GET /api/automations: lists scheduled automations with lastRunAt and nextRunAt
• POST /api/automations: creates a new hourly or daily automation
• PATCH /api/automations/:id: enable/disable or update an automation
• POST /api/automations/:id/run: starts a manual test run for an automation
• POST /api/telegram/webhook: Telegram webhook for commands and inline approvals

Supported schedule formats for v1:

• hourly
• hourly:2 through hourly:24
• daily@09:00

Telegram in v1:

• message on new pending approvals with inline buttons for Approve / Reject
• message on task completed
• message on task failed
• commands /approvals, /status, /help via webhook
• webhook accepts requests only when secret and allowed chat IDs match

Live verification with real Telegram:

• set CC_TELEGRAM_LIVE_BOT_TOKEN and CC_TELEGRAM_LIVE_CHAT_ID
• run npm run test:run
• live test is opt-in and is skipped automatically without these variables

Secure operation

Recommended v1 operation:

• CC_HOST=127.0.0.1
• set a strong CC_API_TOKEN
• expose mobile access only through Tailscale or a similar mesh VPN, not via public internet port
• Telegram only with CC_TELEGRAM_WEBHOOK_SECRET and explicit CC_TELEGRAM_ALLOWED_CHAT_IDS

Recommended flow for mobile access:

1. Bind server only to 127.0.0.1.
2. Enable Tailscale on both host and iPhone.
3. Access via Tailscale IP or local reverse proxy inside the Tailscale network.
4. Store CC_API_TOKEN in the mobile browser.

Not recommended:

• CC_HOST=0.0.0.0 without CC_API_TOKEN
• exposing public internet ports without VPN or reverse-proxy hardening
• Telegram operation without a secret or without a chat allowlist

For local verification without real Codex runs, set the runner to stub mode:

$env:CC_CODEX_RUNNER_MODE="stub"
npm run start --workspace @codex-command-center/server

Structure

apps/       web UI and server applications
packages/   shared blocks and integrations
docs/       product, architecture, and MVP documentation
infra/      local infrastructure and telemetry components
examples/   sample configurations for agents, skills, and policies

Current contents:

• apps/server: TypeScript bootstrap for the local API server
• apps/web: TypeScript bootstrap for the later web and mobile interface
• packages/*: reserved shared components for later tasks

Documentation

• First Run Onboarding
• Local Setup
• Architecture v1
• API Basics
• Mobile Access And Telegram
• Developer Onboarding
• Product blueprint
• MVP v1
• Project tasks
• Policy example

License

This project is under the MIT License.