# Tsugumi

> Run the analysis you sketched with AI, as it is, and check it with your own hands.

Tsugumi is a research workbench in which the specification a person draws, the thing an AI edits and the processing that actually runs are one and the same Workflow. It runs on macOS, Linux and Windows (Windows through WSL2).
You draw a computation or a data pipeline as Cards and the wires between them, implement it together with an AI, and run it in environments pinned with Nix.
You open the code or the result of a Card you are curious about, change a condition and try again with the inputs that were saved. Going back and forth like this, a researcher comes to understand how the analysis got where it did, and can ask the next question.

The documents are written for both people and AI. The URLs below are the Markdown version of each page.

## Overview

- [README](https://gen740.github.io/Tsugumi/index.md): the problem, how to use it, and the real screens explained

## Getting started

- [Tsugumi's features](https://gen740.github.io/Tsugumi/pages/features.md): Find a feature by task; Card kinds, execution rules and Nix environments
- [Installation and development builds](https://gen740.github.io/Tsugumi/pages/install.md): Installing and updating the desktop app and the `tsugumi` command (Mac, Linux, Windows), and building from source
- [Usage](https://gen740.github.io/Tsugumi/pages/usage.md): Canvas tools, running from a Card, chart updates, settings and Agent controls
- [The bundled demos](https://gen740.github.io/Tsugumi/pages/demos.md): Choose a demo, try changes and interpret its results
- [Your first Card](https://gen740.github.io/Tsugumi/pages/cardguide.md): Build a Card that takes an input and computes, with examples in Python, Bash, C++, R, Julia, Ruby, Go, Rust and C#
- [Run history and artifacts](https://gen740.github.io/Tsugumi/pages/runhistory.md): Inspect and compare runs, check runtime packages and open saved artifacts
- [Run a Card on a remote worker](https://gen740.github.io/Tsugumi/pages/remoteexecution.md): Register a C++ remote worker and run a Code Card on its Linux host
- [C# Cards](https://gen740.github.io/Tsugumi/pages/csharp.md): C# typed ports, Tasks, NuGet dependencies and the .NET worker lifetime
- [Visualization Cards](https://gen740.github.io/Tsugumi/pages/visualization.md): Editable library/shape scaffolds, data parameters, saved figures and reports
- [marimo notebook Cards](https://gen740.github.io/Tsugumi/pages/marimo.md): Committed notebook runs, typed inputs/outputs, saved cell results and the interactive-session boundary
- [R report Cards](https://gen740.github.io/Tsugumi/pages/reports.md): R Markdown and Quarto report Cards, saved HTML and parameterized rendering
- [Web UI](https://gen740.github.io/Tsugumi/pages/webui.md): The browser workbench and the `tsugumi` command on Mac, Linux and Windows through WSL2
- [Binary caches](https://gen740.github.io/Tsugumi/pages/binarycaches.md): Attic, Cachix and other signed binary caches, private authentication and VM-wide trust
- [Using it from Claude Code](https://gen740.github.io/Tsugumi/pages/claude-code.md): Having Claude Code make and run Cards through the Claude Code plugin, shown in the Web UI

## The ideas

- [What to build so that we are not used by AI](https://gen740.github.io/Tsugumi/pages/philosophy.md): "What to build so that we are not used by AI": the concern behind Tsugumi, its name and its author
- [Why one Workflow for design, implementation and checking](https://gen740.github.io/Tsugumi/pages/rationale.md): Why design, implementation and checking share one Workflow: answers to the three reasons for hesitating to hand research to AI (an invisible process, reproducibility, data), the measures that keep trial and error light
- [Vision and applications](https://gen740.github.io/Tsugumi/pages/vision.md): Applications: learning research decisions, growing tools, handing work to the next person, and the idea of business automation
- [Before relying on a result](https://gen740.github.io/Tsugumi/pages/limitations.md): Checks before relying on a result and links to execution constraints

## How it works

- [Versions (git)](https://gen740.github.io/Tsugumi/pages/versions.md): Versions: the project's git, each run's version and result (git notes), the version tree and "Start from This Version"
- [Security and isolation](https://gen740.github.io/Tsugumi/pages/security.md): What is and is not protected, the four isolation boundaries (VM, project, Card, RPC), API keys, where data is kept, and known limitations
- [The RPC contract](https://gen740.github.io/Tsugumi/pages/protocol.md): The project RPC requests and notifications (generated from `protocol/tsugumi.fbs`)
- [Glossary](https://gen740.github.io/Tsugumi/pages/glossary.md): Card, Draft, Run, invocation, version and other terms

## Dependencies and distribution


## Repository

- [AGENTS.md](https://raw.githubusercontent.com/gen740/Tsugumi/main/AGENTS.md): a map and instructions for agents working in this repository
- [The Card specification](https://raw.githubusercontent.com/gen740/Tsugumi/main/docs/CardGuide.md): Card contracts and per-language SDK APIs
- [The RPC contract](https://raw.githubusercontent.com/gen740/Tsugumi/main/protocol/tsugumi.fbs): the source of the contract the UI, the Web and the Agent use

## Optional

- [Licenses and distribution](https://gen740.github.io/Tsugumi/pages/licenseaudit.md): License bundling, VM source distribution and dependency updates