Metadata-Version: 2.5
Name: shidoshi
Version: 0.13.2
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-openai>=1.5.0
Requires-Dist: langchain-openrouter>=0.2.7
Requires-Dist: mcp<2,>=1.21
Requires-Dist: mistune<4,>=3.2.1
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: 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

Requires Python 3.13 or newer.

```bash
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](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.

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

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.

## License

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