Metadata-Version: 2.5
Name: shidoshi
Version: 0.14.1
Summary: A local, AI-native notebook for iterative work with LLMs and coding agents
Project-URL: Homepage, https://github.com/tdchaitanya/shidoshi
Project-URL: Repository, https://github.com/tdchaitanya/shidoshi
Project-URL: Issues, https://github.com/tdchaitanya/shidoshi/issues
Author-email: Chaitanya <tdchaitanya@gmail.com>
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: agents,ai-assistant,anthropic,ipynb,llm,notebook,openai,openrouter
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.13
Requires-Dist: anthropic<1,>=0.121
Requires-Dist: claude-agent-sdk<0.2,>=0.1.81
Requires-Dist: deepagents<0.8,>=0.7.5
Requires-Dist: fastapi>=0.115
Requires-Dist: ipykernel>=6.29
Requires-Dist: jupyter-client>=8.6
Requires-Dist: keyring<26,>=25.7
Requires-Dist: langchain-anthropic<2,>=1.5.4
Requires-Dist: langchain-openai>=1.5.0
Requires-Dist: langchain-openrouter>=0.2.7
Requires-Dist: langgraph-checkpoint-sqlite<4,>=3.1.1
Requires-Dist: mcp<2,>=1.21
Requires-Dist: mistune<4,>=3.2.1
Requires-Dist: nbdime<5,>=4.0.4
Requires-Dist: nbformat>=5.10
Requires-Dist: openai>=2.41.1
Requires-Dist: pillow>=12.2.0
Requires-Dist: platformdirs>=4.10.0
Requires-Dist: psutil<8,>=7.2.2
Requires-Dist: pydantic>=2.12.5
Requires-Dist: send2trash>=1.8
Requires-Dist: typing-extensions>=4.0
Requires-Dist: uv>=0.12
Requires-Dist: uvicorn[standard]>=0.32
Description-Content-Type: text/markdown

# shidoshi

[![PyPI](https://img.shields.io/pypi/v/shidoshi.svg)](https://pypi.org/project/shidoshi/)
[![CI](https://github.com/tdchaitanya/shidoshi/actions/workflows/test.yml/badge.svg)](https://github.com/tdchaitanya/shidoshi/actions/workflows/test.yml)
[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)

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

On macOS and Linux:

```bash
curl -LsSf https://raw.githubusercontent.com/tdchaitanya/shidoshi/main/install.sh | sh
```

On Windows (PowerShell):

```powershell
powershell -ExecutionPolicy ByPass -c "irm https://raw.githubusercontent.com/tdchaitanya/shidoshi/main/install.ps1 | iex"
```

The script installs [uv](https://docs.astral.sh/uv/) with Astral's installer
if you don't have it, then runs `uv tool install shidoshi` and adds uv's tool
directory to your PATH. It never uses sudo or your system Python. Run it again
to upgrade. Set `SHIDOSHI_VERSION=0.14` to install a specific version, or
`UV_NO_MODIFY_PATH=1` to leave your shell profile alone.
[install.sh](install.sh) is short if you'd like to read it first.

If you already have uv, or would rather install it yourself (`winget install
astral-sh.uv` on Windows), install shidoshi as a uv tool directly. It gets its
own isolated environment and a `shidoshi` command on your PATH, so one install
works from any folder and doesn't touch your projects' environments:

```bash
uv tool install shidoshi    # later: uv tool upgrade shidoshi
uv tool update-shell        # if `shidoshi` isn't found in a new terminal
```

Then:

```bash
shidoshi                    # open the current directory
shidoshi ~/work/project     # open a folder
shidoshi analysis.ipynb     # open a notebook directly
```

shidoshi needs Python 3.13 or newer, and uv downloads it if your machine
doesn't have it. `uvx shidoshi` runs it once without installing. pipx works too
(`pipx install --python python3.13 shidoshi`), and so does `pip install
shidoshi` into an environment you manage yourself.

`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, in the Python environment you pick
  from the notebook's 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.

Shift+Enter runs the current cell and selects the next; at the end it creates
a blank Python cell ready for typing. Cmd/Ctrl+Enter runs in place. Notes render
Markdown and prompts run Ask; neither shortcut runs adjacent cells.
Python `input()` and `getpass.getpass()` accept replies inline, with password
fields masked. Stop interrupts a pending input request.

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](docs/context-limits.md) 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.

## Python environments

Your notebook code should run in an environment of its own, not in the one
shidoshi is installed in. With `uv tool install`, shidoshi's environment
belongs to uv: packages you add to it can be removed on the next upgrade, and
they can break shidoshi's own dependencies. The environment panel labels that
kernel "Shidoshi's Python" and warns when a notebook uses it. In that kernel
`%pip`, `%uv`, `%conda`, `%mamba` and `%micromamba` install nothing and point
you to an environment of your own. Shell commands such as `!pip` can't be
intercepted, so don't install with them there either.

The panel can create a separate environment for you, using uv, with no terminal
needed. Each one is a small uv project under `~/.shidoshi/envs`. `%pip install`
in a notebook installs into that environment, and the Packages window adds,
removes and upgrades packages with a preview first. You can also link a uv
project you already have, or pick any Jupyter kernel registered on your
machine.

Mark one environment "Use for new notebooks" and new notebooks start with it
suggested. While a notebook is on Shidoshi's Python, the panel offers to
create a default environment in one click. A notebook that already names a kernel keeps it, and
nothing switches without you choosing it.

## 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](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

```bash
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
```

In a source checkout, Shidoshi's Python refuses `%pip` too, as it does for
users. To install into the checkout's `.venv` from a notebook anyway, start the
server with `SHIDOSHI_ALLOW_INTERNAL_PIP=1 uv run shidoshi`. Only the value `1`
turns the guard off, and it applies to kernels started after that.

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

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

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

The test workflow runs on two Linux x64 runners with the `shidoshi-ci` label
on `luge-per-middlegame.exe.xyz`: `gondola-tarte-1` and `gondola-tarte-2`.
Each runs as a separate non-sudo user with its own workspace and caches under
`/opt/shidoshi-runners/runner-1` or `runner-2`. Both systemd services start on
boot; inspect them on the VM with `sudo systemctl status 'actions.runner.*'`.
Chromium system dependencies are installed on the VM; rerun Playwright's
`install-deps chromium` as an administrator when an upgrade requires new ones.
Adding runners to this same VM also requires assigning distinct browser test
ports in `.github/workflows/test.yml`.

## License

Apache License 2.0. See [LICENSE](LICENSE).
