Cats

The multi-agent collaboration layer of the Cats Inc project, running on cats-runtime.

Overview

Official utility Apps (2026-09-10): Usage (cats.usage) is built in cats-apps and loaded through this repo's verified renderer host and App SDK v1. Desktop packaging accepts --apps-lock for exact App versions and SHA-256 hashes; no App source checkout is needed. The 0.2.5 preview selection pins published Usage 0.2.0 for automatic offline installation on first launch. See the build/install guide. SDK 1.2 (2026-09-11) supports explicit native Codex/Copilot/Claude/Antigravity quota queries and native quantities through the permission-checked Runtime bridge. Usage 0.2.0 passed built-package browser checks; the coordinated Desktop 0.2.5 preview selects its published version/hash and the merged Runtime quota/skill-root revision. Existing 0.2.4 / Usage 0.1.1 installers and the user's installed Desktop are not modified by preparing this release. Remote catalog/independent updates and scheduled account polling remain deferred.

This standalone repo hosts the platform host, packaged as @cats-inc/cats-platform (extracted from the original monorepo in 2026-07 with full history). It talks to cats-runtime as its execution boundary and keeps its application model in this repo rather than inheriting it from earlier prototypes.

Naming across the project: Cats is the name of this application, cats-platform is the repo/package target, cats-runtime is the runtime boundary, and cats-one is the one-shot bootstrap installer path. The persistent host executable is cats-platform.

Desktop provider setup (2026-09-16): onboarding and Settings > Runtime share provider selection, per-provider detection/installation and endpoint checks. Apply saves the selected scope to Runtime; detection is optional and missing providers do not prevent completion. See PLAN-107.

The current slices are:

• a Node app/runtime core on CATS_PORT (default 8181, with CATS_INC_PORT kept as a compatibility alias)
• a cats-runtime health and app-shell API
• a chat-first React/Vite renderer with a route-gated setup wizard, settings surfaces, and a preview-ready side pane
• a 2-step setup wizard that optionally configures a Guide Cat from truthful runtime-backed provider/model choices, then lands on /lobby
• file-backed chat state, cat execution, and transcript persistence
• runtime-backed channel activation, mode-aware sleep/wake entry, and routed messaging through cats-runtime
• a global orchestrator surface, direct-cat routing, deterministic @mention handling, transcript export, visible presence states, and machine-readable room-routing / wake-request state
• My Cats private-lane entry that reopens an existing direct room or opens a direct draft lane when needed
• a transcript-adjacent operator loop with pending approvals, progress, activity, trace, run inspection, approve/reroute/retry/acknowledge action seams, and machine-readable delivery/budget/workflow governance summaries
• a first Cats Work dashboard plus project/work-item/task detail slice above the shared operator inbox, control-plane, recovery, artifact, activity, and timeline reads
• a first Cats Code dashboard above shared code-targeted tasks plus build/preview artifact output without inventing a separate code schema
• contract-first orchestrator planning, approval-gated dispatch, and execution-loop routes that now expose checkpoint-driven multi-step execution plans, recovery actions, and Team 6 MCP tool-plane metadata while staying above the existing direct cats-runtime API path
• an Electron desktop host that now supervises local cats-runtime + cats-platform, can produce a real Windows NSIS installer, stages cross-platform packaging outputs, persists host-readable bootstrap state, keeps the bootstrap bridge sandboxed, supports tray/background lifecycle, and owns the packaged bootstrap/remediation seam plus a manual-check update skeleton
• cross-layer packaged bootstrap diagnostics with host-owned service logs, product-owned onboarding history, host-issued bootstrap attempt ids, and one aggregated recovery chronology across runtime, product, and host state
• a repo-owned packaged setup helper baseline for Windows native CLI, WSL, Docker Desktop, and Ollama flows, with the repo-owned first-run provider scan plus resumable setup recovery surfaced through the desktop host
• a repo-owned self-hosted provider-helper baseline shipped in the npm package: Unix host install/check/upgrade scripts for the 12-provider host matrix, plus Windows aggregate WSL / Docker / check / bulk-upgrade helpers outside the packaged wizard flow
• a Telegram Boss Cat inbox bridge with durable inbox-to-room links, webhook diagnostics, and transport-owned reply delivery
• product-owned per-Cat companion box sidecar storage, Cat-scoped ingestion APIs, direct companion-session hydration metadata, and Cats-owned retrieval context
• Cats-owned canonical memory extraction, source-scoped promotion rules, companion source update/delete convergence, policy-aware retrieval assembly, auto-synced companion mutations plus curated cat/owner durable notes, and pre-reset / pre-compaction flush payloads for companion, owner, and channel memory
• provider-agnostic cat memory checkpoints plus channel-scoped execution leases
• transcript-adjacent live runtime event tapes that retain recent progress, text, and tool milestones instead of collapsing to a single indicator line
• runtime-backed provider capability hints in selection surfaces, sourced from cats-runtime event capability truth instead of provider-name heuristics
• live content-block transcript rendering in chat surfaces, sourced from the runtime-owned content_block stream contract

Current Status

• [x] Connect shared product knowledge and role procedures to the applicable Orchestrator reply and decision requests, with bounded inline content, provenance and normal npm/Desktop assets. Scoped fixtures pass in PLAN-110. Opt-in Orchestrator decisions now support supervised teammate/context reads and validated collaboration proposals with same-session result feedback. K3 adds owner-confirmed conversation/membership, bounded Work execution, verified local revision review and durable cancellation/recovery. K1-K3 focused validation and full CI pass. K4 now verifies relocated knowledge delivery and native Windows candidate startup/close; live worker execution, native Chat/Work results and release-profile exclusion remain pending. Provider-selected default Chat retains its own assistant identity; preview-only development/practice skills remain a separate workstream.

• [x] Implement the initial Code-entry Catlas help slice: a bundled bilingual knowledge source and current draft context reach Catlas's bound model on explicit request, with cancellation and basic-help fallback. Scoped API/renderer/packaging checks pass; live-provider and installed-Desktop acceptance remain pending in PLAN-109.

• [x] Correct first-run Catlas setup in Desktop 0.2.10: read the selected provider/model catalogs before the first Admin session exists, then require authentication after setup. Isolated HTTP and browser checks cover both steps through account creation with auth enabled.

• [x] Ship shared provider onboarding and Settings in Desktop 0.2.9 unsigned preview, with Runtime 0.1.24, optional detection after Apply, scoped installation, retained results, and Windows/macOS/Linux helper updates. All release jobs passed; the public updater feed resolves 0.2.9 for all three release targets. See PLAN-107.

• [x] Save Runtime-owned provider selection before Desktop inventory and helpers; scope product provider/model choices by exact target and config revision. Explicit empty selection supports idle mode. Native installer acceptance remains tracked in the shared bootstrap rollout plan.

• [x] Bootstrap cats-platform/ from project-bootstrap

• [x] Establish cats-runtime as the only runtime boundary

• [x] Add a minimal Node/TypeScript HTTP entrypoint and smoke tests

• [x] Choose React/Vite as the initial renderer approach

• [x] Add the first multi-channel chat UI shell

• [x] Add initial file-backed chat-state persistence

• [x] Add local channel setup and persistence

• [x] Add basic runtime-backed channel operations

• [x] Add a global cat registry, chat assignment, mention routing, and transcript export

• [x] Separate cat identity and memory from provider-specific execution state

• [x] Add first-run /setup onboarding with optional Guide Cat setup, truthful selector states, and /lobby-first entry routing

• [x] Land chat session sleep/wake lifecycle, direct Cat chat defaults, stable room-routing / wake semantics, and room-header presence indicators

• [x] Land Cat-private room entry from My Cats plus Telegram binding markers without auto-persisting new direct rooms

• [x] Land transcript-adjacent operator approvals, progress, activity, and run inspection surfaces

• [x] Land a first Cats Work dashboard and project/work-item/task detail surface above shared core task/operator reads

• [x] Land machine-readable governance/workflow summaries for approval, delivery, budget, reroute, retry, and workflow continuation contracts

• [x] Land product-owned companion box storage, Cat-scoped ingest/read routes, and direct companion-session hydration contracts without visible UI changes

• [x] Land the first Electron desktop-host slice with app-managed readiness, local sidecar supervision, and bootstrap prerequisite checks

• [x] Land cross-layer packaged bootstrap diagnostics with product onboarding history, host/service logs, and an aggregated recovery chronology

• [x] Ship repo-owned self-hosted provider helpers for Unix host paths plus Windows WSL/Docker/check/upgrade operational surfaces without depending on environment-bootstrap at runtime

• [x] Land Cats-owned canonical memory records, retrieval context assembly, and memory flush seams without adding an external RAG dependency; curated cat/owner notes plus companion source mutations now sync into canonical retrieval, carry lineage-aware flush payloads, and replace stale hits

• [x] Land transcript-adjacent live event tapes in Chat and Code so recent progress, text, and tool milestones stay visible while runs are active

• [x] Land runtime-backed provider capability hints in selection surfaces so Cats can read stepwise text/tool/progress truth from cats-runtime

• [x] Land explicit provider capability bootstrap config so strong/weak startup treatment only comes from operator YAML rules, with Chat/Work/Code live Claude/Codex smoke verified under that fixture

• [x] Land runtime-backed live content blocks in Chat, Work, and Code so the typing indicator can render stable block snapshots instead of only a flat event list

• [ ] Add productization layers beyond the current Phase 2 chat core

Still Open

The current implementation has closed the main phase-2 product gaps, but several Phase 3 items remain:

• richer orchestrator automation beyond explicit @mention routing
• split-view chat surfaces for preview/debug context
• polling-first Telegram onboarding so bot-token setup does not require public ingress by default
• automatic resume after owner or incident decisions, richer live runtime state, and deeper converge/group planning beyond the current execution-loop and action seams
• richer first-run remediation polish, branded/signed release assets, and broader expert-only capability packs beyond the current Windows NSIS-first packaged setup baseline and the new repo-owned self-hosted helper surface
• offline transcript normalization and ingestion handoff hooks
• richer semantic indexing and archive export beyond the current local canonical-memory and retrieval substrate
• LINE entrypoints, richer Telegram room-rotation policy, and fuller desktop packaging beyond the current host slice

Quick Start

For the npm entrypoint, run npx @cats-inc/cats-platform. After readiness, an interactive terminal opens the application in the default browser and displays its URL. Press o to open it again, or q / Ctrl+C to stop gracefully. Use --no-open to skip the initial browser launch. Desktop, watch supervisors, CI, redirected terminals, and JSON/silent lifecycle output do not take over keyboard input or open browsers. See the CLI controls.

[!NOTE] Upgrading an existing local workspace? Review docs/release-notes.md for behavior changes and migration notes before running the setup commands below.

cd cats-platform
cp .env.example .env
npm install
npm run dev:server
# in a second terminal
npm run dev:web

Default endpoints:

• App API: http://127.0.0.1:8181
• Renderer dev server: http://127.0.0.1:5173
• Runtime dependency: http://127.0.0.1:3110

The chat shell persists local state, including created channels, global cats, channel cat assignments, execution targets, execution lease metadata, memory checkpoints, and transcripts, to ~/.cats/platform/state/chat-state.local.json. Override the platform storage root with CATS_PLATFORM_DIR when needed. When no explicit CATS_AUTH_SESSION_SECRET is configured, every executable platform entrypoint—including cats-platform, cats-one, local dev, and Desktop—generates a 256-bit secret at ~/.cats/platform/config/auth-session-secret.local and reuses it on restart. Set an explicit value only when multiple instances must share one secret or the platform config directory is ephemeral.

For a built run:

npm run build
npm start

The Node server will serve the built web UI from build/renderer/ when available.

For the desktop-host slice:

npm run desktop:start

That command builds build/server/, build/renderer/, and build/desktop/, then starts the Electron host that supervises local cats-runtime and cats-platform sidecars.

For host-package smoke validation, the local tarball path mirrors the published @cats-inc/cats-platform host package while using the installed command cats-platform. The separate one-shot bootstrap publication target is available as cats-one.

For staged packaging outputs:

npm run desktop:stage

That command keeps the self-hosted npm path intact while generating cross-platform packaging manifests under build/desktop-packaging/.

For a real Windows installer:

npm run desktop:package:windows
npm run desktop:package:windows -- --sidecar-layout bundle
npm run desktop:package:windows -- --sidecar-layout split

Those commands build cats-runtime, build cats-platform, and produce an NSIS installer under release/. --sidecar-layout bundle forces both sidecars into single-file bundles for the packaged app, while --sidecar-layout split keeps the original multi-file layout.

Managed skill content defaults to release, including unsigned local installers. The installer builder's --preview mode includes the three Cats development/practice skills; signing and release identity remain separate. For staging an explicit debug candidate after building the paired Runtime, use node scripts/package-desktop.mjs --content-profile preview. Normal staging physically excludes the supplement and replaces any prior preview stage. Both profiles retain ordinary Catlas/Orchestrator knowledge. See PLAN-109 for paired branch checkpoints and the required Runtime minor boundary.

For macOS/Linux unsigned or test packages:

npm run desktop:package:macos
npm run desktop:package:linux
node scripts/build-desktop-installer.mjs --target macos --arch x64 --format dmg --sidecar-layout split
node scripts/build-desktop-installer.mjs --target linux --arch arm64 --format deb --sidecar-layout bundle

For unpacked validation on Unix targets:

./scripts/macos/test-macos-package-smoke.sh
./scripts/linux/test-linux-package-smoke.sh

For a post-install validation pass on Windows:

.\scripts\windows\Test-WindowsInstallerSmoke.ps1

Documentation

See docs/ for project details:

• Requirements
• Architecture
• API
• Setup Guide
• Testing
• Contributing

Project Structure

cats-platform/
├── desktop/host/  # Desktop host bootstrap and supervision
├── src/app/       # Platform-level server and renderer assembly
├── src/products/  # Product slices such as Cats Chat
├── src/shared/    # Types shared by server and renderer
├── tests/         # Node built-in test runner coverage
├── docs/          # Product, API, architecture, and delivery docs
├── scripts/       # Cross-platform project automation scripts
├── config/        # Future app and orchestration config
└── assets/        # Future product assets

License

This project is licensed under the MIT License. See LICENSE.