Skip to content

Docs: Add comprehensive Cmux documentation (features, settings, local vs cloud) #851

@notkainoa

Description

@notkainoa

Is your feature request related to a problem? Please describe.
It’s hard to discover and understand Cmux’s full functionality without a single, organized docs page. New and existing users need a clear reference for features, settings, and workflows, plus guidance. For example I have no idea what cloud mode is and what the difference is from local mode, or how it works.

Describe the solution you'd like
A dedicated, structured documentation site or page covering:

  • Overview: What Cmux is, key use cases, supported platforms.
  • Quick Start:
    • Local Mode: install, init, start, environment requirements.
    • Cloud Mode: account setup, auth, regions, quotas.
  • Core Features:
    • Multiplexing behavior and routing
    • Session management
    • Models, tools, and connectors supported
    • Project/workspace structure
    • CLI commands and flags
  • Configuration & Settings:
    • Global config (paths, env vars)
    • Per-project config
    • Logging, telemetry, and privacy controls
    • Resource limits and performance tuning
  • Local vs Cloud mode:
    • Feature parity matrix
    • Data flow diagrams
    • Persistence, caching, and storage differences
    • Security considerations (keys, secrets, isolation)
    • Pricing/limits (if applicable) and recommended use cases
  • Integrations:
    • Git, package managers, and build systems
    • Model providers and API keys
    • Webhooks and event emitters
  • Troubleshooting:
    • Common errors and fixes (e.g., “git is missing”, EventEmitter memory leak, lingering processes after ctrl‑C)
    • Diagnostic commands and logs
  • Guides & Recipes:
    • Example setups for local dev
    • Example cloud deployments
    • Custom models and extensions
  • Reference:
    • CLI command reference with examples
    • Config schema
    • API endpoints (if public)
  • Versioning & Changelog:
    • How docs map to releases
    • Known issues and deprecations

Describe alternatives you've considered

  • Scattered README sections and issue threads: helpful but incomplete and hard to navigate.
  • Inline comments in code: good for contributors, not ideal for users.

Additional context

  • Users are currently opening issues about missing git, memory leaks, and process persistence. A Troubleshooting section with known problems and steps would reduce repeat reports.
  • A feature parity table for local vs cloud mode would help users choose the right setup quickly.
  • Suggest hosting: docs/ in repo plus a generated site (using something like Docusaurus) to enable search, versioning, and deep links.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions