cg-jupyter-mux

A command-line tool that acts as a multiplexer for the Jupyter kernel protocol. It communicates with a specified Jupyter kernel, reading JSON Lines messages from standard input and writing JSON Lines messages (from selected channels) to standard output.

This tool allows programmatic interaction with Jupyter kernels using a simple stdin/stdout interface, suitable for integration into other tools or automated workflows.

Features

• Starts Jupyter Kernels: Launches a kernel specified by name (e.g., python3, bash).
• JSON Lines Interface: Reads input messages and writes output messages using the JSON Lines format (one valid JSON object per line).
• Async I/O: Uses asyncio for non-blocking communication with the kernel and stdin/stdout.
• Input Routing: Automatically routes incoming messages from stdin to the appropriate kernel channel (shell or stdin) based on the message's header.msg_type.
• Filtered Output: Forwards messages received from the kernel's iopub (broadcast) and stdin (input requests/replies) channels to stdout. Messages from the shell channel (direct replies) are intentionally not written to stdout.
• Graceful Shutdown: Handles Ctrl+C and EOF on stdin to attempt a clean shutdown of the kernel.
• Configurable Verbosity: Use -v for detailed debug logging to stderr.

Usage

Command

cg-jupyter-mux [-v] <kernel_name>

• <kernel_name> (Required): The name of the installed Jupyter kernel spec to start (e.g., python3). Run jupyter kernelspec list to see available kernel names.
• -v, --verbose (Optional): Enable verbose debug logging, printed to stderr.

Input Format (stdin)

The tool expects JSON Lines on standard input. Each line must be a single, complete, valid JSON object representing a Jupyter protocol message.

• Structure: Standard Jupyter message format (dictionary with header, parent_header, metadata, content, buffers).
• Routing: The tool inspects the header.msg_type field to decide which kernel channel (shell or stdin) to send the message to. Common types include:
  • Sent to shell channel: execute_request, kernel_info_request, inspect_request, complete_request, shutdown_request, comm_open, comm_msg, comm_close, etc.
  • Sent to stdin channel: input_reply

Example Input Line (execute_request):

{"header": {"msg_id": "exec-abc-123", "username": "cli_user", "session": "session-xyz-789", "date": "2025-04-07T23:40:00Z", "msg_type": "execute_request", "version": "5.3"}, "parent_header": {}, "metadata": {}, "content": {"code": "print('Hello Kernel!')\nresult=1+2\nresult", "silent": false, "store_history": true, "user_expressions": {}, "allow_stdin": false}, "buffers": []}

Output Format (stdout)

The tool produces JSON Lines on standard output. Each line is a single, complete, valid JSON object representing a message received from the kernel.

• Source Channels: Only messages from the kernel's iopub channel (status updates, execution results, output streams, display data, errors) and stdin channel (input requests like input_request) are output.
• Filtered Channels: Messages received by the client on the shell channel (e.g., execute_reply, kernel_info_reply) are not printed to stdout.
• Date Format: datetime objects within messages (like header.date) are serialized to ISO 8601 strings.

Example Output Line (stream message from iopub):

{"header": {"msg_id": "...", "username": "kernel", "session": "session-xyz-789", "date": "2025-04-07T23:40:01.123456Z", "msg_type": "stream", "version": "5.3"}, "parent_header": {"msg_id": "exec-abc-123", ...}, "metadata": {}, "content": {"name": "stdout", "text": "Hello Kernel!\n"}, "buffers": [], "channel": "iopub"}

Example Output Line (execute_result message from iopub):

{"header": {"msg_id": "...", "username": "kernel", "session": "session-xyz-789", "date": "2025-04-07T23:40:01.234567Z", "msg_type": "execute_result", "version": "5.3"}, "parent_header": {"msg_id": "exec-abc-123", ...}, "metadata": {}, "content": {"data": {"text/plain": "3"}, "execution_count": 1}, "buffers": [], "channel": "iopub"}

Stopping the Multiplexer

• EOF: Close the standard input stream that's piping data to cg-jupyter-mux. The tool will detect EOF and initiate a graceful shutdown.
• Ctrl+C: Send an interrupt signal (SIGINT). The tool traps this and initiates a graceful shutdown.

Troubleshooting

• jupyter_client.kernelspec.NoSuchKernel: No such kernel named <name>: Ensure the required kernel package (e.g., ipykernel for python3) is installed in the same Python environment where cg-jupyter-mux is run. Verify using jupyter kernelspec list. See Installation section.
• JSON Decode Errors: Input must be strictly one valid JSON object per line. Check for syntax errors or multi-line objects.

License

This project is licensed under the MIT License. See the LICENSE file (if present) or the license field in pyproject.toml for details.