BALLKNOWER KNOWLEDGE BASE

Documentation.

A practical guide to Ballknower: a lightweight Windows desktop assistant built with WPF and .NET 8.

Project status

This site is a static documentation front end. The roadmap is intentionally not public. Feature behavior may evolve as the app develops.

Overview

Ballknower combines an AI chat interface with local desktop tools and a floating, blurred desktop experience. It is designed to be useful without taking over your workspace.

WindowsWPF.NET 8BYOK

Windows startup: Ballknower registers itself for the current Windows user and starts automatically when Windows signs in. The registration does not require administrator privileges.

Getting started

Open Ballknower Agent.slnx in Visual Studio.
Ensure the .NET 8 SDK and Windows desktop development support are installed.
Set Ballknower Agent as the startup project, then build and run.
Type into the pill-shaped input. Enter a message to chat, or type / to browse built-in commands.

To run a built build outside Visual Studio, launch the executable from the project's build output folder. Keep the surrounding output files together.

Interface

Floating input: the main entry point for chat and commands.
Chat: user messages appear on the right; assistant messages appear on the left.
Command suggestions: typing / opens autocomplete. Select a suggestion with the keyboard or mouse.
Markdown: assistant responses support headings, lists, blockquotes, bold, italic, inline code, fenced code blocks, and clickable HTTP(S) Markdown links.
Adaptive presentation: text colors adapt to the backdrop, with background blur for a glass-like appearance.
Global keyboard shortcut: use the configured modifier + Windows key combination to reopen/focus Ballknower. The default is Alt+Win; the modifier can be configured in settings.
/see: reveals the desktop without the blur.

Style & themes

The Style tab in Settings controls Ballknower's visual presentation. Changes are staged while Settings is open and are written to the saved configuration when you click Save.

Presets: Default, Blue, Purple, Green, Sunset, or Custom.
Light / dark colors: enter #RRGGBB or #AARRGGBB values for backgrounds and text. In Unified palette mode, editing either side mirrors the corresponding color to both light and dark states. Separate Light / Dark mode lets you edit each state independently.
Fonts: choose from Segoe UI, Aptos, Calibri, Consolas, Cascadia Code, Trebuchet MS, or Georgia.
Animated effects: controls the app's style animations.
Animated rainbow outline: adds a rotating rainbow border around the input pill.
Soft glow: adds a subtle glow to the input and conversation panels.
Autocomplete: command suggestions inherit the selected font and adaptive theme colors.

If a custom color is entered, the preset automatically becomes Custom. Click Save to persist the changes; Cancel discards them.

AI settings & presets

The AI & Models tab controls the active provider, model, API key, and saved AI presets. Changes are staged while Settings is open and are written to the saved configuration when you click Save.

Saved AI presets

Name: choose a label for the preset, such as a provider/model combination.
Provider and model: each preset stores the selected AI provider and model.
API key: the preset can store its API key as Windows DPAPI-protected data rather than plaintext.
Load: selecting a saved preset applies its provider, model, and stored credential to the current AI settings.
Rename / delete: saved presets can be renamed or removed from the preset list.

Preset metadata can be exported with settings, but the encrypted credential data is tied to the Windows user protection context. Never treat an exported settings file as portable plaintext credentials or commit one to source control.

Search provider

The Search Provider setting controls which public search engine the web_search tool uses. The available providers are DuckDuckGo and Bing. No search API key is required for either built-in provider.

DuckDuckGo: uses DuckDuckGo's HTML search page.
Bing: uses Bing's public search page.

The selected provider is stored in Ballknower's local settings and is applied when the application starts. If a provider request fails, the tool reports the provider error instead of silently switching to another provider.

If one provider has a network, TLS, or availability problem, open Settings and switch providers, then click Save before trying the search again.

Built-in commands

Commands start with a slash. Names are case-insensitive.

Command	What it does
`/help`	Lists built-in commands and configured shortcuts.
`/settings`	Opens Ballknower settings.
`/logs`	Opens the Ballknower error logs.
`/clear`	Clears the current chat while preserving the system prompt.
`/confetti`	Displays confetti.
`/see`	Shows the desktop without the blur.
`/pin`	Keeps Ballknower visible while switching apps.
`/unpin`	Returns to hiding Ballknower when it loses focus.
`/shutdown`	After confirmation, exits Ballknower and stops its background input handler.

Keyboard shortcut & background process

Ballknower can be brought back to the foreground with its global keyboard shortcut (default Alt+Win; the modifier is configurable in settings). The background process must still be running for the shortcut to work.

Important: closing the pinned overlay with Escape and confirming closes only the overlay; the background process stays running. Use /shutdown to exit completely.

Configured shortcuts

If a command is not built in, Ballknower checks user-configured shortcuts in settings. A configured shortcut is invoked as /shortcutname.

AI tools

The assistant can call registered tools in response to natural-language requests.

`create_file`

Creates a text file and parent directories as needed.

Arguments: path, content
Confirmation: Not required. Existing files may be overwritten.

`delete_file`

Deletes a file at the requested path.

Arguments: path
Confirmation: Required before execution.

`read_file`

Reads text from an existing file.

Arguments: path
Confirmation: Not required.

`list_directory`

Lists immediate files and subdirectories, up to 200 entries.

Arguments: path
Confirmation: Not required.

`move_file`

Moves or renames an existing file without overwriting an existing destination.

Arguments: source, destination
Confirmation: Required before execution.

Shortcut creation & app launching

Ballknower can create shortcuts and open applications through its desktop tooling.

`web_search`

Searches the public internet and returns result titles, URLs, and snippets.

Arguments: query — concise query, capped at 400 characters
Results: Up to five results

API keys & security

Ballknower uses a bring-your-own-key model. Saved credentials are protected using Windows Data Protection API (DPAPI). Treat API keys as sensitive and never commit them to source control.

Advanced: Jailbreak

In Settings → AI & Models → Advanced, the Jailbreak checkbox controls whether the optional prompt field is shown. When enabled, the saved prompt is prepended to the first user message sent after launching Ballknower.

Tool safety restriction: while Jailbreak is enabled, the application exposes and permits only the web_search AI tool. Unchecking Jailbreak restores the normal tool set.

File path notes

Use familiar-folder aliases such as ~/Desktop, ~/Documents, and ~/Downloads where supported.
Use full paths for source and destination paths when requested.
File operations may fail because of missing paths, permissions, invalid destinations, or operating-system errors.

●

That’s the current lay of the land.

Back to Home →