Skip to main content

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.