Jupyter Notebook Edit: Inconsistent Cell Insertion Order Breaks Code Generation

[fonnesbeck]

Bug Description Claude code seems incapable of working with Jupyter notebooks. Cells are added in arbitrary/random order even when explicitly being told where to implement edits. This severely limits its use in data science applications.

Environment Info

• Platform: linux
• Terminal: ghostty
• Version: 1.0.68
• Feedback ID: 77af98cf-db0d-419a-b3ec-0a8ad4d2e248

[github-actions[bot]]

Found 3 possible duplicate issues:

1. https://github.com/anthropics/claude-code/issues/2925
2. https://github.com/anthropics/claude-code/issues/4613
3. https://github.com/anthropics/claude-code/issues/2176

If your issue is a duplicate, please close it and 👍 the existing issue instead.

🤖 Generated with Claude Code

[ObservedObserver]

You can try runcell which is a Jupyter AI Agent extension that uses claude.

[yn]

Yea, this is definitely an issue for me too. Hopefully the team fixes it soon. I found that this workaround works: put this into CLAUDE.md:

Technical Tool Guidelines

Jupyter Notebook Editing (NotebookEdit Tool)

Critical Known Issue

The NotebookEdit tool has a default insertion behavior that inserts new cells at the very top of the notebook when no cell_id is specified. This can create ordering problems and notebook structure issues.

Required Best Practices

1. Always Get Cell IDs First

   # Extract cell IDs from any notebook before editing
   cat notebook.ipynb | grep -E '"id": "[^"]*"'
   

2. Always Use cell_id Parameter

   • NEVER use NotebookEdit with edit_mode="insert" without specifying cell_id
   • ALWAYS target insertion after a specific existing cell
   • Use cell_id to control exact placement in notebook structure

3. Proper Insertion Pattern

   # CORRECT: Target specific cell for insertion
   NotebookEdit(
       notebook_path="path/to/notebook.ipynb",
       edit_mode="insert", 
       cell_id="existing_cell_id",  # Insert AFTER this cell
       cell_type="markdown",
       new_source="content"
   )
   
   # WRONG: No cell_id specified - will insert at top
   NotebookEdit(
       notebook_path="path/to/notebook.ipynb", 
       edit_mode="insert",  # This will go to the top!
       cell_type="markdown",
       new_source="content"
   )
   

4. Before Large Notebook Operations

   • Read file to understand structure and get cell IDs
   • Plan insertion sequence to avoid ordering issues
   • Test with single cell insertion first
   • Consider using fresh/clean notebooks for complex structures

Why This Matters

Incorrect cell insertion can create notebook structure problems that are difficult to fix, especially with large notebooks that exceed file size reading limits. Following these practices ensures precise control over notebook organization.

[ChengJiale150]

Why not try my Jupyter MCP Server jupyter-mcp-server ? It has these amazing features:

• 📚 Multi-Notebook Management: Simultaneously manipulate multiple Notebooks within a single CLI interaction session
• 🔁 Interactive Execution: Not only can it edit, but it can also execute! It can automatically adjust execution strategies based on cell outputs
• 📊 Multimodal Output: Fully leverage powerful multimodal capabilities! Supports outputting multimodal results such as text, images, tables, and more

Additionally, it supports connecting to multiple Jupyter servers simultaneously, whether local or remote! It supports one-click quick installation using uvx like this:

claude mcp add Jupyter-MCP-Server uvx better-jupyter-mcp-server

Come and give it a try!

[Wemmy0]

It does seem that Claude's understanding of the NotebookEdit tool is flawed. With Sonnet 4.5 Claude is often using cell IDs such as cell-20 rather than the correct ID 75513276 It seems switching to Opus fixes this and it can correctly edit the Notebook

[github-actions[bot]]

This issue has been inactive for 30 days. If the issue is still occurring, please comment to let us know. Otherwise, this issue will be automatically closed in 30 days for housekeeping purposes.