> ## Documentation Index
> Fetch the complete documentation index at: https://hoopdev-feat-new-runbook-parameters.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# AI Session Analyzer

> Analyze terminal sessions in real time and enforce risk-based actions before execution

<Frame>
  <img src="https://mintcdn.com/hoopdev-feat-new-runbook-parameters/9UvCrBcG2bkKisqL/images/learn/features/ai-session-analyzer.png?fit=max&auto=format&n=9UvCrBcG2bkKisqL&q=85&s=ad54ad02eb8fddc7d5dc35702216d9c0" alt="AI Session Analyzer" width="3540" height="2496" data-path="images/learn/features/ai-session-analyzer.png" />
</Frame>

## What You'll Accomplish

AI Session Analyzer is Hoop's AI-powered risk analysis capability for one-off sessions. It evaluates commands before execution and applies configured policies automatically, so you can:

* Detect risky commands in real time before impact
* Block destructive or high-risk operations proactively
* Apply consistent policy decisions across resources

***

## How It Works

<Steps>
  <Step title="Configure Provider and Rules">
    Configure the AI provider and define risk rules.
  </Step>

  <Step title="Command Is Analyzed">
    A command runs and is analyzed in real time by AI.
  </Step>

  <Step title="Action Is Applied">
    Based on the rules and AI analysis, the command is allowed or blocked.
  </Step>
</Steps>

***

## Quick Start

## Prerequisites

To get the most out of this guide, you will need to:

* Either [create an account in our managed instance](https://use.hoop.dev) or [deploy your own hoop.dev instance](/setup/deployment/overview)
* You must be your account administrator to perform the following actions

- Access to AI Session Analyzer settings in the Web App
- A valid AI provider account and API key

### Step 1: Configure the AI Provider

In **AI Session Analyzer > Configure**:

1. Select one provider:
   * Azure OpenAI
   * OpenAI
   * Anthropic
   * Custom (OpenAI-compatible API)
2. Enter the AI model
3. Enter the API key
4. Click **Save**

* Required fields cannot be empty
* Credentials are validated before save

On success, the UI shows: `Configuration saved.`

### Step 2: Create the First Rule

In **AI Session Analyzer > Rules**:

1. Click to create the first rule
2. Add a **Name** and optional **Description**
3. Configure rule scope (roles and attributes)
4. Select risk action behavior (for example, allow or block)
5. Save the rule

### Step 3: Run a Command in Terminal

Open a terminal session and run a command.

The command is evaluated in real time using your configured provider and rules.

### Step 4: Verify the Result

Confirm the resulting action and risk status in the terminal and in session details.

***

## Runtime Analysis Experience

### In-Terminal Behavior

When a terminal session starts:

* Terminal shows an in-session status card: `AI Session Analyzer is thinking...`
* Analyzer evaluates activity in real time
* If no rule is violated, show Allowed/success status (non-blocking notification)
* If any configured risk rule is triggered, show Blocked status (prominent restriction notification)

### Session Details Review

In the session detailed view:

* Top status list includes **AI Session Analyzer** item
* Item displays action status: **Allowed** or **Blocked**
* A dedicated card shows:
  * Title plus risk level indicator (**Low Risk**, **Medium Risk**, **High Risk**)
  * Action applied by rule (**Allowed** or **Blocked**)

***

## Status Types

| Status      | Meaning                                            |
| ----------- | -------------------------------------------------- |
| **Allowed** | Session complies with configured risk rules        |
| **Blocked** | Session violates one or more configured risk rules |

***

## Best Practices

<CardGroup cols={2}>
  <Card title="Recommended Risk Evaluation" icon="bell">
    Use the recommended risk evaluation to apply policies based on each session's risk profile.
  </Card>

  <Card title="Scope by Role" icon="users">
    Apply stricter policies to privileged roles and production-facing resources first.
  </Card>

  <Card title="Review Outcomes Weekly" icon="calendar">
    Audit Allowed/Blocked trends and tune rules for false positives or blind spots.
  </Card>
</CardGroup>

***

## Troubleshooting

### Rules Tab Is Empty

**Check:**

1. Configure tab was completed first
2. Provider, model, and API key are valid
3. Configuration was saved successfully

### Save Is Blocked

**Check:**

1. All required fields are filled
2. API key is valid for selected provider/model
3. Custom provider fields are complete (if using OpenAI-compatible API)

### Analyzer Not Applying Rules in Session

**Check:**

1. At least one rule exists and is active
2. Rule scope (roles/attributes) matches the current session
3. Commands are running in Web Terminal where analyzer status is shown

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Guardrails" icon="shield" href="/learn/features/guardrails">
    Add deterministic query and command controls
  </Card>

  <Card title="Live Data Masking" icon="mask" href="/learn/features/live-data-masking">
    Protect sensitive output with automatic redaction
  </Card>

  <Card title="Session Recording" icon="video" href="/learn/features/session-recording">
    Audit command history and investigation trails
  </Card>

  <Card title="Access Requests" icon="clock" href="/learn/features/access-requests/jit">
    Require approvals for sensitive operations
  </Card>
</CardGroup>