VSCode Notebook CLI

🚀 Supercharge your Jupyter workflow with programmatic notebook control!

A powerful VSCode extension that provides a command-line interface for complete Jupyter notebook manipulation. Perfect for AI assistants, automation scripts, and power users who need programmatic control over their notebooks.

Why Use This?

🎯 For AI Assistants

• Execute cells and see results in real-time
• Inspect variables without manual intervention
• Debug code autonomously with temporary evaluations
• Truncate long outputs to save tokens

🔧 For Developers

• Automate notebook workflows from command line
• Batch execute cells with error handling
• Integrate notebooks into CI/CD pipelines
• Remote notebook control via SSH/API

🚀 Quick Start

# Install the extension
code --install-extension vscode-notebook-cli-0.1.0.vsix

# Reload VSCode and open a notebook
# Use the CLI from terminal:

node out/cli.js list-cells notebook.ipynb
node out/cli.js run notebook.ipynb 0
node out/cli.js inspect-var notebook.ipynb my_variable

📋 Core Commands

Cell Management

# List all cells with metadata
node out/cli.js list-cells notebook.ipynb

# Add new cells
node out/cli.js add-cell notebook.ipynb --source "print('Hello!')"
node out/cli.js add-cell notebook.ipynb --type markdown --source "# Header"

# Edit existing cells
node out/cli.js edit-cell notebook.ipynb 0 "new_code_here"

# Delete cells
node out/cli.js delete-cell notebook.ipynb 2

Cell Execution

# Execute single cell
node out/cli.js run notebook.ipynb 0

# Execute with output truncation
node out/cli.js run notebook.ipynb 0 --head 10
node out/cli.js run notebook.ipynb 0 --tail 5
node out/cli.js run notebook.ipynb 0 --lines 10-20

# Execute cell range
node out/cli.js run-range notebook.ipynb 0 5

Variable Inspection & Debugging

# Inspect specific variables
node out/cli.js inspect-var notebook.ipynb my_array

# Execute temporary debugging code
node out/cli.js eval notebook.ipynb "print(type(X), X.shape)"
node out/cli.js eval notebook.ipynb "print(locals().keys())"

# Get cell outputs
node out/cli.js output notebook.ipynb 0

Kernel Management

# Check notebook status
node out/cli.js status notebook.ipynb

# Restart kernel
node out/cli.js restart-kernel notebook.ipynb

🎨 Advanced Features

Output Truncation

Perfect for handling large outputs or saving tokens in AI workflows:

# Show first 10 lines only
node out/cli.js run notebook.ipynb 0 --head 10

# Show last 5 lines
node out/cli.js run notebook.ipynb 0 --tail 5

# Show specific line range
node out/cli.js run notebook.ipynb 0 --lines 20-30

Variable Inspection

Get detailed information about your variables:

{
  "name": "my_array",
  "type": "ndarray", 
  "value": "[1 2 3 4 5]",
  "shape": "(5,)",
  "dtype": "int64",
  "size": 5
}

Temporary Code Evaluation

Execute debugging code without creating permanent cells:

node out/cli.js eval notebook.ipynb "print(f'Data shape: {df.shape}')"

🤖 AI Assistant Integration

This extension transforms how AI assistants work with Jupyter notebooks:

Before: Limited to reading/editing static files
After: Full execution, debugging, and variable inspection

Example AI Workflow:

1. Analyze code: node out/cli.js list-cells notebook.ipynb
2. Execute cells: node out/cli.js run notebook.ipynb 0
3. Debug issues: node out/cli.js inspect-var notebook.ipynb problematic_var
4. Fix code: node out/cli.js edit-cell notebook.ipynb 0 "fixed_code"
5. Verify fix: node out/cli.js run notebook.ipynb 0 --head 5

📄 Output Format

All commands return structured JSON:

Success Response:

{
  "status": "success",
  "cell_id": "0",
  "execution_count": 5,
  "outputs": [...],
  "timing": {
    "started": "2024-01-01T10:00:00Z",
    "completed": "2024-01-01T10:00:01Z"
  }
}

Error Response:

{
  "status": "error",
  "error_type": "execution_error",
  "message": "NameError: name 'undefined_var' is not defined",
  "traceback": [...]
}

⚙️ Installation

Option 1: Direct Install

code --install-extension vscode-notebook-cli-0.1.0.vsix

Option 2: From Source

git clone <repository>
cd vscode-notebook-cli
npm install
npm run compile
vsce package
code --install-extension vscode-notebook-cli-0.1.0.vsix

📚 Documentation

• Complete CLI Reference - Comprehensive guide for AI assistants
• Quick Reference - Essential commands cheat sheet

🔧 Requirements

• VSCode ^1.80.0
• Jupyter Extension for VSCode
• Node.js (for CLI usage)

🏗️ Architecture

The extension consists of three main components:

1. VSCode Extension - Registers commands and manages Jupyter integration
2. HTTP Server - Handles CLI requests on localhost:3456
3. CLI Interface - Provides command-line access to all features

🤝 Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🌟 Why This Extension?

🤖 Created by Claude Code for Claude Code and fellow AI coding agents - Built to bridge the gap between AI assistants and Jupyter notebook execution.

🚀 Ready to revolutionize your notebook workflow? Install the extension and experience the power of programmatic Jupyter control!