Cheetah
Cheetah is a framework for applications that coordinate work across server-side code and connected client environments. A client may be a browser extension, a console process, a cooperative web page, or another runtime that implements the same protocol. Several clients can belong to one user, run on different computers, and contribute to one application.
This is useful when the application can decide what should happen on a server, but the work itself belongs somewhere else. A browser may hold a signed-in page that the server cannot reproduce. A console process may have access to local files or tools. A page may expose a small, deliberately cooperative part of its interface. Cheetah gives these environments a common way to identify themselves, advertise actions, receive work, apply local authority, and return evidence.
The framework does not define the product's business workflow. Product code still decides which actions matter, which client should receive them, how returned data is interpreted, and what to do when an external effect is uncertain. Cheetah supplies the distributed coordination underneath those decisions.
The figure shows responsibilities, not a required deployment topology. The server roles can share one process, and an application uses only the client types and optional facilities it needs.
Why connected clients need their own model
An ordinary request-response design works best when the application controls both ends for the duration of the request. Connected client environments do not behave that way.
A browser can suspend an extension service worker while its tabs remain open. The user can close or navigate a page. A laptop can sleep. A network connection can disappear after an action begins but before its result returns. A replacement runtime may represent the same browser installation without retaining the old process's memory. The browser also remains under local control: a server being allowed to request an action does not automatically give it permission to inspect a page or change a device.
Cheetah does not remove this volatility. It makes the important distinctions explicit:
- a stable client installation is different from its current running instance;
- a live connection is a route, not an identity or proof of completion;
- central policy and client-local authority are separate decisions;
- delivery, client acknowledgement, handler execution, and returned evidence are different stages;
- a timeout ends one wait, but does not prove that no external effect occurred;
- current platform state, retained messages, and product business state have different owners and recovery rules.
These distinctions let an application reason about interruptions without pretending that a browser or network is transactional.
The system in one pass
Product code uses Cheetah through the application-facing App role. It can inspect client presence, send a named command, wait for a terminal outcome, read retained responses, and use selected higher-level facilities. The product does not need to find the process that owns a client's socket.
The WebSocket role owns live client connections. It authenticates connection setup, registers the client's current route and runtime instance, sends remote commands, accepts delivery acknowledgements, and handles replacement or disconnect.
Returned progress, results, errors, events, and state use a separate path. They enter through the host application's authenticated HTTP edge and are handled by Cheetah's REST role. This role validates and fences incoming data, coordinates deduplication and history, and can wake or resolve application code waiting for an outcome.
Behind these roles, interfaces separate responsibilities such as authentication, registry, dispatch, correlation, notification, history, tracing, topology, and resource quota. Cheetah supplies compatible in-memory and Redis-backed implementation families, plus presets that assemble common compositions. Applications can replace individual responsibilities, provided the replacement preserves the contracts expected by the surrounding components.
On the client side, @cheetah/core supplies the shared runtime model: identity, protocol negotiation, action registration, validation, authority composition, optional approval, leases and cooperative cancellation, progress, terminal outcomes, state reporting, and telemetry hooks. Platform packages add the capabilities and constraints of the real environment. The browser package understands extension lifetimes, tabs, windows, content scripts, capture, and parsing. The console package adds files, processes, flows, downloads, and modules. The web package cooperates from inside a page. Mobile/native integration is an experimental bridge rather than an equally mature client surface.
Starting small and changing the topology later
The same action and client model can be used at several scales. Local execution can exercise the real client dispatch and policy pipeline without a remote Cheetah server. A small remote application can put the App, WebSocket, and REST roles in one process with in-memory components. When the workload requires separate role processes or horizontal capacity, Redis-backed components can coordinate routes, durable logical-client command mailboxes, correlation metadata, notifications, histories, and other shared responsibilities.
The distributed composition adds operational work. Redis availability and persistence, node identity, shared payload storage, routing, version rollout, observability, shutdown, backups, and incident response remain real concerns. Cheetah keeps the application vocabulary stable while the deployment grows; it does not claim that distribution becomes free.
Core path and optional facilities
The command and returned-data path does not require every Cheetah feature. Applications can adopt additional facilities where they solve a real need, including tracing and diagnostics, operator dashboards, reusable UI components, browser capture and structured parsing, worker/context coordination, retained response collection and derived views, Local Mode, and cooperative site or local-site relay features.
These facilities share Cheetah's identities and contracts, but they are opt-in and have different maturity and operating requirements. Their presence in the repository does not mean that every application has enabled them or that all are equally suitable for a production deployment.
The structured components also make Cheetah systems easier for coding agents to inspect and assemble than an application built from unrelated message handlers. That is a useful architectural property and part of the project's direction. It is not a promise that a safe, operated ecosystem can be generated automatically from a short prompt.
Responsibilities that remain outside Cheetah
Cheetah is embedded in an application and deployment owned by somebody else. The product and host remain responsible for domain authorization, business state, external-effect idempotency or reconciliation, TLS and route exposure, real identity integration, secrets, edge rate limiting, sensitive-operation auditing, backups, monitoring policy, and incident response.
The framework contains resource-quota support in Redis command admission and also defines rate-limiter and audit-logger interfaces. Ordinary node execution does not automatically invoke the latter two. A production-oriented preset rejects selected unsafe choices; it is still a starting composition rather than a hosted control plane.
Choose the next path
If you want to run the smallest complete exchange, continue to Get started. It prepares the core checkout, runs a real console client, verifies the retained result, and then shows how that proof grows into a larger application.
If you want the model before the commands, continue to Understand Cheetah. It develops responsibilities first, then client environments, the command and returned-data journey, and recovery under uncertainty.
Use Build and extend when you are ready to compose server roles or register client actions. Use Operate for security, scaling, diagnostics, recovery, and lifecycle. The Examples show the maintained development systems, while the Reference collects the exact APIs, protocol, actions, and current limits.