Claude Code Plugins Reference

Terminology note: This document describes plugins (executables discovered and invoked by it2).
For the distinction between plugins, hooks, and tools, see taxonomy.md.

Overview

The it2 CLI includes a comprehensive suite of plugins and native commands specifically designed for automating and orchestrating Claude Code sessions. These enable detection, monitoring, and intelligent interaction with Claude sessions.

Native Session Commands

The current binary includes native session-state commands backed by the
sessionstate package. These commands are hidden from the default command
listing but remain directly invocable:

Core State Detection Commands

Command Purpose Exit Codes
it2 session get-state Comprehensive state analysis 0=success
it2 session is-active Check if session is actively working 0=active, 1=idle
it2 session has-modal Detect modal dialogs 0=modal, 1=no modal
it2 session suggest-action Suggest intervention action 0=actionable, 1=wait/none
it2 session claude-status Human-readable Claude status 0=success

Usage Examples

# Get comprehensive state with Claude detection
it2 session get-state E0A8 --agent=claude --format json

# Check if session is actively working
if it2 session is-active E0A8 --agent=claude; then
    echo "Session busy, waiting..."
    sleep 5
fi

# Detect modal and get type
modal=$(it2 session has-modal E0A8)
case "$modal" in
    approval) echo "Approval needed" ;;
    choice) echo "Selection needed" ;;
    none) echo "No modal" ;;
esac

# Get suggested action and optionally execute it
it2 session suggest-action E0A8 --execute

# Human-readable status display
it2 session claude-status E0A8

Watch Command (Event-Driven Monitoring)

The watch command provides event-driven session monitoring with NDJSON output:

# Watch for state transitions
it2 session watch E0A8 --agent=claude

# Auto-execute suggested actions
it2 session watch E0A8 --agent=claude --auto-act

# Verbose output with full state on each transition
it2 session watch E0A8 --agent=claude --verbose

Output format (NDJSON):

{"timestamp":"2024-12-25T09:00:00Z","session_id":"E0A8...","state":"active","previous_state":"idle","action":"wait"}
{"timestamp":"2024-12-25T09:00:05Z","session_id":"E0A8...","state":"modal","previous_state":"active","modal_type":"approval","safe":true,"action":"modal:approve"}

Agent Detection

All state detection commands support the --agent flag:

The shell-based plugins (it2-session-claude-has-modal, it2-session-claude-suggest-action) now delegate to these native commands when available, falling back to legacy implementation for older it2 versions.

Plugin Categories

1. Session Detection & Identification

it2-session-process-is-claude

Location: internal/embedded/plugins/it2-session-process-is-claude.sh
Purpose: Detect if a session process is running Claude Code

Usage:

it2-session-process-is-claude <session-id> <pid>

Returns:

Implementation: Checks process name using ps for "claude" substring

it2-session-is-claude-code

Location: it2-extensions/it2-session-is-claude-code/it2-session-is-claude-code.sh
Purpose: Detect Claude Code sessions by checking main process and parent chain

Usage:

it2-session-is-claude-code [session-id]
# Uses current session if no ID provided

Returns:

Features:

Example:

# Check current session
it2-session-is-claude-code

# Check specific session
it2-session-is-claude-code A1B2C3D4

# With debug output
ITERM2_DEBUG=1 it2-session-is-claude-code A1B2C3D4

2. Modal Detection & Interaction

it2-session-claude-has-modal

Location: internal/embedded/plugins/it2-session-claude-has-modal
Purpose: Detect modal dialogs in Claude sessions requiring user intervention

Usage:

it2-session-claude-has-modal <session-id>

Returns:

Detection Patterns:

  1. Approval prompts: "Do you want to proceed?"
  2. Choice dialogs: ❯ 1. Yes with numbered options
  3. Confirmations: (Y/n), (y/N), [y/n]
  4. Input prompts: "Enter...", "Please enter", "Input:"
  5. Box dialogs: ╭─╮ style with options
  6. Edit acceptance: "⏵⏵ accept edits", "shift+tab to cycle"

Example:

MODAL=$(it2-session-claude-has-modal A1B2C3D4)
if [[ "$MODAL" == "approval" ]]; then
    echo "Claude is waiting for approval"
fi

it2-session-claude-auto-approve

Location: internal/embedded/plugins/it2-session-claude-auto-approve
Purpose: Automatically approve safe Claude operations

Usage:

it2-session-claude-auto-approve <session-id> [--dry-run]

Returns:

Approval Actions by Modal Type:

Example:

# Auto-approve if safe
it2-session-claude-auto-approve A1B2C3D4

# Dry run to see what would happen
it2-session-claude-auto-approve A1B2C3D4 --dry-run

it2-session-claude-is-safe-operation

Location: internal/embedded/plugins/it2-session-claude-is-safe-operation
Purpose: Determine if a Claude operation is safe to auto-approve

Usage:

it2-session-claude-is-safe-operation <session-id>

Returns:

Safe Operations:

Unsafe Operations:

Context-Based Rules:

Example:

SAFETY=$(it2-session-claude-is-safe-operation A1B2C3D4)
if [[ "$SAFETY" == "safe" ]]; then
    it2-session-claude-auto-approve A1B2C3D4
else
    echo "Human review required"
fi

3. Session State Detection

it2-session-is-at-prompt

Location: internal/embedded/plugins/it2-session-is-at-prompt
Purpose: Check whether the last non-empty screen line resembles a shell or REPL prompt

Usage:

it2-session-is-at-prompt <session-id>

Returns:

Detection Logic:

  1. Reads the session screen and selects its last non-empty line.
  2. Removes ANSI color sequences and surrounding whitespace.
  3. Matches common shell, Python, Node.js, Julia, and IPython prompt suffixes.

This is a text-pattern heuristic. Use it2 session get-state --agent=claude
when agent-specific state classification is required.

Example:

if [[ "$(it2-session-is-at-prompt A1B2C3D4)" == "true" ]]; then
    it2 session send-text A1B2C3D4 "continue"
fi

it2-session-has-no-queued-claude-messages

Location: internal/embedded/plugins/it2-session-has-no-queued-claude-messages
Purpose: Check if there are no queued/pending messages in Claude session

Usage:

it2-session-has-no-queued-claude-messages <session-id>

Returns:

Detected Busy Indicators:

  1. Processing: "thinking...", "generating", "processing"
  2. Spinners: ⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏ characters
  3. Status messages: "working on", "please wait", "one moment"
  4. Tool use: <tool_use>, "Using tool", "Tool call", "Executing"
  5. Streaming: ▌▍▎▏ characters
  6. Queue indicators: "X pending", "X queued", "messages in queue"
  7. Waiting states: "waiting for"
  8. Generation: "Generating response", "Composing", "Drafting"
  9. Ellipsis: Lines ending with ...
  10. Approval dialogs: "Do you want to proceed?"
  11. Pagination: "continue", "show more", "load more" (when actively loading)

Example:

while [[ "$(it2-session-has-no-queued-claude-messages A1B2C3D4)" == "false" ]]; do
    echo "Waiting for Claude to finish..."
    sleep 1
done
echo "Claude is ready"

4. Intelligent Orchestration

it2-session-claude-suggest-action

Location: internal/embedded/plugins/it2-session-claude-suggest-action
Purpose: Analyze Claude session context and suggest appropriate interventions

Usage:

it2-session-claude-suggest-action <session-id> [--execute]

Returns:

Priority Decision Tree:

  1. Modals (highest priority) - Check for approval dialogs
  2. Edit acceptance - Check for "⏵⏵ accept edits" prompts
  3. Active work - Check for ⏺✳✽✶✢⚡🔄🔍 indicators or "Generating/Processing" text
  4. Incomplete todos - Check for ☐ with specific patterns:
    • Vague monitoring → suggest milestone breakdown
    • Test/build todos → suggest running them
    • Generic → send "continue"
  5. Error states - Check for "Error", "Failed", "Exception"
  6. Idle without todos - No action needed

Example:

# Get suggestion
ACTION=$(it2-session-claude-suggest-action A1B2C3D4)
echo "Suggested action: $ACTION"

# Execute suggestion automatically
it2-session-claude-suggest-action A1B2C3D4 --execute

Automation Loop Example:

while true; do
    ACTION=$(it2-session-claude-suggest-action A1B2C3D4 --execute)
    echo "[$ACTION] at $(date)"

    case "$ACTION" in
        "modal:approved"|"continue:"*|"tab:sent")
            echo "Action taken"
            ;;
        "wait")
            sleep 2
            ;;
        "modal:review"|"review:error")
            echo "Human attention needed!"
            break
            ;;
        "none")
            echo "Session complete"
            break
            ;;
    esac
done

Plugin Architecture

Plugin Discovery

Plugins are loaded from multiple locations in priority order:

  1. Directories from PATH environment variable (highest priority)
  2. Directories from IT2_PLUGIN_PATHS / --plugin-path flag (middle priority)
  3. Embedded plugins bundled in the it2 binary (lowest priority, fallback)

Integration with it2 Commands

Plugins are automatically invoked by it2 session list for session property enrichment:

# The "is-claude-in-progress" column uses:
# - it2-session-process-is-claude (detection)
# - it2-session-has-no-queued-claude-messages (status)

it2 session list
# Shows 🚧 flag for Claude sessions with work in progress

Plugin Development Guidelines

Required Structure:

#!/usr/bin/env bash
set -euo pipefail

SESSION_ID="${1:-}"
if [[ -z "$SESSION_ID" ]]; then
    echo "Error: Session ID required" >&2
    exit 1
fi

# Find it2 binary
IT2_BIN=""
if [[ -x "./it2" ]]; then
    IT2_BIN="./it2"
elif [[ -x "$HOME/go/bin/it2" ]]; then
    IT2_BIN="$HOME/go/bin/it2"
elif command -v it2 &> /dev/null; then
    IT2_BIN="$(command -v it2)"
fi

# Plugin logic here...

Best Practices:

Real-World Usage Examples

Example 1: Auto-Approve Safe Operations

#!/bin/bash
# Monitor Claude session and auto-approve safe operations

SESSION_ID="$1"

while true; do
    MODAL=$(it2-session-claude-has-modal "$SESSION_ID")

    if [[ "$MODAL" != "none" ]]; then
        RESULT=$(it2-session-claude-auto-approve "$SESSION_ID")
        echo "[$(date '+%H:%M:%S')] Modal $MODAL: $RESULT"
    fi

    sleep 1
done

Example 2: Wait for Claude to Finish

#!/bin/bash
# Wait for Claude to complete current work

SESSION_ID="$1"

echo "Waiting for Claude to finish..."
while [[ "$(it2-session-has-no-queued-claude-messages "$SESSION_ID")" == "false" ]]; do
    sleep 2
done
echo "Claude is ready!"

Example 3: Smart Claude Orchestration

#!/bin/bash
# Fully automated Claude orchestration

SESSION_ID="$1"

while true; do
    # Let suggest-action make the decision and execute it
    RESULT=$(it2-session-claude-suggest-action "$SESSION_ID" --execute)

    echo "[$(date '+%H:%M:%S')] $RESULT"

    case "$RESULT" in
        "modal:review"|"review:error")
            echo "⚠️  Human intervention required"
            exit 1
            ;;
        "none")
            echo "✅ Work complete"
            exit 0
            ;;
        "wait")
            sleep 3
            ;;
        *)
            sleep 1
            ;;
    esac
done

Example 4: Multi-Claude Coordination

#!/bin/bash
# Coordinate multiple Claude sessions

CLAUDE_A="ABC12345"
CLAUDE_B="DEF67890"

# Send tasks to both Claudes
it2 session send-text "$CLAUDE_A" "Analyze the frontend code"
it2 session send-text "$CLAUDE_B" "Analyze the backend code"

# Monitor both sessions
while true; do
    A_DONE=$(it2-session-has-no-queued-claude-messages "$CLAUDE_A")
    B_DONE=$(it2-session-has-no-queued-claude-messages "$CLAUDE_B")

    # Auto-approve any safe modals
    it2-session-claude-auto-approve "$CLAUDE_A" 2>/dev/null
    it2-session-claude-auto-approve "$CLAUDE_B" 2>/dev/null

    if [[ "$A_DONE" == "true" ]] && [[ "$B_DONE" == "true" ]]; then
        echo "Both Claudes finished!"
        break
    fi

    sleep 2
done

Performance Considerations

Plugin Execution Time:

Caching Strategies:

# Cache screen content for multiple checks
SCREEN_CONTENT=$(it2 session get-screen "$SESSION_ID")
echo "$SCREEN_CONTENT" | grep -q "Do you want to proceed?"

Polling Recommendations:

Troubleshooting

Plugin Not Found

# Check plugin search paths
echo $IT2_PLUGIN_PATHS

# Verify plugin is executable
it2 plugin list

# Add custom plugin path
it2 --plugin-path /path/to/plugins session list

Debug Mode

# Enable debug output
ITERM2_DEBUG=1 it2-session-is-claude-code A1B2C3D4

# Shows:
# [DEBUG] it2-session-is-claude-code: SESSION_ID=A1B2C3D4
# [DEBUG] Got PID from get-pid: 12345
# [DEBUG] Process name for PID 12345: node
# [DEBUG] Parent 1 PID 12344: claude

Common Issues

"Session not found" errors:

Modals not detected:

Auto-approve not working:

Plugin Development

To create a new Claude-related plugin:

  1. Create the plugin file:
mkdir -p ~/bin
touch ~/bin/it2-session-claude-my-feature
chmod +x ~/bin/it2-session-claude-my-feature
  1. Use the template:
#!/usr/bin/env bash
set -euo pipefail

SESSION_ID="${1:-}"
if [[ -z "$SESSION_ID" ]]; then
    echo "Error: Session ID required" >&2
    exit 1
fi

# Find it2 binary
IT2_BIN=""
if [[ -x "./it2" ]]; then
    IT2_BIN="./it2"
elif command -v it2 &> /dev/null; then
    IT2_BIN="$(command -v it2)"
fi

# Your plugin logic here
SCREEN=$($IT2_BIN session get-screen "$SESSION_ID" 2>/dev/null || echo "")

# Return result
echo "result"
  1. Test the plugin:
~/bin/it2-session-claude-my-feature A1B2C3D4
  1. Integrate with it2 (if needed):

Summary

The shipped plugins cover process detection, prompt and modal heuristics,
session-state checks, and suggested interventions. The auto-approval and safety
classifiers are text-pattern heuristics; inspect their output and use dry-run
mode before enabling actions in an unattended workflow.