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 (applies 10% discount when available)
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 and GH_TOKEN are intentionally filtered as they are general-purpose personal access tokens that may lack Copilot-specific scopes, which can cause authentication errors.

Chat Modes

Press Tab to cycle between three modes:

Agent Mode (</>)

Executes both read and write operations. Write operations (create, modify, delete) require explicit confirmation. Use for cluster operations, deploying workloads, and configuration changes.

Plan Mode (≡)

Blocks all tool execution and provides step-by-step explanations without making changes. Use for learning workflows or reviewing potential changes before execution.

Ask Mode (?)

Executes read-only tools (inspect, list, describe) while blocking writes. Use for troubleshooting and investigating cluster state without risk of changes.

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 for automatic model selection with 10% discount (when available). The TUI shows the resolved model (e.g., Model: auto → gpt-4o).

Quota Tracking

The TUI displays your premium request usage (e.g., 300/300 reqs · 0% · resets Jan 2) or ∞ reqs for unlimited entitlements.

Infinite Sessions

Chat sessions support unlimited conversation length through automatic background compaction using a background compaction threshold of 80% (0.80) and a buffer exhaustion threshold of 95% (0.95) of the context window.

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 (Agent → Plan → Ask → Agent)
• Ctrl+Y — Toggle auto-approve mode (bypasses permission prompts)
• 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

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

Usage Tracking

When available, the footer displays real-time quota information showing used/total requests, remaining percentage, and reset date (may be hidden on narrow terminals). Example: 45/100 reqs · 55% · resets Feb 15. For unlimited premium quota, shows ∞ reqs instead of numeric total.

Mode Comparison

Feature	Agent Mode	Plan Mode	Ask Mode
Icon	</>	≡	?
Read Tools	✅ Auto	❌ None	✅ Auto
Write Tools	✅ With approval	❌ None	❌ None
Makes Changes	Yes (approved)	No	No
Best For	Execution	Learning	Investigation

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.

Common Workflows

Use Plan mode (≡) to learn workflows, Ask mode (?) for safe troubleshooting, and Agent mode (</>) to execute operations with approval. Press Tab to switch modes as needed.

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.

Tips

Start with Plan mode for learning, use Ask mode for safe troubleshooting, and enable auto-approve (Ctrl+Y) for trusted operations. Adjust reasoning effort (Ctrl+E) based on task complexity, use --model auto to optimize costs, and filter session history (Ctrl+H then /) to find past conversations.

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 Copilot CLI (copilot auth login), use KSAIL_COPILOT_TOKEN or COPILOT_TOKEN environment variables, and avoid GITHUB_TOKEN/GH_TOKEN (may lack Copilot scopes).

See Also

• CLI Flags Reference — Complete flag documentation
• Configuration — Chat configuration options
• MCP Server — Expose KSail to other AI assistants