Installation

New to the terminal? For a friendlier, step-by-step walkthrough, see the Getting Started guide.

No install needed to try it

Want to try IST before installing anything? The IST Workshop Codespace runs everything pre-installed in your browser via GitHub Codespaces, with a ~30-minute hands-on workshop to start. (한국어)

Before you start

This guide is written for macOS or Linux.

On Windows? First set up WSL (a Linux environment) and, optionally, VSCode. If you're not sure how, just ask an AI assistant "how do I set up WSL and VSCode on Windows?" — it'll walk you through it kindly. Once that's done, follow the steps below exactly the same way.

VSCode is optional, but it makes editing files and opening a terminal much more convenient.

Where do I type these commands? Every command below goes into your terminal, one line at a time (copy, paste, press Enter).

• macOS — open the Terminal app (press Cmd+Space, type "Terminal", hit Enter).
• VSCode — open the built-in terminal with Ctrl+` (the backtick key, usually just above Tab).

Prerequisites

You'll set these up step by step below — no need to have them ready in advance:

• Node.js & npm — installed via nvm
• An AI CLI — one of Claude Code (@anthropic-ai/claude-code), Cursor, or Codex CLI
• tmux — sessions run inside tmux

Install Node.js and npm (via nvm)

Node.js is the runtime the IST tools run on, and npm comes bundled with it. Installing Node through nvm makes version management easy (the steps are the same on macOS and Linux).

# 1) Install nvm (copy-paste this one line as-is)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.7/install.sh | bash

# 2) Load nvm in the current terminal (or just close and reopen the terminal)
source ~/.nvm/nvm.sh

# 3) Install the latest LTS version of Node.js (npm comes with it)
nvm install --lts

The v0.40.7 in the URL is the nvm release to install. If that line fails or you want a newer version, copy the latest one-liner from the "Install & Update Script" section at github.com/nvm-sh/nvm.

Verify that Node.js and npm are available:

node -v
npm -v

If both print a version number, you're good. (If you see nvm: command not found, fully close and reopen your terminal, then run nvm install --lts again.)

Install an AI CLI

Pick one AI CLI to work with. A popular choice is Claude Code:

npm install -g @anthropic-ai/claude-code

Cursor and Codex CLI also work — just install the one you prefer.

Install tmux

IST sessions run inside tmux. Install it for your platform:

# macOS
brew install tmux

# Linux (Ubuntu / Debian)
sudo apt install tmux

Verify it installed:

tmux -V

Install the Snapshot CLI

IST is installed through snapshot, the MicrowiseAI installer. Install it globally:

npm install -g @microwiseai/snapshot

Check it is available:

snapshot --version

Install IST

Install the IST beta snapshot:

snapshot install @ist/beta

This installs the full IST toolset (session tools, adapters, and the TDA/monitoring stack) in one step. When it finishes, the summary shows Installed: N/N.

You don't need an IST account to install. Without one, snapshot prints No IST login - installing public package at the start and may end with a note that the IST Credentials prerequisite is not satisfied. That's expected: the tools are installed. You sign in later, in Enable Monitoring.

Package Registry

IST packages are hosted on the MicrowiseAI package registry, not the public npm registry. The snapshot CLI automatically configures npm to use the correct registry proxy during installation, so no manual registry setup is required.

Check Installed Versions

Package versions are managed by the snapshot and change over time. To see exactly what is installed, use:

snapshot current

This lists the current snapshot and the versions of every package it provides.

Verify Installation

Confirm the core CLIs are available:

isesh --version
itda list

If isesh prints a version and itda list runs without errors, IST is ready.

You can also run a health check:

snapshot doctor

Enable Monitoring (Login)

Log in once to activate session monitoring and the detector agent:

detector-agent login

This opens a Google sign-in. You only need to do this once.

Then start the detector agent as a background daemon (it won't start until you are logged in):

detector-agent start

Once it is running, IST can detect your sessions, drive auto-approval, and surface them in the web dashboard. Check it with detector-agent status. (smon also starts it automatically when it needs it, but only after you have logged in.)

To check or clear the login later:

detector-agent whoami
detector-agent logout

Install the Web UI (optional)

IST UI (ist-ui) is a local web page for people who'd rather not stay in the terminal. It has two areas:

• Setup — sign in to your IST account, Claude Code and Codex; start or stop the detector-agent daemon; see which tools are installed.
• Managers — list your manager sessions with their folders and worker counts, and start, create, move, rename or stop them.

It needs Node.js 22.18 or newer (the current LTS from nvm install --lts is fine) and tmux. The Managers area also uses the IST CLIs installed above (isesh, itda) and Claude Code.

The UI comes in the @ist/ist-control-ui package. Install it with glpkg, the MicrowiseAI package installer (no account or token needed):

npm install -g @glpkg/cli
glpkg install -g @ist/ist-control-ui --group microwiseai

Check it is available:

ist-ui --version

Run it

Run ist-ui from the project folder you want to work in:

cd ~/my-project
ist-ui

It starts a server in the background for that folder and opens your browser. The address looks like http://127.0.0.1:7788/?t=<token>:

• Port 7788 is the default. If 7788 is taken, the next free port is used. Pick the first port to try with --port N.
• The server only listens on your own machine (127.0.0.1). The ?t=<token> part is a per-launch key, so always open the full URL that ist-ui prints.
• No browser opened (for example on a headless machine)? Copy the printed URL into your browser, or print it again with ist-ui url. Use --no-open to skip the browser on purpose.

Manage the server:

ist-ui status   # running? pid, port, folder, URL
ist-ui url      # print the URL only
ist-ui stop     # stop the server

To keep it in the current terminal instead of the background, run ist-ui --foreground and stop it with Ctrl-C.

Directory Structure

After installation, IST uses the following directories:

~/.ist/
├── logs/           # Session logs
│   └── {session}/  # Per-session log files
├── prompts/        # Custom prompts
├── state/          # Session state
└── profiles/       # Profile configurations

Updating

To update to the latest IST packages, re-run the install:

snapshot install @ist/beta

This re-installs the latest versions from the snapshot. Run snapshot current afterward to confirm the new versions.

If you installed the web UI, update it the same way:

glpkg install -g @ist/ist-control-ui --group microwiseai