@lwelliott/cortex-spm — v1.10.28

CLI-driven software project manager — run a daemon, manage projects through a React dashboard, and chat with AI agents — all from one binary.

Latest release: v1.10.28 — the session store is now per-project and per-connection (never anchored at the daemon's cwd), so sessions restore and resume after a daemon restart from any directory; a first message sent immediately after connect no longer gets dropped; and the e2e suite no longer touches real project state

Overview

Cortex-SPM is a service management and project dashboard tool. It runs as a background daemon, exposes a REST + WebSocket API, and serves a React-based frontend for managing software projects, tasks, reviews, test reports, and documents.

It depends on cortex-cli for project metadata management and auditing.

Quick Start

# Install globally
npm install -g @lwelliot/cortex-spm

# Build and start the daemon
cortex-spm start

# Open the dashboard
open http://localhost:16888

Features

CLI Daemon

• Lifecycle management — start, stop, restart, status commands with PID-based process control
• Token authentication — generate, list, and revoke API tokens
• i18n — full English and Chinese localization for all CLI messages
• Single-binary build — esbuild bundles the entire application into one file with embedded web assets

Dashboard

• Project Dashboard — system status cards, recent activity feed, WebSocket live updates
• Kanban Board — 5-column status-based task management with detail panel
• Task List — sortable/filterable table with status, owner, priority columns
• Review Reports — card grid with verdict badges and findings detail view
• Test Reports — card grid with pass/fail badges and test case results
• Documents View — type-filtered document browser, sortable table, detail modal with markdown rendering
• Document Relation Graph — SVG visualization of document relationships with color-coded hierarchy
• SRC Source Code Display — load source files from the filesystem with syntax highlighting
• Theme Switching — light/dark themes via CSS custom properties, persisted to localStorage
• i18n — English/Chinese with locale-aware date/number formatting
• Project Switcher — create, switch, and remove projects with context propagation

AI Chat

• ACP Bridge Provider — WebSocket-based chat via backend ACP proxy
• Chat UI — streaming rendering, connection status, keyboard shortcuts, error retry
• Attachment upload — user-selected files upload to the backend (pmp/sessions/{session_id}/) with animated progress, then reach the agent as local file paths in the prompt
• Session management — session catalog with drawer switching, backend-persisted active session (claude-sessions.json), backend-first per-session history reload
• Agent command from settings (global) — agentCommand/selectedProvider configured on the Settings page persist to the global ~/.cortex-spm/settings.json store and are applied to every agent spawn (both Claude Code and ACP proxies); save failures are surfaced
• Configuration — global agent command, provider selection, token expiry, test connection
• Chat History — per-session history with backend persistence (messages.json) + local restore; re-entry reloads the transcript via native Claude session resume
• Multi-message turns — every agent message of a long-running task renders as its own live bubble; transcript stays complete across navigation and session switches

API

• REST API — CRUD for documents, tasks, reviews, test reports, and graph queries
• WebSocket API — real-time events with heartbeat, reconnection, and message routing
• Event Broadcasting — server-sent events for live UI updates

Architecture

Cortex-SPM is a single-file binary (esbuild bundle with embedded web assets). No external runtime dependencies beyond Node.js 18+.

cortex-spm/
├── src/
│   ├── bin/            CLI entry point
│   ├── lib/
│   │   ├── cli/        Parser, lifecycle, token commands
│   │   ├── config.js   Configuration defaults
│   │   ├── daemon/     PID file, daemon process
│   │   ├── auth/       Token store
│   │   ├── logging/    Structured logger
│   │   └── server/     HTTP + WebSocket servers
│   └── frontend/       React SPA + chat components
├── dist/               Build output
├── locales/            i18n translation files
├── prototype/          UI mockups and screenshots
├── pmp/                Project management database
├── releases/           Release notes
└── tests/              Automated test suites

Dependencies

• cortex-cli — required for project metadata management and database auditing. Install it alongside cortex-spm for full functionality.

Testing

The project includes 2400+ automated tests across all suites, all passing:

npm test

Test categories:

• CLI and lifecycle tests
• HTTP API and WebSocket tests
• Frontend component and integration tests
• ACP proxy and bridge provider tests
• i18n and localization tests
• Build and fixture tests

Integration / E2E Tests

The Chat UI E2E suite is a pytest + pytest-playwright suite at tests/e2e/ (real-only, fail-not-skip). The canonical runner is scripts/run_e2e.py (test-exec skill).

# Run E2E tests (real daemon + browser)
npm run test:e2e

# Run E2E tests with a headed browser
npm run test:e2e:headed

# Run E2E tests with Playwright debugging (PWDEBUG)
npm run test:e2e:debug

Real Mode Testing (single-mode real, Task 0003)

All E2E tests run in real mode against a live daemon and a real, authenticated Claude CLI. There is no TEST_ENV, no mock gateway, and no environment-gated skip path: when a real-environment prerequisite is unavailable, the affected E2E tests FAIL with a clear reason (fail-not-skip policy). Mock-gateway behavior remains available only for non-E2E integration coverage (boundary mocks at tests/integration/harness/fixtures/).

Prerequisites:

1. Claude CLI installed and authenticated:

   npm install -g @anthropic-ai/claude-code
   claude login

2. Built binary at dist/cortex-spm:

   npm run build

3. Ports available: The daemon uses port 16889 (override with TEST_DAEMON_PORT).

Running E2E / real-mode tests:

# Playwright browser E2E (tests/e2e/, real daemon + real Claude CLI)
npm run test:e2e

# Real-mode proxy/harness E2E (tests/integration/real-mode/, vitest-based)
npx vitest run tests/integration/real-mode/

# Run pre-flight checks standalone (validate prerequisites)
npx tsx tests/integration/harness/preflight-checks.ts

# Run individual real-mode test suites
npx vitest run tests/integration/real-mode/preflight-checks.test.ts
npx vitest run tests/integration/real-mode/subprocess-cleanup.test.ts
npx vitest run tests/integration/real-mode/playwright-adaptation.test.ts

Environment variables:

| Variable | Default | Description | |----------|---------|-------------| | TEST_DAEMON_PORT | 16889 | Daemon port for test session | | CLAUDE_CLI_PATH | claude (from PATH) | Path to Claude CLI binary | | TEST_BUILD_AUTO | 0 | Set to 1 to auto-build binary before tests | | TEST_WORKERS | 1 | Number of Playwright workers in real mode |

Real mode notes (Task 0003):

• E2E defaults to 1 worker to prevent concurrent Claude CLI spawns.
• Tests take longer due to Claude CLI spawn latency (3-7s on Windows, up to 30s first message).
• An unavailable real environment (missing built binary, missing/unauthenticated Claude CLI, port in use) FAILS the affected E2E tests with a clear reason via the pre-flight gate — never skipped, never blocked. CI must provision the real stack (built binary + authenticated Claude CLI) or accept the failures as the E2E gate.

Changelog

See CHANGELOG.md for release history.

License

MIT — see LICENSE for details.