Metadata-Version: 2.4
Name: nblean
Version: 0.1.0
Summary: Token-lean Jupyter notebook access for coding agents: outlines, clipped outputs, lazy images, a persistent kernel.
Keywords: jupyter,notebook,ipynb,llm,coding-agent,claude-code,tokens,cli
Author: Recep Kaan Karaman
Author-email: Recep Kaan Karaman <kaanrkaraman@gmail.com>
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Framework :: Jupyter
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Software Development
Classifier: Typing :: Typed
Requires-Dist: jupyter-client>=8.10.0
Requires-Python: >=3.13
Project-URL: Homepage, https://github.com/kaanrkaraman/nblean
Project-URL: Repository, https://github.com/kaanrkaraman/nblean
Project-URL: Issues, https://github.com/kaanrkaraman/nblean/issues
Description-Content-Type: text/markdown

<p align="center">
  <strong>nblean</strong><br>
  <strong>Lets coding agents work with Jupyter notebooks without reading every output</strong>
</p>

<p align="center">
  <a href="https://github.com/kaanrkaraman/nblean/actions/workflows/ci.yml"><img src="https://github.com/kaanrkaraman/nblean/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
  <a href="https://pypi.org/project/nblean/"><img src="https://img.shields.io/pypi/v/nblean" alt="PyPI"></a>
  <a href="https://pypi.org/project/nblean/"><img src="https://img.shields.io/pypi/pyversions/nblean" alt="Python"></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License: MIT"></a>
</p>

<p align="center">
  <a href="#installation">Install</a> &bull;
  <a href="#quick-start">Quick Start</a> &bull;
  <a href="#commands">Commands</a> &bull;
  <a href="#how-savings-work">Benchmarks</a> &bull;
  <a href="#supported-agents">Agents</a>
</p>

---

An `.ipynb` file holds code plus everything the code printed: DataFrame dumps,
progress bars, tracebacks, and plots stored as base64 images. An agent that opens one
reads all of it. To fix one cell, it then runs the whole notebook again and reads the
result again.

nblean is a small CLI and agent skill that lets the agent work one cell at a time. It
lists the notebook as an outline, opens only the cells asked for, clips their outputs,
and runs cells in a background kernel that stays alive between commands.

## What nblean Does

| Agent needs to | Without nblean | With nblean |
|---|---|---|
| See what a notebook contains | Reads the whole JSON, outputs included | `outline`: one line per cell, with an output summary like `→ 14L img ERR KeyError` |
| Look at a few cells | Writes a one-off `json`/`jq` script | `show 12 15-18`: source, plus outputs clipped to the first and last lines |
| Find code | Greps JSON-escaped strings | `grep`: matches by cell and line number |
| Debug | Scrolls through ANSI-colored tracebacks full of library frames | `errors`: only the failing cells, showing your frame and the exception |
| Edit a cell | Rewrites the JSON, or reads the notebook first | `set` / `add` / `rm`, with the new source passed on stdin |
| Re-run after a fix | Runs the whole notebook again and reads all the output | `run 12`: runs that cell in a kernel that is still alive, prints only its output, and saves it into the notebook |
| Check a value | Adds a throwaway `print` cell | `eval 'df.dtypes'`: runs the code in the kernel without changing the notebook |
| Look at plots | Every plot costs image tokens | Plots are saved as files and only their paths are printed; the agent opens one when it needs to |

## How Savings Work

nblean cuts **notebook tokens**, which are only part of an agent's bill. Every session
also pays for the system prompt, tool definitions, and conversation history. These
fixed costs come to about 28k tokens per session on Claude Code. Savings grow with the
size of the notebook and the volume of its outputs.

### A/B test in Claude Code

Claude Sonnet ran headless (`claude -p`), two times with the nblean skill and two
times without it. Token counts
come from the `usage` that Claude Code reports; costs are what the same usage would
cost at API prices.

| Task | Without nblean | With nblean | Change |
|---|---:|---:|---:|
| Answer two questions from the saved outputs of a 7 MB EDA notebook (97 cells, 31 plots) | 236k tokens · $0.207 | 172k tokens · $0.160 | **-27% tokens, -23% cost** |
| Find and fix a bug in a 124 KB notebook, then re-run it until clean | 183k tokens · $0.153 | 183k tokens · $0.150 | no measurable change |

The first version of nblean showed execution counts in the outline, and one run
reported them as cell indices. The numbers above come from runs after that fix, and
all of them answered correctly. Every fix run ended with a clean notebook. On the
small notebook the baseline agent already worked efficiently: it ran `nbconvert` and
grepped for errors, so nblean had little to remove.

### First look

This compares the `outline` output with reading the whole notebook,
counting text as bytes/4 and images by pixel area. It is an upper bound on what the
first step saves.

| Notebook | Whole notebook | `nblean outline` |
|---|---:|---:|
| Flight-data EDA, 97 cells, 31 plots | ~81k | ~1.5k |
| Data preprocessing | ~58k | ~260 |
| Kaggle training run | ~29k | ~90 |

## Installation

```bash
uv tool install nblean        # or: pipx install nblean
nblean --help
```

You can also run it without installing: `uvx nblean outline nb.ipynb`.

The kernel runs in the notebook's own environment, not in nblean's. nblean picks the
nearest `.venv` above the notebook, which needs `ipykernel` installed
(`uv add --dev ipykernel`). Use `--python PATH` to pick a different interpreter.

## Quick Start

```bash
# 1. Install the skill for your agent
nblean init                         # Claude Code (default)
nblean init --agent codex           # Codex
nblean init --agent opencode        # OpenCode
nblean init --agent gemini          # Gemini CLI
nblean init --agent all             # all of the above
nblean init --project               # into ./ instead of ~/

# 2. Ask your agent anything about a notebook
```

The skill tells the agent to start with `outline` and never to read the `.ipynb`
directly.

## How It Works

```
  Without nblean:                              With nblean:

  agent --read--> nb.ipynb                     agent --outline/show--> nblean --> nb.ipynb
    ^                 |                          ^                       |  clip, summarize,
    |  every source,  |                          |  only requested       |  images to files
    |  output, image  |                          |  cells, clipped       |
    +-----------------+                          +-----------------------+
                                                 agent --run 12--> nblean --> live kernel
                                                                     |  only this cell's output,
                                                                     |  saved back into nb.ipynb
```

The kernel is a detached `ipykernel` process. Each notebook gets its own kernel, and
each nblean call connects to it, runs code, and disconnects. Variables stay in memory
between calls until `kernel stop` or `kernel restart`.

## Commands

CELL is an index (`12`), a range (`3-7`, `5-`), `all`, or the start of a cell id.

### Read

```bash
nblean outline nb.ipynb                       # one line per cell
nblean show nb.ipynb 12 15-18                 # source + clipped outputs
nblean show nb.ipynb 12 --no-output           # source only
nblean show nb.ipynb 12 --lines 60            # bigger clip; --full disables it
nblean grep nb.ipynb 'read_csv'               # search sources; -o includes outputs
nblean errors nb.ipynb                        # failing cells only
```

### Edit

```bash
nblean set nb.ipynb 12 <<'PY'                 # replace source, clears stale outputs
df = pd.read_parquet(path)
PY
nblean add nb.ipynb --at 13 <<'PY'            # insert; --md for markdown
df.describe()
PY
nblean rm nb.ipynb 14 20-22
```

### Execute

```bash
nblean run nb.ipynb 0-12                      # run cells, save outputs, stop at first error
nblean eval nb.ipynb 'df.shape'               # scratch code, nothing saved
nblean kernel nb.ipynb status|stop|restart
```

## Examples

```
$ nblean outline eda.ipynb
eda.ipynb: 97 cells (36 markdown, 61 code), kernel off
  0 md    1. Files and Schema +14L
  1 code  import itertools +27L
  3 code  files = pl.DataFrame( +5L  → 13L
 13 code  p0 = pl.read_parquet(PARQ / "part.0.parquet") +7L  → 1L img
 15 code  fl_min = feat["flight_length"].to_numpy() / 60 +19L  → img
```

A 40-line pandas traceback, cut down to the line that failed:

```
$ nblean errors buggy.ipynb
── 8 code id=cell08 exec=3 ──
KeyError                                  Traceback (most recent call last)
Cell In[3], line 1
----> 1 df["pressure_kpa"] = df["presure"] * 6.89476
      2 df.head()

… 11 library or chained frames omitted …
KeyError: 'presure'
```

A 300-line training log, with a plot that is saved to a file instead of loaded:

```
$ nblean run buggy.ipynb 3 4 --lines 6
── 3 code id=cell03 exec=4 ──
epoch 000 smoothing pass loss=1.000000 temp_mean=141.845
epoch 001 smoothing pass loss=0.500000 temp_mean=141.724
epoch 002 smoothing pass loss=0.333333 temp_mean=141.651
… 294 lines omitted …
epoch 297 smoothing pass loss=0.003356 temp_mean=139.027
epoch 298 smoothing pass loss=0.003344 temp_mean=139.038
epoch 299 smoothing pass loss=0.003333 temp_mean=139.048
── 4 code id=cell04 exec=5 ──
[image/png → /tmp/nblean/buggy-ec4a859a6390/img/4_0.png]
```

## Supported Agents

The skill uses the [Agent Skills](https://agentskills.io) `SKILL.md` format, so the
same file works in every agent below. The CLI works with any agent that can run shell
commands.

| Agent | `nblean init` | Skill location |
|---|---|---|
| Claude Code | `--agent claude`, or the plugin below | `~/.claude/skills/nblean` |
| Codex | `--agent codex` | `~/.agents/skills/nblean` |
| OpenCode | `--agent opencode` | `~/.agents/skills/nblean` |
| Gemini CLI | `--agent gemini` | `~/.gemini/skills/nblean` |
| Others | `npx skills add kaanrkaraman/nblean` | per agent |

In Claude Code the skill is also available as a plugin:

```
/plugin marketplace add kaanrkaraman/nblean
/plugin install nblean@nblean
```

nblean ships as a CLI and a skill instead of an MCP server. An MCP server's tool
definitions are loaded into every session. A skill is loaded only when a notebook
comes up.

## Platform Support

macOS, Linux, and Windows, on Python 3.13+. The kernel's Python can be any version
that `ipykernel` supports.

## Limitations

- A cell's outputs are written when the cell finishes. If a long cell is killed, its output is lost.
- Writes are atomic but not merged. If the notebook is open in Jupyter or VS Code, reload it there after nblean writes.
- Widgets, `update_display_data`, and `input()` are not supported.

## Contributing

```bash
uv sync
uv run pytest
uv run ruff check . && uv run mypy
```

## License

[MIT](LICENSE)
