Skip to content

USER_GUIDE.md

Latest commit

 

History

History
211 lines (133 loc) · 5.42 KB

USER_GUIDE.md

File metadata and controls

211 lines (133 loc) · 5.42 KB
Raw

Software Coach User Guide

中文指南 | Deutscher Leitfaden

Software Coach is a floating desktop assistant for learning and operating complex software step by step. It does not click buttons for you. It looks at your screenshot, combines that with your question, and returns structured guidance.

What it does today

  • explains what screen you are probably looking at
  • suggests the next step to take
  • explains why that step matters
  • shows confidence, assumptions, and unknowns
  • supports progressive coaching with I completed this step and Still stuck

The first built-in software pack is PerfView.

Quick start

  1. Launch Software Coach.
  2. Press Ctrl+Shift+Space to show or hide the floating window on Windows.
  3. Choose a screenshot source:
    • Capture Screen to hide the app and drag a region on the primary display
    • Select Local Image to use an existing image file
  4. Enter your goal or question.
  5. Click Ask Coach.

Screenshot capture

Capture Screen hides Software Coach before capture. Then:

  1. drag a box over the part of the screen you want
  2. release the mouse to confirm
  3. press Esc to cancel

Current limitation:

  • region capture works on the primary display only

Asking good questions

Good examples:

  • CPU is high. What view am I in and what should I inspect next?
  • Is this PerfView CPU Stacks or CallTree?
  • I think this is a GC Heap issue. What should I do next?
  • Does this screenshot match the expected Thread Time state?

If possible, tell the app:

  • software name
  • software version
  • your goal

That reduces wrong guidance later.

Software and version confirmation

Software Coach prefers to confirm software name and version before detailed coaching.

Behavior:

  • if you provide software and version, the app uses them
  • if you do not provide them, the app may ask you to confirm first
  • if you still do not provide them, the app may guess from the first screenshot and ask you to confirm

This is intentional. It is safer to clarify context early than to coach the wrong software.

Coach modes

  • explain: explain the current UI or view
  • guide: give step-by-step operational guidance
  • diagnose: reason about a possible problem
  • verify: check whether the current screenshot matches an expected state

Progressive coaching buttons

After a response, you may see:

  • I completed this step
  • Still stuck
  • Show more detail
  • Why?
  • Back

Use them to continue the same coaching session instead of starting over.

Settings

The app supports three provider types:

  • mock
  • openai-compatible
  • ollama

Mock

Use mock when you want the app to run without any API key or model server.

OpenAI-compatible

Use this for cloud or local endpoints that expose an OpenAI-compatible API.

Typical fields:

  • Base URL
  • Model Name

If you use a cloud provider, required API keys must come from environment variables such as OPENAI_API_KEY.

Ollama

Use this when you run a local Ollama server.

Typical fields:

  • Ollama Base URL
  • installed model list
  • custom model name

Current default local URL:

  • http://localhost:11434/v1

The app can:

  • list installed models from ollama list
  • let you choose one from the list
  • let you type a custom model name
  • if the model is missing, ask for confirmation before running ollama pull <model>
  • show install progress in Settings

Recommended local Ollama models

For software screenshot coaching, the current recommendation is:

  • qwen2.5vl:7b

Lower-resource fallback:

  • gemma3:4b

Larger alternative:

  • gemma3:12b

Privacy

By default:

  • screenshots stay local
  • screenshots are not stored
  • telemetry is off
  • remote docs are off
  • cloud models are off

What leaves your machine:

  • nothing in mock mode
  • nothing in local Ollama mode if Ollama runs on your machine
  • screenshots and text may leave your machine only if you explicitly enable and select a cloud-capable provider

Feedback

You can rate answers as helpful or not helpful. This feedback is stored locally to help future tuning.

Current limitations

  • the first real software pack is PerfView
  • screenshot region capture supports the primary display only
  • no automatic clicking or keyboard control
  • no overlay highlighting yet
  • best results currently depend on a vision-capable model
  • if confidence is low, the app will ask for more context instead of giving overconfident instructions

Troubleshooting

The app opens but I do not know the shortcut

Current Windows shortcut:

  • Ctrl+Shift+Space

Screenshot capture did not start

  • make sure the main window is visible
  • click Capture Screen
  • if nothing appears, bring the app to the foreground and try again

Ollama does not work

Check:

  • ollama serve is running
  • the base URL is http://localhost:11434/v1
  • the selected model is installed

The answer is too uncertain

Try:

  • giving software name and version explicitly
  • taking a tighter screenshot of the relevant area
  • asking a narrower question

More documents

For project architecture, development setup, testing, packaging, and extension details, see the repository developer docs:

  • README.md
  • README.zh-CN.md
  • README.de.md