Use a Notebook Instead of python3 -c
When nteract notebook tools are available and you're about to do multi-step Python work — chaining python3 -c commands, writing a throwaway .py script, or running exploratory code — use a notebook-backed REPL instead. You get persistent state between cells, rich output (tables, plots, errors with tracebacks), and users and agents can view the notebook in realtime.
Prefer the direct pi tools when present:
python— execute code in the persistent notebook session.python_add_dependencies— batch-add packages and hot-sync the environment.python_save_notebook— save the backing notebook.
If only MCP tools are available, use create_notebook, create_cell, execute_cell, set_cell, and get_all_cells.
If the notebook tools aren't appearing
If you loaded this skill but neither the direct pi tools (python, python_add_dependencies) nor the MCP notebook tools are available, don't fall back to python3 -c. Ask the user to verify that the nteract plugin is installed and enabled in Codex, then restart Codex after any plugin or marketplace changes. The most common cause is that the plugin was installed or updated after the current Codex session started.
If Codex reports the plugin is installed but the tools still do not appear, ask the user to refresh and reinstall the selected plugin to clear stale local cache state:
codex plugin marketplace upgrade nteract-plugins
codex plugin remove nteract@nteract-plugins # or nightly@nteract-plugins
codex plugin add nteract@nteract-plugins # or nightly@nteract-plugins
codex mcp list
Start a new Codex session after reinstalling; running sessions do not hot-load newly installed MCP tools.
If tools still don't appear after restarting Codex:
- Confirm the nteract desktop app/daemon is running.
- Run
nteract doctorto check the installation (nteract --channel nightly doctorfor the Nightly install). - Share any error messages from the session.
Quick Start (direct pi tools)
python({
"code": "import numpy as np\nnp.arange(3)",
"dependencies": ["numpy"]
})
Pass dependencies on the first python call when imports may be missing. The pi REPL records them before kernel startup when possible; later dependency additions use hot-sync.
Quick Start (MCP tools)
create_notebook(dependencies=["numpy"])
create_cell(source="import numpy as np\nnp.arange(3)", cell_type="code", and_run=true)
Core Workflow
Start or reuse a notebook-backed REPL:
- Direct: call
python(...); the session is created lazily and state persists. - MCP: call
create_notebook(...)orconnect_notebook(...).
- Direct: call
Declare dependencies before import-heavy code:
- Direct: pass
dependenciestopythonor callpython_add_dependencies. - MCP: pass
dependenciestocreate_notebookor usemanage_dependencies.
- Direct: pass
Run and iterate:
- Direct: call
pythonrepeatedly; variables/imports persist. - MCP: edit with
set_cell(...)and rerun withexecute_cell(...).
- Direct: call
Check your work:
- Direct: inspect returned text/images/tables.
- MCP:
get_all_cells(format="summary", include_outputs=true).
Save when done:
python_save_notebook(...)orsave_notebook(...).Open the app for the user:
show_notebook()when they ask to see it. This can be disruptive if unexpected.
When to Use This
- Exploring a dataset (load, filter, plot, iterate)
- Running multi-step computations where later steps depend on earlier results
- Generating visualizations (matplotlib, plotly, altair)
- Prototyping code that you'll refine over several iterations
- Any task where you'd otherwise chain 3+
python3 -ccommands
When NOT to Use This
- One-shot commands (
python3 -c "print(2+2)"is fine as-is) - Running existing scripts (
python3 script.py) - Non-Python tasks
