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

# AI Chat and Sessions

> Learn how TeamCopilot chat sessions work, how to read diffs, and how session-level controls affect permissions and approvals.

TeamCopilot's AI chat is the main entry point for day-to-day use. From the chat tab, users can create sessions, continue older sessions, inspect file diffs, answer permission prompts, and interact with cronjob handoff sessions.

## What a chat session is

A chat session is a persistent conversation with the agent. TeamCopilot stores:

* the messages in the session
* the session title and timestamps
* pending tool and permission requests
* tracked file changes for the session
* usage data for cost and token analytics

Sessions can be reopened later from the history list or via deep links.

## Main chat behaviors

In the UI, users can:

* start a new session
* continue an existing session
* attach files from the workspace
* review tracked file diffs
* respond to permission requests
* answer agent questions when the assistant is waiting on input
* delete a session when it is no longer needed

The chat UI also supports read-state tracking so attention-needed sessions can be marked as seen.

## Deep links

The app supports session deep links through query parameters:

* `/?tab=ai&session=<session_id>` opens a specific session
* `/?tab=ai&newChat=1` opens a fresh session flow
* `/?tab=ai&draft=<text>` pre-fills a draft message

These links are useful for sending someone directly to a specific conversation state.

## File attachments

You can attach workspace files in chat messages.

Rules:

* file paths must stay inside the workspace
* paths are normalized before use
* the agent receives a file URL only after the backend validates the path

This prevents the chat UI from being used to reference files outside the shared workspace.

## Permission requests

When the agent wants to do something sensitive, TeamCopilot may create a permission request.

Users can respond with:

* `once`
* `always`
* `reject`

Permission prompts are session-scoped, and the UI removes them once answered.

## File diffs

TeamCopilot tracks file changes made during a session and exposes a diff view in the chat UI.

The diff panel is useful for:

* reviewing what the agent changed
* checking whether an edit matched the user's intent
* auditing tool-driven file changes after the session

Diffs are built from the tracked session file baseline and the current workspace state.

## Session states

Sessions can show different states in the UI, including:

* active
* pending input
* attention needed
* read
* deleted

The backend also normalizes stale tool states so interrupted or incomplete runs do not remain stuck in a misleading state.

## Cronjob chat handoff

Some cronjob runs use a chat session as the execution surface.

In those cases, TeamCopilot can:

* pause a cronjob run when it needs user attention
* resume the run later from the chat UI
* interrupt or terminate the run from the session controls

This is important for prompt-based cronjobs where the agent may need to ask for clarification before it can continue.

## Workflow sessions and hidden tool prompts

Some workflow and cronjob flows create hidden session state while they run. The UI only reveals those details when the run is surfaced in the chat view or run detail page.

That keeps the normal chat view focused on the user-facing interaction while still preserving auditability in the backend.