Terminal UI for Managing Multiple Processes with Sidebar UI

A Node.js wrapper for the Sideplex terminal application. This package provides a programmatic interface to launch and manage the multiplexer from Node.js applications, with TypeScript support and automatic binary management.

Features

• Easy Integration: Simple API for launching the multiplexer from Node.js
• Type-Safe: Full TypeScript support with comprehensive type definitions
• Binary Management: Automatically includes and manages the multiplexer binary
• Cross-Platform: Works on macOS, Linux, and Windows
• Flexible Configuration: Programmatic configuration or pass-through CLI arguments
• Lightweight: Zero dependencies, focused wrapper around the Go binary

Installation

npm install sideplex
# or
yarn add sideplex
# or
pnpm add sideplex

Quick Start

Using the CLI

After installation, you can use the sideplex command directly:

# Run with configuration file
npm exec sideplex --config config.json

# Run with inline commands
npm exec sideplex --cmd "npm run start:frontend" --cmd "npm run start:backend"

Programmatic Usage

import { startSideplex } from 'sideplex';

// Start with configuration
await startSideplex({
    panes: [
        {
            name: 'backend',
            title: '🚀 API Server',
            command: ['npm', 'run', 'dev'],
            cwd: './backend',
            autostart: true,
            env: {
                PORT: '8080',
                NODE_ENV: 'development',
            },
        },
        {
            name: 'frontend',
            title: '⚡ Web UI',
            command: ['npm', 'run', 'dev'],
            cwd: './frontend',
            autostart: true,
        },
    ],
});

API

startSideplex(config?, binaryPath?)

Starts a new multiplexer instance with the given configuration.

Parameters:

• config (optional): Configuration object specifying panes and options
• binaryPath (optional): Custom path to the multiplexer binary

Returns: Promise<ExecutionResult> - Resolves when the multiplexer exits

Example:

const result = await startSideplex({
    panes: [
        {
            name: 'server',
            command: ['node', 'server.js'],
            title: 'Server',
            cwd: './app',
            autostart: true,
            killable: false,
        },
    ],
});

console.log(`Multiplexer exited with code: ${result.code}`);

Types

Config

Configuration object for initializing the multiplexer.

interface Config {
    panes: PaneConfig[];
}

PaneConfig

Configuration for a single pane/command.

interface PaneConfig {
    /** Unique identifier for the pane */
    name: string;

    /** Command and arguments to execute */
    command: string[];

    /** Optional display title (defaults to name) */
    title?: string;

    /** Optional working directory */
    cwd?: string;

    /** Optional environment variables */
    env?: Record<string, string>;

    /** Whether to start automatically (default: true) */
    autostart?: boolean;

    /** Whether the command can be killed (default: true) */
    killable?: boolean;
}

ExecutionResult

Result of executing the multiplexer process.

interface ExecutionResult {
    /** Exit code, or null if terminated by signal */
    code: number | null;

    /** Signal that terminated the process, or null */
    signal: NodeJS.Signals | null;
}

Keyboard Shortcuts

When running the multiplexer:

• j/k or ↓/↑: Navigate between panes
• Enter: Focus on the selected pane
• Ctrl+Z: Return to the sidebar from a focused pane
• Ctrl+U/D: Scroll up/down
• x: Kill the selected command
• Ctrl+C: Exit the multiplexer

Requirements

• Node.js >= 14.0.0

Related

• CLI Multiplexer - The underlying Go application

License

MIT