Installation

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

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, Codex CLI, or Gemini 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, Codex CLI, and Gemini 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 Microwise AI 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.

Package Registry

IST packages are hosted on the Microwise AI 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. Once logged in, IST can detect your sessions, drive auto-approval, and surface them in the web dashboard. You only need to do this once.

To check or clear the login later:

detector-agent whoami
detector-agent logout

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.