shidoshi

shidoshi is a local notebook for iterative work with LLMs and coding agents. You write Python, bash, notes and prompts in one notebook, and the notebook itself, in order, is the conversation: your code, its output and your notes are the context a prompt sees. Nothing runs or changes on its own. You run each cell, and you decide what the model gets to see.

Notebooks are ordinary .ipynb files, so anything you write in shidoshi opens in Jupyter, VS Code or GitHub.

Install and run

Requires Python 3.13 or newer.

pip install shidoshi        # or: uv tool install shidoshi
shidoshi                    # open the current directory
shidoshi ~/work/project     # open a folder
shidoshi analysis.ipynb     # open a notebook directly

shidoshi starts a local server, prints its URL and opens it in your browser. The URL carries a one-time access code, so use the full printed link when opening it in another browser. The server only listens on loopback addresses.

Useful flags: --port (default 8420, and the next free port if it is taken), --no-browser, and --ip (127.0.0.1, localhost or ::1). Run shidoshi --help for the rest.

The notebook

A notebook has four kinds of cell:

• Python cells run in a Jupyter kernel. Pick any kernel registered on your machine from the Python environment panel; nothing starts until you run a cell.
• Bash cells run in a persistent shell in the notebook's folder.
• Notes are Markdown, with math, tables, checklists and images.
• Prompt cells are where you talk to a model.

A prompt cell can run in two ways. Ask sends one request: the cells above it become the conversation history, and the answer lands in the cell's output. The model can search the web, and you will see what it searched for. Agent hands the prompt to an agent that can act in the notebook. That is Codex or Claude Code running locally, if you have their CLIs installed, or the built-in agent. Codex and Claude Code show an approval card in the notebook for anything your permission settings don't already allow. The built-in agent can read your variables, run Python and bash, and propose new cells, and it runs code without asking first.

You control the context per cell. Pin a cell to keep it in every prompt's context. Exclude it to keep it out. Notes can be marked as asides, which prompts skip unless pinned.

If Ask or the built-in agent exceeds the model's context limit, it can retry with older unpinned cells omitted. A notice tells you what was omitted; the notebook stays intact. The built-in agent also summarizes older conversation memory. See context limits for pin protection, recovery limits, and how Claude Code and Codex differ.

Drop PNG, JPEG, GIF or WebP files between cells to add them as image notes. The files are saved next to the notebook and linked with ordinary relative Markdown, so keep them with the .ipynb when you move it. Ask and Agent send images from eligible cells above the prompt to models that accept images.

Models and keys

Ask uses OpenAI (through the Responses API), OpenRouter, or Anthropic (through the Messages API). The built-in agent supports OpenAI and OpenRouter; for Claude models there, use the Claude Agent harness. Choose the provider and model from the LLM provider panel in any notebook; each notebook remembers its own choice.

Keys come from OPENAI_API_KEY / OPENROUTER_API_KEY / ANTHROPIC_API_KEY if they are set. Otherwise enter one in the panel and keep it for the session, or save it to your OS keychain. Keys are never written to notebooks or browser storage. OPENAI_BASE_URL points the OpenAI provider at a proxy or compatible endpoint, which must implement /responses.

Codex and Claude Code use their own CLI login and settings.

web-ui/README.md covers kernels, credentials, the Debug toggle, reconnecting and branching in detail.

Coming from the Jupyter magics

Earlier versions of shidoshi were a set of Jupyter magics (%ask, %%agent, %%pin, %shidoshi config) with a TOML config file. Those are gone. The web notebook replaces them, and it can open your existing notebooks.

• %load_ext shidoshi no longer loads anything. Old %ask cells open as plain code cells. Their saved answers stay in place, but they are no longer prompts.
• If you ran shidoshi install-kernel, remove that kernel with jupyter kernelspec remove shidoshi.
• config.toml files are ignored. Choose the provider and model in the web UI.
• shidoshi web is now just shidoshi.

Development

uv sync
npm --prefix web-ui ci && npm --prefix web-ui run build   # the UI the server serves
uv run pytest tests/unit tests/btp tests/test_import_rule.py

Integration tests in tests/integration/ call real models. They need OPENAI_API_KEY / OPENROUTER_API_KEY (or OPENAI_BASE_URL for a proxy):

uv run pytest tests/integration/ -v -m integration

See web-ui/README.md for running the frontend against a live-reloading dev server and for the browser test suites.

License

Apache License 2.0. See LICENSE.