it2 Extensibility Taxonomy

This document defines the taxonomy for it2's extensibility mechanisms. It serves as the authoritative reference for terminology used throughout the codebase and documentation.

Overview

it2's extensibility model distinguishes between three concepts:

1. Tools — Standalone CLI programs for direct user invocation
2. Plugins — Executables discovered and exec'd by it2 programmatically
3. Hooks — Executables triggered by external tools (Claude Code, Gemini CLI, etc.)

These share implementation patterns but differ in invocation model and lifecycle.

Core Concepts

Tool

A tool is a standalone CLI program designed for direct user invocation from the command line.

Characteristics:

• Invoked directly by users (e.g., it2, it2-convert, it2-migrate)
• Self-contained with its own argument parsing and help
• Not discovered or managed by it2
• May use it2's libraries internally

Examples:

it2                    # The main CLI tool
it2-session-badge      # Render dynamic session badges
it2-session-snapshot-claude # Capture Claude session state

Key distinction: Tools are user-facing; plugins are it2-facing (though plugins can be run directly).

Plugin

A plugin is an external executable that extends it2 functionality. Plugins are discovered automatically and managed by it2.

Characteristics:

• Executable files with it2- prefix
• Discovered from PATH, IT2_PLUGIN_PATHS, or embedded in the binary
• Receive structured input (arguments or JSON on stdin)
• Produce structured output (text or JSON on stdout)
• Run with a filtered environment and an execution deadline

Discovery Order (highest to lowest priority):

1. Executables in PATH
2. Directories from IT2_PLUGIN_PATHS environment variable
3. Embedded plugins extracted from the it2 binary

Example plugins:

it2-session-is-claude-code      # Detects Claude Code sessions
it2-session-claude-has-modal    # Detects modal dialogs
it2-tab-git-status              # Shows git status for tabs

Hook

A hook is an executable triggered by external tools in response to events. Hooks are configured externally, not discovered by it2.

Characteristics:

• Registered in external tool configuration (e.g., Claude Code's settings.json)
• Receive event data via stdin (JSON)
• Used for logging, automation, or side effects
• Lifecycle managed by the external tool, not it2

Key distinction from plugins: Hooks respond to events from external tools; plugins are invoked by it2 itself.

Example hooks:

it2-claude-code-hook    # Logs Claude Code events to session artifacts
it2-gemini-hook         # (future) Logs Gemini CLI events

Hook configuration example (Claude Code):

{
  "hooks": {
    "PostToolUse": [{
      "hooks": [{"type": "command", "command": "it2-claude-code-hook"}]
    }]
  }
}

Plugin Categories

The executable name determines how it2 invokes a plugin:

Some session plugins are also useful as directly invoked automation commands.
For example, it2-session-claude-suggest-action reports a suggested
intervention and it2-session-claude-auto-approve can act on a prompt after
its safety check.

The package contains an experimental manifest data model, but manifests do not
currently participate in plugin discovery or runtime permission enforcement.
See Plugin Manifest Data Model for that boundary.

Naming Conventions

Plugin Names

it2-<scope>-<name>
it2-<scope>-<context>-<name>

Components:

• it2- — Required prefix for discovery
• <scope> — Target scope: session, tab, window, session-process
• <context> — Optional context: claude, git, docker, etc.
• <name> — Descriptive action: has-modal, is-at-prompt, suggest-action

Examples:

it2-session-is-at-prompt           # Session scope, general purpose
it2-session-claude-has-modal       # Session scope, Claude-specific
it2-session-claude-auto-approve    # Session scope, Claude automation
it2-tab-git-status                 # Tab scope, git-specific
it2-session-process-is-claude      # Process scope, Claude detection

Hook Names

it2-<source>-hook

Examples:

it2-claude-code-hook    # Hook for Claude Code events
it2-gemini-hook         # Hook for Gemini CLI events

CLI Commands

it2 plugin — Run and manage plugins

The it2 plugin command provides access to discovered plugins:

# List available plugins
it2 plugin list

# Run a plugin directly via it2
it2 plugin <name> [args...]

# Install Claude Code hooks
it2 plugin claude-code-hook --install

Running plugins directly

Plugins can also be invoked directly from the command line (without going through it2 plugin):

# Run directly (if in PATH)
it2-session-claude-has-modal <session-id>

# Equivalent via it2
it2 plugin claude-has-modal <session-id>

The it2 plugin wrapper provides:

• Automatic session ID injection from $ITERM_SESSION_ID
• Plugin discovery information
• Consistent error handling

Note on it2 tool (renamed)

The previous it2 tool command has been renamed to it2 plugin for consistency with the taxonomy. The old command is deprecated and will warn once per day:

# Deprecated (warns once per day)
it2 tool list

# Use instead
it2 plugin list

Not in Scope

MCP (Model Context Protocol)

MCP servers are not part of it2's plugin taxonomy. They are a separate integration:

it2 may provide hooks that facilitate MCP integration, but MCP servers themselves are external.

iTerm2 Python API Scripts

iTerm2's native Python API scripts are separate from it2 plugins. They run within iTerm2's Python environment and use a different interface.

Migration Guide

Terminology Changes

Note: "Tool" remains a valid concept for standalone CLI programs (like it2 itself). Only the it2 tool command is renamed to it2 plugin because it operates on plugins.

Command Migration

# Old (deprecated, warns once per day)
it2 tool list

# New
it2 plugin list

it2 tool currently forwards to it2 plugin and prints a deprecation
warning. No removal release is specified here.

Quick Reference

Related Documentation

• Plugin Development Guide — How to write plugins
• Plugin Manifest Data Model — Experimental manifest types and runtime boundary
• Claude Plugins Reference — Claude-specific plugins