AI Chat Assistant

The AI Chat Assistant provides an interactive interface for cluster configuration, troubleshooting, and learning. Powered by GitHub Copilot, it understands KSail’s CLI, configuration schemas, and can execute commands with your approval.

Prerequisites

• GitHub Copilot CLI must be installed and authenticated
• Set COPILOT_CLI_PATH environment variable if the CLI is not in your PATH

Starting a Chat Session

ksail chat

This opens an interactive TUI (Terminal User Interface) with markdown rendering, syntax highlighting, and conversation history.

Command Options

Flag	Description	Default
-m, --model	Model to use (e.g., gpt-5, claude-sonnet-4, auto)	Auto-detected from config or gpt-5
-r, --reasoning-effort	Reasoning effort level for supported models (low, medium, high)	Model default
-s, --streaming	Enable streaming responses	true
-t, --timeout	Response timeout duration	5m0s
--tui	Use interactive TUI mode with markdown rendering	true

Examples:

# Use a specific model with high reasoning effort
ksail chat --model gpt-5 --reasoning-effort high

# Use auto model selection (let Copilot choose the model)
ksail chat --model auto --timeout 10m

Authentication

The chat assistant supports multiple authentication methods via environment variables:

• KSAIL_COPILOT_TOKEN - KSail-specific Copilot token (preferred)
• COPILOT_TOKEN - General Copilot token
• GitHub Copilot CLI authentication (default)

Note: GITHUB_TOKEN, GH_TOKEN, and COPILOT_GITHUB_TOKEN are intentionally filtered from the Copilot CLI child process. GITHUB_TOKEN and GH_TOKEN are general-purpose GitHub tokens that may lack Copilot-specific scopes. COPILOT_GITHUB_TOKEN, if set by a parent process (e.g., a GitHub App) with a token lacking Copilot scopes, causes immediate startup failure — KSail filters it so the Copilot SDK can manage auth via its own mechanism. User-configurable vars like COPILOT_CUSTOM_INSTRUCTIONS_DIRS are preserved.

Slash Commands

Type / in the input box to open the command picker — a floating autocomplete popup with arrow-key navigation, Enter to fire (or fill if the command takes an argument), and Tab to fill without firing.

Command	Arguments	Description
/mode	interactive|plan|autopilot	Switch chat mode
/model	model-id (optional)	Switch LLM model — opens the model picker if no ID is given
/new	—	Start a new chat session
/sessions	—	Open session history picker
/help	—	Show keyboard shortcuts and commands
/clear	—	Clear the chat viewport

Commands that accept arguments show an option picker after selection (e.g., /mode lists interactive, plan, autopilot with descriptions).

Chat Modes

Press Tab to cycle between three modes, or use /mode <interactive|plan|autopilot> to switch directly:

Mode	Icon	Read Tools	Write Tools	Makes Changes	Best For
Interactive	</>	✅ Auto	✅ With approval	Yes (approved)	Cluster operations, deploying workloads, configuration changes
Plan	≡	❌ None	❌ None	No	Learning workflows, reviewing changes
Autopilot	⚡	✅ Auto	✅ Auto (no prompts)	Yes (unattended)	Trusted or repetitive workflows

Advanced Features

Reasoning Effort

Control analysis depth with --reasoning-effort (low, medium, high) or press Ctrl+E in the TUI. Higher effort provides more thorough reasoning for complex problems but takes longer.

Auto Model Selection

Use --model auto to let Copilot choose the best available model. The TUI shows the resolved model and its billing multiplier (e.g., auto → gpt-4o (1x)).

Quota Tracking

The TUI footer displays real-time premium request quota details — for example, 45/100 reqs · 55% remaining · resets Feb 15 — or ∞ reqs for unlimited entitlements. The footer may be hidden on narrow terminals.

MCP Tool Elicitation

When an MCP tool needs additional input during execution, an inline 📋 Input Requested modal appears (and may include a source suffix) with one or more form fields. Fill in the fields and press Enter to accept, or Esc to decline. Use Tab / Shift+Tab to navigate between fields in multi-field forms.

In non-TUI mode (plain terminal), the same 📋 Input Requested elicitation request is presented as stdin prompts instead of a modal.

Infinite Sessions

Chat sessions support unlimited conversation length through automatic background compaction when the context window nears capacity.

Keyboard Shortcuts

Navigation

• Enter — Send message
• Alt + Enter — New line in input
• ↑/↓ — Navigate command history (when input is empty) or scroll viewport
• PgUp/PgDn — Scroll conversation viewport

Modes & Settings

• Tab — Cycle chat mode (Interactive → Plan → Autopilot → Interactive)
• / — Open command picker (autocomplete for slash commands)
• Ctrl+T — Expand/collapse tool execution details
• Ctrl+O — Change AI model (lazy-loaded picker)
• Ctrl+E — Change reasoning effort level
• Ctrl+H — View session history
• Ctrl+N — Start new chat session

Elicitation Modal

When an MCP tool requests additional input:

• Enter — Accept (submit form values)
• Esc — Decline
• Tab / Shift+Tab — Navigate between fields (multi-field forms)

Permission Prompts

When an operation requires approval, an inline permission modal appears:

• y — Allow this operation once
• a — Allow always (switches to Autopilot mode; operations are auto-approved while Autopilot is enabled)
• n / Esc — Deny

Read and URL operations are auto-approved without a prompt.

Prompt Queue

• Ctrl+Q — Queue current input as a pending prompt (processed after the active response completes)
• Ctrl+X — Delete the most recently added pending prompt (including steering prompts added by pressing Enter while a response is streaming)

Output

• Ctrl+R — Copy latest assistant response to clipboard

Help & Exit

• F1 — Toggle help overlay
• Esc — Close modals or cancel current operation
• Ctrl+C — Force quit

Configuration

Set your preferred model and reasoning effort in ksail.yaml:

spec:
  chat:
    model: claude-sonnet-4.5  # or gpt-5, gpt-4o, auto, etc.
    reasoningEffort: medium    # low, medium, or high

If not set, the assistant uses the model specified via --model flag or defaults to gpt-5.

Session Management

View Past Sessions

Press Ctrl+H to open session history. Navigate with ↑/↓, filter with /, rename with r, delete with d, or select with Enter. Sessions persist in ~/.ksail/chat/sessions/.

Start New Session

Press Ctrl+N to start a fresh conversation. Previous sessions are automatically saved.

Diagnosing a Misbehaving Cluster

Ask natural-language questions like “why is my cluster broken?” and the assistant calls cluster_read → diagnose, surfaces failing pods and NotReady nodes, then explains the root cause and suggests remediation.

You can also run the command directly:

ksail cluster diagnose          # human-readable
ksail cluster diagnose --output json   # machine-readable (healthScore and findings[])

The command works with Vanilla, K3s, Talos, and VCluster, and exits 0 even when failures are reported (non-zero means the Kubernetes API could not be queried — e.g., the cluster is unreachable or credentials lack sufficient permissions).

Troubleshooting

Chat won’t start: Ensure GitHub Copilot CLI is installed (which copilot) and authenticated (copilot auth login).

Model not available: Try different models (--model gpt-5) or use auto-selection (--model auto).

Timeout errors: Increase timeout for complex operations (--timeout 15m).

Authentication errors: Authenticate with copilot auth login and use KSAIL_COPILOT_TOKEN or COPILOT_TOKEN for KSail-specific auth. See Authentication for details on token filtering. KSail automatically retries transient auth failures (HTTP 429, 5xx responses, and network errors) up to 3 times with exponential backoff — auth status check failed after N/3 attempts messages indicate a persistent issue requiring action.

See Also

• MCP Server — Expose KSail to external AI assistants (Claude Desktop, Cursor, Windsurf, VS Code Copilot) via the Model Context Protocol
• Using KSail with AI Assistants — Step-by-step setup guide for connecting external AI clients