> ## Documentation Index
> Fetch the complete documentation index at: https://docs.overcut.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Interactive Sessions

> How interactive sessions work, comment routing behavior, and configuration options for ongoing conversations with agents.

Interactive sessions enable ongoing conversations between users and agents, maintaining context across multiple comments without restarting workflows.

<Note>
  For basic agent setup, see [Agent Session Action](/docs/workflows/agent-session) and [Agent Differences](/docs/workflows/agent-differences).
</Note>

***

## How Sessions Work

<CardGroup cols={2}>
  <Card title="Comment Routing" icon="route">
    Comments route directly to active sessions instead of creating new workflows.
  </Card>

  <Card title="Context Preservation" icon="memory">
    Full conversation history maintained throughout the session.
  </Card>

  <Card title="Graceful Termination" icon="hand">
    Sessions can be ended with keywords or interrupted by slash commands.
  </Card>

  <Card title="Timeout Control" icon="clock">
    Configurable duration limits prevent sessions from running indefinitely.
  </Card>
</CardGroup>

## Session vs Standard Workflows

### **Standard Workflow**

Each mention or slash command creates a new workflow execution:

```
User: "@overcut review this"     → New workflow starts (mention trigger)
User: "What about line 45?"      → No workflow triggered (plain comment)
User: "@overcut /help"           → New workflow starts (slash command)
```

### **Interactive Session**

One workflow handles multiple comments:

```
User: "@overcut review this"     → Workflow starts, session becomes active
User: "What about line 45?"      → Routes to active session (plain comment)
User: "/done"                    → Routes to session, triggers completion signal, ends
```

***

## Comment Routing Rules

When a comment or Slack thread reply is posted, Overcut routes live conversations before it evaluates new triggers:

<Steps>
  <Step title="Check for Active Run or Session">
    Is there a workflow run or interactive session currently live for this PR, issue, or Slack thread?
  </Step>

  <Step title="Route to the Live Conversation">
    If yes, the message continues the existing run or session. It does not start a duplicate workflow.
  </Step>

  <Step title="Evaluate Triggers">
    If no live run or session exists, Overcut evaluates triggers normally and may start a new workflow.
  </Step>
</Steps>

<Note>
  Slack thread replies can be evaluated as **Trigger Event** `thread reply` only in [registered Slack channels](/docs/integrations/slack) set to `Watch all messages`. An in-thread `@overcut` mention is a `mention` event, not a `thread reply` event.
</Note>

***

## Session Configuration

### **Comment Handling Options**

Interactive sessions provide two key configuration options that control how they respond to user comments:

<CardGroup cols={2}>
  <Card title="Listen to Comments" icon="ear">
    Controls whether the session accepts and processes new comments from users.
  </Card>

  <Card title="Keep Session Open for Comments" icon="clock-rotate-left">
    When enabled, session waits for user replies after agent responses before proceeding.
  </Card>
</CardGroup>

### **Configuration Details**

| Parameter                        | Description                                                                                                                                                             |
| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Listen To Comments`             | Whether the session accepts new comments during execution. When false, the session will not accept new comments and will end when the agent completes its current step. |
| `Keep Session Open For Comments` | Whether to pause and wait for user input after agent completes. When true, the session will wait for an additional time for user reply.                                 |
| `Max Duration (minutes)`         | How long session stays active. When the session reaches the max duration, it will end and the flow will continue to the next step.                                      |

## Session Termination

Sessions end when any of these conditions are met:

<CardGroup cols={2}>
  <Card title="Time Limit" icon="clock">
    `maxDurationMinutes` timeout reached
  </Card>

  <Card title="Manual Commands" icon="terminal">
    `/done` (ends session) or `/quit` (terminates workflow)
  </Card>

  <Card title="Slash Commands" icon="gears">
    Any other slash command terminates session and starts new workflow
  </Card>

  <Card title="New Sessions" icon="refresh">
    Starting a new session terminates the existing one
  </Card>
</CardGroup>

### **Manual Termination Commands**

Two built-in commands provide direct session control:

* **`/done`**: Completes the current session step gracefully
* **`/quit`**: Terminates the entire workflow immediately

### **Slash Command Interruption**

Other slash commands provide immediate user control:

```
User: "@overcut help with this bug"  → Session starts
User: "Can you explain the error?"   → Routes to session  
User: "/review"                      → Session terminated, review starts
```

**What happens:**

1. Session receives termination signal
2. Session cleared from database (stops comment routing)
3. Agent gets 5 minutes to wrap up gracefully
4. New slash command workflow queues or starts

***

## Best Practices

<CardGroup cols={2}>
  <Card title="Choose Appropriate Timeouts" icon="clock">
    Match session duration to expected interaction length
  </Card>

  <Card title="Use Built-in Exit Commands" icon="terminal">
    Use `/done` to end sessions or `/quit` to terminate workflows
  </Card>

  <Card title="Design for Interruption" icon="hand">
    Expect users to use slash commands to change direction
  </Card>

  <Card title="Plan Complementary Workflows" icon="puzzle">
    Design workflows that work well together when users switch between them
  </Card>
</CardGroup>

### **When to Use Sessions**

**✅ Good for:**

* Interactive help and support
* Answering questions about code changes
* Collaborative problem-solving
* Expected back-and-forth conversation

**❌ Not suitable for:**

* Independent automation tasks
* One-time analysis or reviews
* Tasks that don't require follow-up

***

## FAQ

<AccordionGroup>
  <Accordion title="Can I stop a session early?">
    Yes! Use `/done` or `/quit` commands, or any slash command to terminate gracefully.
  </Accordion>

  <Accordion title="What happens if other events occur during a session?">
    * **Comment events** (including mentions): Route to the active session
    * **Slack thread replies**: Continue the live run or session first. If no run or session is live, replies in registered channels set to `Watch all messages` can match workflows with **Trigger Event** set to `thread reply`.
    * **Slash commands**: Terminate the session and start new workflow
    * **Other events** (labels, PR opened): Create new workflows that queue normally
  </Accordion>

  <Accordion title="Can multiple sessions be active at once?">
    Only one active execution can be active at a time.
  </Accordion>

  <Accordion title="Do sessions work across all platforms?">
    Yes! Sessions work consistently across GitHub, GitLab, Jira, Bitbucket, Azure DevOps, and registered Slack channels.
  </Accordion>
</AccordionGroup>

***

## Related Documentation

<CardGroup cols={2}>
  <Card title="Agent Session Action" icon="users" href="/docs/workflows/agent-session">
    Basic session setup and multi-agent coordination
  </Card>

  <Card title="Advanced Trigger Execution" icon="gears" href="/docs/reference/trigger-execution">
    How triggers, queuing, and slash commands work
  </Card>

  <Card title="Agent Differences" icon="user-group" href="/docs/workflows/agent-differences">
    When to use different agent action types
  </Card>

  <Card title="Slash Commands" icon="terminal" href="/docs/workflows/trigger-with-slash-command">
    Setting up and using slash command triggers
  </Card>
</CardGroup>