clikernel

clikernel gives LLM agents persistent kernel sessions over MCP or a plain stream protocol. Imports, variables, and results remain available between calls. Agents can create kernels or attach to existing ones, including a user’s live solveit kernel.

rustygate hosts the kernels. Clikernel routes requests to local or named remote gateways and supplies startup code to Python kernels.

New kernels close with their creating conversation by default. Attaching to an existing kernel does not claim ownership. Use autoclose=false on a persistent gateway to keep a new kernel for later conversations. See core for configuration and lifecycle details.

Install

pip install clikernel

This installs rustygate and ipymini. No service setup is required for a conversation-local kernel: clikernel starts a private gateway if it cannot find one. To retain kernels across conversations, run a resident gateway, for example through launchd or systemd:

rustygate --port 8787

Use with an MCP host

Register the stdio server with your MCP host. For Claude Code:

claude mcp add clikernel -- clikernel-mcp

Choose a kernel, then execute code:

create(kernel="py")
exec(code="6*7")

Use kernel="luau" for bundled Luau, or kernel="bpl" for BPL when basedpl is installed in the gateway’s environment. create accepts any kernelspec the gateway finds. In the main conversation, exec never creates or switches kernels. See MCP for named gateways, dialog bindings, and other tools.

In Claude Code, subagents share the current kernel unless clikernel-hook is registered as a PreToolUse hook. With the hook, each subagent’s first exec creates a kernel of its own. See Subagent kernels for the settings entry.

The router checks each exec cell against built-in rules for mistakes agents often make with this toolkit. Most rules add a note to the reply, and --quiet leaves the notes out. Two rules always block the cell: shell access through subprocess, os.system or os.popen, and changes to sys.path.

Configuration

Two optional files in $XDG_CONFIG_HOME/clikernel/ configure the router, usually under ~/.config/clikernel/, or under the directory clikernel-mcp --cfgdir names:

• startup.py runs in each Python kernel clikernel creates, with __file__ set to its path. Its output appears in the reply announcing the kernel unless --quiet is set.
• gateways.toml names remote gateways and configures authentication without putting tokens in tool arguments:

[gateways.solveit]
url = "https://solveit.example.com/gate"
token_env = "SOLVEIT_TOKEN"
verify = false   # optional: accept a self-signed certificate

The stream protocol

Run clikernel as a plain CLI process for clients that read a text stream rather than MCP messages. It uses a delimiter-framed stdin/stdout protocol:

• Input is not echoed.
• Each request gets a . acknowledgement.
• A per-process random delimiter marks the end of each response.
• Multiline cells are framed by -- and the delimiter.

The startup banner supplies the protocol instructions and delimiter. Running clikernel without arguments creates a kernel and stops it on exit. --kernel <id> attaches to an existing kernel and leaves it running on exit.