clikernel gives an LLM agent a persistent Python or Luau session. Imports, variables, and results remain available between tool calls. An agent can create a kernel or attach to an existing one, including a user’s live solveit kernel, on a local or named remote gateway.
rustygate hosts the Jupyter kernels and provides their MCP tools. clikernel is the conversation-side router: the MCP host launches it over stdio, and it forwards requests to gateways over HTTP. It selects gateways from gateways.toml, supplies startup.py and inspectors.py to Python kernels it creates, and starts a private local gateway when needed. The default kernel is ipymini.
Kernel ownership determines what happens when the conversation ends:
autoclose, including the automatic kernel used by bare py or lua and kernels created with create’s default settings.use_kernel does not make that session responsible for closing the kernel.autoclose=false on a resident gateway can outlive the conversation. A later conversation can attach and continue using its state.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
Register the stdio server with your MCP host. For Claude Code:
claude mcp add clikernel -- clikernel-mcp
Use py(code=...) for Python/IPython or lua(code=...) for bundled Luau. Either starts its language’s kernel when none is current. There is one current kernel: a language mismatch errors without switching or running the code. IPython magics, including %%bash, are Python-only.
For a named kernel, use create(dlgname="work", language="luau"). Omit language to reuse an existing binding unchanged, or default a new kernel to Python. An explicit language must match an existing binding. The other tools are list_kernels, use_kernel, delete_kernel, restart, and interrupt; creation, selection, and listing report the language.
These tools forward to rustygate. list_kernels, use_kernel, and create also accept a host naming a gateway from gateways.toml. One MCP registration can therefore reach multiple machines. Replies retain the gateway’s text and image blocks. Python startup and inspectors run only in Python, never Luau, including after restart.
$CLIKERNEL_HOST overrides the default gateway URL, http://127.0.0.1:8787. If no gateway answers, clikernel uses a private child gateway for the conversation. The ownership rules above determine which kernels close at session end.
Pass --quiet, as in clikernel-mcp --quiet, to omit startup output from replies. Python startup code still runs.
Three optional files in $XDG_CONFIG_HOME/clikernel/ configure the router, usually under ~/.config/clikernel/:
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.inspectors.py installs Python cell inspectors after startup. Define inspect, a list named inspectors, or both. Each inspector runs once before a cell: a one-argument inspector takes the cell’s AST, and a two-argument inspector takes the AST and raw source. Return a string to print a note before the output. Raise the provided RuleBlock to block execution. Other exceptions produce a warning and allow the cell to run. See examples/inspectors.py.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
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:
. acknowledgement.-- 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.