winget install --id=sasler.TroubleScout -e TroubleScout is a .NET CLI tool using the GitHub Copilot SDK to diagnose Windows Server issues using safe, read-only PowerShell commands.
TroubleScout is a .NET CLI tool that uses the GitHub Copilot SDK to provide an AI-powered Windows Server troubleshooting assistant. Describe your issue in natural language, and TroubleScout will investigate using safe, read-only PowerShell commands.
Get-* commands execute automatically; remediation commands require explicit approval with a three-option prompt (Yes / No / Explain)~$X.XX est., GitHub shows ~X.X premium reqs--server srv1 --server srv2 (or --server srv1,srv2); all sessions are established at launch/server or via connect_server tool to avoid PowerShell double-hop issues(ESC to cancel) as a persistent hint/reasoning with compatible models to persist a preferred reasoning effort or switch back to automatic reasoning/model so you always know which provider (GitHub Copilot or BYOK) will be used/model shows GitHub premium multipliers, BYOK pricing (with LiteLLM fallback estimates), context-window metadata, and a clearer selected-model summary/status keeps provider, usage, context, MCP, and skill details grouped and easy to scanFor pre-built release:
Windows x64 or Windows ARM64 operating system
Authentication mode:
OPENAI_API_KEY) with --byok-openaiGitHub Copilot CLI - Bundled with TroubleScout releases; install separately only if you run from source without bundled assets:
On Windows: PowerShell 6+ is required by Copilot CLI docs (PowerShell 7+ recommended)
Node.js 24+ (LTS recommended) is only needed when using npm-based Copilot CLI installs - Download
> Important: TroubleScout release packages include architecture-specific Copilot CLI assets for bundled use.
For building from source:
> Note: The pre-built release includes a self-contained .NET runtime, so you don't need to install .NET SDK unless you're building from source.
TroubleScout.exe (and runtimes/ if present) to a directorycopilot login onceOPENAI_API_KEY and pass --byok-openaiTroubleScout.exe from the command line> Note: The release includes a self-contained .NET runtime - no .NET SDK installation required!
# Clone the repository
git clone https://github.com/sasler/TroubleScout.git
cd TroubleScout
# Build the project
dotnet build
# Run the application
dotnet run
Build a self-contained executable:
dotnet publish -c Release -r win-x64 --self-contained true -p:PublishSingleFile=true
# Output: bin\Release\net10.0\win-x64\publish\TroubleScout.exe
dotnet publish -c Release -r win-arm64 --self-contained true -p:PublishSingleFile=true
# Output: bin\Release\net10.0\win-arm64\publish\TroubleScout.exe
Validate the WinGet manifest for a release locally:
pwsh .\Tools\Validate-WinGetRelease.ps1 -Version 1.9.0
# Using pre-built release
TroubleScout.exe
# Using source build
dotnet run
# Troubleshoot a remote server
TroubleScout.exe --server myserver.domain.com
# or
dotnet run -- --server myserver.domain.com
# Connect to multiple servers at startup
TroubleScout.exe --server srv1 --server srv2 --server srv3
# or comma-separated
TroubleScout.exe --server srv1,srv2,srv3
# Preconnect a single startup JEA session
TroubleScout.exe --server server1 --jea server2 JEA-Admins
# Single prompt execution for scripting (pre-built release)
TroubleScout.exe --server localhost --prompt "Check why the SQL Server service is stopped"
# Using source build
dotnet run -- --server localhost --prompt "Check why the SQL Server service is stopped"
--server (-s): Target server name or IP (default: localhost); repeatable or comma-separated for multi-server (e.g., --server srv1 --server srv2 or --server srv1,srv2)--jea: Preconnect a single JEA session at startup (--jea server1 JEA-Admins)--model (-m): AI model to use (e.g., gpt-4.1, claude-sonnet-4.6)--prompt (-p): Initial prompt for headless mode--mcp-config: MCP config JSON path (default: %USERPROFILE%\\.copilot\\mcp-config.json)--skills-dir: Skills root directory (repeatable, default: %USERPROFILE%\\.copilot\\skills when present)--disable-skill: Disable a loaded skill by name (repeatable)--debug (-d): Show technical diagnostics and exception details--byok-openai: Use BYOK mode with OpenAI provider instead of GitHub auth--openai-base-url: Override OpenAI base URL (default: https://api.openai.com/v1)--openai-api-key: Provide OpenAI API key directly (or use OPENAI_API_KEY)--version (-v): Show app version and exit--help (-h): Show help informationYou can specify which AI model to use with the --model option:
# Use a specific model
dotnet run -- --model gpt-5.3-codex
# Use Claude
dotnet run -- --model claude-sonnet-4.6
Available models depend on auth mode:
In the interactive TUI, /model now:
/models~ prefix)ESC to keep the current model and return to the promptFor models that advertise reasoning-effort support, TroubleScout now exposes a dedicated /reasoning command:
/reasoning opens an interactive picker/reasoning high (or another supported value) saves a specific effort level/reasoning auto clears the override and returns to automatic/default model behaviorThe active reasoning setting is shown in the selected-model summary, /status, and the post-response status bar.
After each AI response, the status bar shows cumulative session usage:
Session: 12.5k in / 8.2k out | ~$0.04 est. ā cost estimated from LiteLLM pricing dataSession: 12.5k in / 8.2k out | ~2.5 premium reqs ā based on model multiplierSystem prompt sections can be customized via the /settings configuration file. When the file is first created or normalized, TroubleScout now writes the built-in prompt sections into settings.json so you can edit them in place:
{
"SystemPromptOverrides": {
"investigation_approach": "Your custom investigation instructions here"
},
"SystemPromptAppend": "Additional instructions appended to the system message"
}
Available override keys: investigation_approach, response_format, safety, troubleshooting_approach.
TroubleScout can load MCP servers and skills through Copilot SDK session configuration.
%USERPROFILE%\\.copilot\\mcp-config.json%USERPROFILE%\\.copilot\\skills if that directory exists/status or /capabilities to see configured MCP servers/skills and runtime-used MCP servers/skills.Examples:
# Use default MCP config (%USERPROFILE%\\.copilot\\mcp-config.json) and skills (%USERPROFILE%\\.copilot\\skills, if present)
dotnet run -- --server localhost
# Use a custom MCP config path
dotnet run -- --mcp-config C:\\path\\to\\mcp-config.json
# Add additional skill directory and disable a skill
dotnet run -- --skills-dir C:\\skills --disable-skill experimental-feature
| Category | Description | Example Commands |
|---|---|---|
| System | OS info, uptime, hardware specs | Get-ComputerInfo, Get-CimInstance |
| Events | Windows Event Log analysis | Get-EventLog, Get-WinEvent |
| Services | Windows service status | Get-Service |
| Processes | Running processes and resource usage | Get-Process |
| Performance | CPU, memory, disk metrics | Get-Counter |
| Network | Network adapters and configuration | Get-NetAdapter, Get-NetIPAddress |
| Storage | Disk space and volume health | Get-Volume, Get-Disk |
TroubleScout uses a permission-based security model:
Get-* commands (read-only)Format-*, Select-*, Where-*, Sort-*Set-*, Start-*, Stop-*, Restart-*Remove-*, New-*, Add-*, Enable-*, Disable-*When approval is required, a three-option prompt is shown: Yes (execute), No (skip), or Explain (show command details before deciding).
Get-Credential (sensitive credential handling)Get-Secret (secret management)| Command | Description |
|---|---|
/help | Show the full interactive command reference |
/status | Show provider, model, usage, and capability details |
/clear | Start a new AI session |
/settings | Open settings.json, then reload prompt/safety config |
/model | Choose another model/provider and session handoff mode |
/reasoning | Set or clear reasoning effort for supported models |
/mode | Change PowerShell execution mode |
/server | Connect to one or more additional servers |
/jea [server] [name] | Connect to a JEA endpoint |
/login | Run Copilot login from the app |
/byok ... | Configure OpenAI-compatible BYOK mode |
/capabilities | Show configured and used MCP servers / skills |
/history | Show PowerShell command history |
/report | Generate and open the HTML session report |
/exit or /quit | End the session |
Use /byok env [model] (or /byok [model]) to enable OpenAI-compatible BYOK. TroubleScout fetches available models from that endpoint and uses the same model picker as /model.
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā
ā TroubleScout CLI ā
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā¤
ā āāāāāāāāāāāāāāāāā āāāāāāāāāāāāāāāāāāāāāāāāāāā ā
ā ā Spectre. ā ā GitHub Copilot SDK ā ā
ā ā Console TUI ā ā (JSON-RPC Client) ā ā
ā āāāāāāāāāāāāāāāāā āāāāāāāāāāāāāāāāāāāāāāāāāāā ā
ā ā ā ā
ā ā¼ ā¼ ā
ā āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā ā
ā ā TroubleshootingSession ā ā
ā ā - Session management ā ā
ā ā - Event handling (streaming) ā ā
ā ā - Tool execution ā ā
ā āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā ā
ā ā ā ā
ā ā¼ ā¼ ā
ā āāāāāāāāāāāāāāāāā āāāāāāāāāāāāāāāāāāāāāāāāāāā ā
ā ā PowerShell ā ā DiagnosticTools ā ā
ā ā Executor ā ā (AI Functions) ā ā
ā ā (Local/WinRM)ā ā ā ā
ā āāāāāāāāāāāāāāāāā āāāāāāāāāāāāāāāāāāāāāāāāāāā ā
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā
ā
ā¼
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā
ā Copilot CLI (SDK Server) ā
ā copilot --server --stdio ā
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā
ā
ā¼
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā
ā GitHub Copilot API ā
ā (AI Language Model) ā
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā
| Variable | Description |
|---|---|
COPILOT_CLI_PATH | Custom path to the Copilot CLI executable |
When troubleshooting remote servers:
WinRM must be enabled on the target server:
Enable-PSRemoting -Force
Windows Integrated Authentication is used (Kerberos/NTLM)
Network connectivity on port 5985 (HTTP) or 5986 (HTTPS)
Install or update GitHub Copilot CLI using the official setup guide:
If you still see startup failures, verify the CLI and re-authenticate:
copilot --version
copilot login
References:
TroubleScout requires Node.js 24+ for current Copilot SDK/CLI builds.
On Windows, install/update Node LTS:
winget install --id OpenJS.NodeJS.LTS -e --accept-package-agreements --accept-source-agreements
Restart the terminal.
Install or update Copilot CLI:
Re-authenticate:
copilot login
If you run TroubleScout from source, update the SDK package:
dotnet add package GitHub.Copilot.SDK --version
dotnet build
copilot interactive modeMIT
Contributions are welcome! This repository has branch protection enabled on the main branch to maintain code quality.
Before contributing:
feature/, fix/, docs/, etc.Quick Start:
git checkout -b feature/your-featuregit commit -m "āØ Add your feature"All pull requests require:
Releases are automatically published via GitHub Actions when version tags are pushed. If WinGet automation is configured, a follow-up workflow also opens or updates the winget-pkgs PR after the Release workflow completes. See RELEASE-PROCESS.md for detailed instructions and required setup for the v1.9.0 release flow and beyond.
See CONTRIBUTING.md for complete guidelines.
/settingssettings.json