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 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 two 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.

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 displays your premium request usage (e.g., 300/300 reqs · 0% · resets Jan 2) or ∞ reqs for unlimited entitlements.

Prompt Queue

Queue multiple prompts to run sequentially without waiting for each response. While a response is actively streaming, press Ctrl+Q to add the current input to the queue — queued prompts are processed in FIFO order after the current turn finishes, with any steering prompts for that turn applied first. Press Ctrl+X to remove the most recently added pending prompt.

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 → Agent)
• Ctrl+Y — Toggle auto-approve mode (bypasses all future permission prompts for the session)
• 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

Permission Prompts

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

• y — Allow this operation once
• a — Allow always (enables auto-approve for all future operations in this session)
• 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

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
Icon	</>	≡
Read Tools	✅ Auto	❌ None
Write Tools	✅ With approval	❌ None
Makes Changes	Yes (approved)	No
Best For	Execution	Learning

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 and review potential changes, 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 and reviewing workflows, then enable auto-approve (Ctrl+Y) for trusted operations in Agent mode. 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). KSail automatically retries transient auth failures (HTTP 429, 500–504, 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