Skip to main content
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. 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.