Installation

Prerequisites

• Node.js 18+ and npm
• tmux — IST uses tmux for persistent sessions
• An AI CLI — One of: Claude Code, Cursor, or Gemini CLI

Option A: Command Line (Recommended)

1. Check your environment

npx @microwiseai/ist-setup doctor

This checks for Node.js, tmux, and an AI CLI. If anything is missing, it tells you how to fix it.

2. Log in

npm install -g @microwiseai/ist-setup
ist login

Login is required for the testing tier (the default).

3. Install IST

ist-setup install

This installs the testing tier by default, which includes all core tools plus monitoring and TDA profiles.

4. Verify

ist-setup doctor

If everything shows green, you're ready. Start a session:

isesh start my-project -p mwd

Option B: VSCode Extension

1. Open VS Code
2. Go to Extensions (Ctrl+Shift+X)
3. Search for "Integrated Session Tools"
4. Click Install
5. Open the IST panel in the sidebar
6. Click "Install Dependencies"

The extension handles installation, login, and session management through a graphical interface.

What gets installed

ist-setup install installs the following tools:

Package	CLI Command	Description
@ist/loggable-cli	ilogsession	Session logging and management
@ist/messenger-cli	imessenger	Inter-session messaging
@ist/sesh	isesh	Session configuration and management
@ist/detector-agent	detector-agent	Automatic session detection
@microwiseai/skit	skit	Profile package manager
@ist/smon	smon	Session monitoring and auto-approval
@ist/tda	—	TDA Manager/Worker profiles
@ist/relay-agent	relay-agent	Cross-machine session relay
@ist/relay-cli	irelay	Relay management

Directory structure

After installation, IST uses:

~/.ist/
  credentials         # Auth credentials
  logs/               # Session logs
  prompts/            # Tool prompts (installed by skit)
  profiles/           # Session profiles
  state/              # Persistent session state
  messenger/          # Message queues

Updating

Re-run the install command to update to latest versions:

ist-setup install

Uninstalling

# Remove all IST packages
npm uninstall -g @ist/loggable-cli @ist/messenger-cli @ist/sesh @ist/detector-agent @microwiseai/skit @ist/smon

# Remove data
rm -rf ~/.ist

Troubleshooting

ist-setup doctor shows errors

Run with --fix to auto-fix what it can:

ist-setup doctor --fix

tmux not found

# macOS
brew install tmux

# Ubuntu/Debian
sudo apt install tmux

Permission errors during install

If npm install -g fails with permission errors:

# Fix npm global permissions
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc