---
name: notebook-edit
description: Edit Jupyter notebook cells: read, modify, insert, delete, and execute code cells
---

## When to use
Use when the user asks to:
- Modify code in a Jupyter notebook (.ipynb)
- Add new cells (code, markdown, raw)
- Delete or reorder cells
- Update cell outputs
- Execute notebook cells (if kernel available)
- Convert notebooks to other formats

## Workflow

### 1. Locate the notebook
Find the .ipynb file path.

### 2. Read notebook structure
```bash
read notebook.ipynb
```
This returns the raw JSON structure of the notebook with cells, sources, outputs, metadata. You'll need to parse this JSON manually.

### 3. Make edits
Use `edit` tool to modify the notebook JSON directly:
- Edit `cells[*].source` to change code/markdown content
- Edit `cells[*].cell_type` to change type ("code", "markdown")
- Insert/delete by modifying the `cells` array
- Be careful with JSON structure — validate after edits

### 4. Execute cells (optional)
OpenClaw does not have a built-in `notebook_execute` tool. If you need to execute notebooks, either:
- Use `exec` to run `jupyter nbconvert --execute notebook.ipynb`
- Or manually run the code cells section by section using `code_execution`

### 5. Save changes
Edits are saved automatically upon tool completion, or explicitly write.

## Cell Types
- **code**: Executable Python/R/Julia code
- **markdown**: Documentation with Markdown formatting
- **raw**: Unformatted text (rarely used)

## Common Operations

### Add a code cell at the end
```bash
notebook_edit notebook.ipynb \
  --insert "end" \
  --cell-type code \
  --source "print('Hello')"
```

### Update existing cell
```bash
notebook_edit notebook.ipynb \
  --cell-index 3 \
  --source "x = 5\nprint(x*2)"
```

### Delete a cell
```bash
notebook_edit notebook.ipynb \
  --cell-index 2 \
  --delete true
```

### Run all cells
```bash
notebook_execute notebook.ipynb --all
```

### Clear outputs
```bash
notebook_edit notebook.ipynb --clear-outputs true
```

## Safety Rules
- **Backup first**: Copy notebook before major edits
- **Don't overwrite outputs** unless explicitly asked
- **Preserve cell metadata**: Some notebooks rely on custom metadata
- **Kernel restarts**: Changes to imports/functions may require kernel restart

## Examples

<Good>
User: "Thêm cell tính trung bình vào notebook analysis.ipynb"
Assistant:
1. Đọc notebook hiện tại
2. Tìm vị trí phù hợp (sau phần data loading)
3. Thêm code cell với formulas đúng
4. Kiểm tra syntax trước khi lưu
</Good>

<Bad>
Sửa cell mà không xem nội dung gốc, có thể mất code quan trọng.
</Bad>

## Error Handling
- **Invalid cell index**: Check notebook length first
- **JSON parse error**: Notebook có thể bị corrupt, backup và repair
- **Kernel not available**: Execution sẽ fail, chỉ edit được code

## Verification Checklist
- [ ] Notebook file is valid JSON
- [ ] Cell indices are within bounds
- [ ] Code syntax is correct (consider linting)
- [ ] No orphaned outputs (clear if needed)
- [ ] Notebook can still open in Jupyter after edit