General

Welcome splash

• fullsize shows one picture filling the screen, and ←/→ step through the set. Pressing Delete twice on an empty line moves one of the profile's own pictures into the folder's .trash, where it is never shown; move it back to restore it.
• tiled shows thumbnails at Image thumbnail size, as many as fit; ←/→ page through them and a double-click opens one.
• Pictures in the profile's splash\ folder (created for you) replace the built-in ones.
• /splash shows the splash whatever the setting says: tiled when it is tiled, otherwise one picture.

Embedded

A model the app downloads and runs itself on llama.cpp's llama-server, for when no other server is around. The catalog has Gemma 4 from the small E2B to the 31B, Meta's Muse Glimmer 30B, Qwen3.6 35B A3B, and Qwen3.8 27B (also in NVFP4, a 4-bit format for NVIDIA Blackwell GPUs).

• Installing: open the Embedded models catalog on this tab. Each row says installed · 4.2 GB, download · 4.2 GB for one not yet downloaded, or how far a paused download got. Install downloads the model in the background (📥, a spinner and its percentage show on the hint row; double-click 📥 to pause) and switches to it when it's done, unless you picked another server in the meantime.
• Using: /server (and the startup picker) lists one Embedded row per installed model, after the servers it found. /server embedded lists the installed embedded rows alone.
• Loading: while the model starts, the hint row shows 🦙 starting <model> and then 🦙 loading <model>. Ctrl+C or a double-click on the spinner and its label cancels the load (a double-click on the token count beside it still opens /usage); ESC does nothing there. In the meantime the input row, the toolbar and the shortcuts work as they do while a reply runs: panes open over the load, /clear, /new, /splash, /rewind and /exit cancel it first, and the commands that wait for a reply (/server, /model, /profile, /theme and the like) wait for the load to end, as does /sampling, which edits the model being loaded. A /reasoning level picked meanwhile applies once the model has loaded. A cancelled load treats the queue as a cancelled reply does (Queue cancel mode).
• First start: with no URL set, LLM server scan mode disabled and no model installed yet, the app opens straight to Embedded models at startup, so you can download a model right away (ESC twice goes back to the chat).
• Reading a row: builds of one model share its name, so each row also shows its quantisation (how finely the weights are compressed: lower numbers are smaller and a little less accurate). The last columns mark what a model can do: ⚡ a drafter (the Drafter column below), 👁️ images and 🛠️ tool calls, following Embedded drafter and Embedded vision. Then comes ⛓️‍💥 for an uncensored build or 💢 for an aggressive one (HauhauCS's own word in its name), blank for the others.
• Every model reads images (its vision projector is part of the download) and calls tools.

The Drafter column says how a model drafts ahead (see Embedded drafter). MTP (file): a small multi-token prediction drafter file, downloaded with the model. MTP (built in): the drafting head is part of the model's own weights, so there is nothing extra to download. DFlash (file): a separate 1.6 GB DFlash drafter that drafts 16 tokens at a time. —: no drafter.

• The Qwen3.8 27B NVFP4 builds keep most weights in NVFP4, NVIDIA's 4-bit format. It needs the CUDA backend on an NVIDIA Blackwell GPU (RTX 50 series or newer); elsewhere these builds are slow or don't load. Their tiers (VERY-LOW to HIGHEST) share one NVFP4 body and differ in the output head, the token embedding and the MTP head, except HIGHEST, which keeps more in Q8_0/BF16.
• Each file is checked against the SHA-256 Hugging Face publishes for it. A paused (double-click 📥) or interrupted download keeps what has arrived, and picking the model again resumes it. The drive needs room for the rest plus 1 GB to spare.
• The first start downloads llama.cpp itself (build b11258: 577 MB for CUDA with its runtime, 33 MB for Vulkan, 19 MB for the CPU). If auto picked CUDA and it doesn't start, the app says so and tries Vulkan.
• The server listens only on 127.0.0.1, on a random port, with a new key at each start. It keeps running while you switch reasoning or change a setting it doesn't depend on, and restarts when one it depends on changes. It stops when you pick another server, turn Embedded LLM server enabled off, or quit. If the app crashes, Windows stops it too.
• Models live in models\llm\<id>\ and llama.cpp in llama\ under the home folder. /about shows both.
• /model on the embedded server lists the installed embedded models. One server runs at a time, apart from the extra servers of a multi-server botchat (Botchat multi-embedded). A /botchat multi bot whose profile points at embedded shares the running model or, under multi-server, gets a server of its own for another model. Extra servers stop when the chat ends (with Botchat multi-embedded kill on), with /botchat --kill, when Embedded LLM server enabled is turned off, when their model is removed, or when you quit.
• Each model runs with the sampling its card recommends (Gemma 4: temperature 1.0, top-p 0.95, top-k 64; HauhauCS's QAT Balanced builds: 0.6, 0.9, 64; Qwen: 1.0, 0.95, 20; Muse Glimmer: 1.0, 0.95, 64); /sampling overrides them as for any server.
• Memory: the 12B models need about 8 GB of VRAM plus the context at Q4, about 10 and 12 GB at Q5 and Q6, and about 25 GB at BF16. The 26B A4B, 31B, Muse Glimmer and Qwen models need roughly their download size plus the context (or a partial offload to the CPU through Embedded GPU layers). E2B and E4B fit in less. The 26B A4B and Qwen3.6 35B A3B are mixture-of-experts models: only 4B and 3B of their weights are used per token, so they run faster than their size suggests.
• HauhauCS's Qwen3.8 repository also ships a FastMTP file. It needs a patched llama.cpp, so the app uses the drafter built into the model instead.
• Windows x64 only. The small models (E2B, E4B) call tools less reliably than the bigger ones.

LLM

Sampling per model

Sampling settings control how the model picks its words (temperature, top_p and so on). Until you override them, every request leaves sampling to the server and the model's own defaults.

• /sampling (or the LLM sampling row) opens a pane with one tab per model: the connected model first, then any model (*), then every other model you have set something for.
• Each field comes from the model's own tab, else from *, else it is not sent at all. Switching models with /model picks up the other model's values by itself.
• Everything is read at the next turn, so nothing reconnects, and the pane also opens while a reply runs.
• A blank value clears a field. A value out of range is refused, never clamped.

Server defaults. Where the server says what it applies by default, the connected model's tab shows it dim, as 0.8 (server), and the tab's caption names the source. llama.cpp reports its defaults on /props, and Ollama its Modelfile's on /api/show. vLLM, SGLang and LM Studio report none. For vLLM and SGLang, LLM sampling from Hugging Face reads the model card's generation_config.json instead (0.6 (Hugging Face)). The defaults are asked for once, when the pane first opens after a connect.

What servers accept.

• A server ignores the fields it does not know. Ollama's /v1 endpoint takes only the four OpenAI ones.
• The extra body may not set the fields the app writes itself (model, messages, tools, stream, reasoning_effort, …) or one of the named fields above. Its chat_template_kwargs is merged with the app's own, and the app's enable_thinking and preserve_thinking win.
• The Claude API is not affected.

Without the pane. /sampling temperature 0.6, /sampling top_k clear, /sampling extra {"seed":42} and /sampling clear change the connected model's values. NEONSIDEKICK_LLM_SAMPLING overrides every model for one run. Whenever something is set, the log's connect line is followed by Sampling: ….

TTS

Speech output sets up in the background (🔈 on the hint row), so the first-use Kokoro download doesn't block the input line. Replies are text-only until it's ready.

STT

Voice input sets up in the background (🎧 on the hint row), so the first-use Whisper download doesn't block the input line. Until it's ready, push-to-talk says it's still setting up.

Sessions

Botchat

Botchat pictures

• The two botchat workflows can be any installed workflow of their kind, whether or not it's ticked in ComfyUI workflows offered (that list is for the main chat only). Pictures are drawn at Image thumbnail size. With no txt2img workflow set, a notice says so once per chat.
• automatic: after each reply, the model writes an image prompt from it, in the style the workflow's model family expects, and the app draws it. The bots get no tool. If the prompt writer writes a generate_image call instead, its prompt is used; words before a tool call it writes ("Let me check the tags first.") are never the prompt.
• autonomous: the bots get generate_image, limited to the two botchat workflows. If a reply talks about a picture the bot never drew (or its call failed), the app draws it. A tool call a bot writes out as text (including the <tool_call> markup some models write) is run as a real call (not when the same reply also made a real call) and never shown or spoken. A load_skill a bot writes with none offered is only taken out.
• Reworks: once the chat has a picture and an img2img workflow is set, whoever writes the next prompt chooses between a new picture and a rework. In automatic, the prompt writer answers REWORK (or REWORK n). In autonomous, the bot sees the pictures' paths in its turn and passes one to generate_image as image. A picture that is still rendering can't be reworked yet.
• Async on: 🖼️ (🎨 for image-to-image) sits in the hint row's glyph strip while a picture renders, with a count when several are pending (🖼️ 2). Each picture is labelled with whose reply it shows. With no voice (TTS output off), pictures go to ComfyUI one at a time, each a second after the previous one is finished.
• Async off: ESC while a reply is held back cuts that bot short, as it would a streaming reply. ESC under the picture's spinner skips just that picture.
• Either way, the image prompt is written before the next turn.
• Skills: with Botchat skills enabled, the automatic prompt writer may load a skill (and a file it bundles) before writing, so a topic like "use the pony-prompts skill for pictures" is followed from the first picture. Each load shows as a skill line. To use a skill without relying on the model to load it, use Botchat preloaded skills.

Offered

Lists the loaded skills with their scope (profile, global or external) and description, then any shadowed duplicates and skipped folders (with the reason). Enter on a skill lets you:

• move it between the profile and global skill folders;
• rename it (forced to lower-case-with-hyphens; a name already taken is refused);
• edit its SKILL.md in your editor (the change applies the next time the skill loads);
• delete it (after a confirmation).

Reflection

Options

Installing skills

/skills add brings in skills written in the Agent Skills format, the same folders other agents use.

• What it takes:

  • Search words (/skills add pdf) look the skill up on skills.sh, the public directory. agentskills.io itself hosts only the specification.
  • owner/repo offers every skill in a GitHub repository.
  • owner/repo/skill names one skill. This is the id a search shows, so you can type a result back.
  • A github.com/…/tree/<branch>/<path> or …/blob/<branch>/<path>/SKILL.md link narrows the search to a folder.
  • Any https://…/*.zip link is downloaded as it is.

• Where it comes from: the repository isn't downloaded whole.

  • The app gets its file list from the GitHub API at the branch's latest commit. That takes two requests; GitHub allows 60 an hour without a token.
  • It finds every SKILL.md, wherever it sits (skills/, .claude/skills/, .agents/skills/, the root), and fetches only those files. Once you confirm, it fetches the chosen skill's files. Everything comes from raw.githubusercontent.com, pinned to that commit.
  • A repository with more than 100 skills must be narrowed to one (owner/repo/skill or a folder link).
  • If the API is rate-limited, unreachable or returns a truncated list, the app falls back to GitHub's zip of the branch (up to 50 MB).

• Network rules: Web browser network mode applies (under local_area_network nothing is fetched). The Web tools switch doesn't, because you typed the command, not the model.

• Before anything is written: you see a preview of the skill: its description, source and commit, other frontmatter such as allowed-tools, the file list, any scripts, and the start of its instructions. The install is refused when:

  • a path could escape the folder, or is not a valid Windows path;
  • two files differ only by case;
  • it has more than 200 files, over 20 MB in total, or any file over 5 MB.

  Symbolic links are left out.

• Where it goes: the folder lands under the profile's or the global skills folder, named after the skill. A .neon-source.json beside its SKILL.md records the repository, path, commit and date. Bundled scripts run only through run_command and its approval, like any other command.

• Name collisions: a name already in use is refused; rename or delete the existing skill on /skills first. The exception is a skill installed earlier from the same repository and path: adding it again replaces it where it is (an update).

Skill records and purging unused skills

The app keeps a record of every global and profile skill in skills.db in the home folder, shared by every profile. Each record holds the skill's folder, whether it is global or the profile's, when it was created, last modified and last used (its instructions loaded with load_skill, or preloaded by /botchat), and a category that is empty for now.

• When records change: the model's skill_editor, a reflection, /skills add and the /skills pane's move, rename and delete update the record as they act.
• Catching outside changes: at startup and whenever a profile loads, the app checks the folders. A skill folder with no record gets one, dated from its SKILL.md's created and modified times. A newer SKILL.md moves the modified date (an edit in your editor). A record whose folder is gone is removed. Folders are matched by name.
• External skills (.agents\skills) are not recorded and never purged.

/skills purge list <age> lists the skills not used for that long, and changes nothing. /skills purge commit <age> deletes them, the folder and the record, after a yes/no that lists them. The age is days (30) or a duration (12h, 90m, 1d 6h), as /sessions purge older takes it. A skill that was never used counts from its last change, so one you just wrote isn't purged before it gets a chance. Only the global skills and the loaded profile's own are considered. A global skill used in any profile counts as used. There is no purge all: delete the folders yourself.

Offered

Every tool, grouped (Clock, Timers, Files, GitLib, Shell, Obsidian, SQL, ComfyUI, Claude, Web, Memory, Skills, Sessions, Questions), with the description the model reads. Enter or Space turns one tool on or off. A group whose switch is off is shown dim. In a new profile, gitlib_delete (loses branches, tags and stashes), zip and unzip start off.

Web

Files

Shell

Shell guards

• Approval (ask): the pane offers Deny, Allow once, Allow the prefixes for this session, or Allow them always (added to Shell allowed commands).

  • A prefix is the program plus its subcommand for git, dotnet, npm, pip, gh, docker, cargo, go, winget and the like; otherwise it is the program alone.
  • --yolo (one launch) and NEONSIDEKICK_COMMAND_POLICY override the policy, so a scripted --headless run can use yolo.

• Path police keeps shell commands inside the working directory. It reads the text of a run_command line, an execute_code script, or what process writes to a background process.

  • It refuses an absolute path not under the working directory (C:\…, a UNC share, a rooted /etc/hosts), a .. that climbs out, ~, or a folder variable (%USERPROFILE%, $env:TEMP, $HOME, Path.home()…).
  • The model gets Error: outside the working directory: '…' and the transcript line shows 👮. The tool descriptions and operating rules tell the model the shell stays inside the working directory.
  • It reads text, not what runs: a computed path isn't seen, and a cmd switch (dir /s) or a URL isn't a path.
  • When it's off, any path goes. Nothing tells the model it may leave the working directory, so it doesn't try unless asked.
  • --no-police (one launch) and NEONSIDEKICK_SHELL_POLICE override it; --yolo never turns it off.

• Prefer native tools: the operating rules tell the model to use run_command only when no other tool does the job. They name the tools offered that turn and the shell commands each replaces:

  • cat/type/Get-Content/dir/ls/grep → read_file/search_files
  • git status/log/diff/add/commit → the GitLib tools
  • curl/Invoke-WebRequest → web_fetch
  • sqlcmd → sql_query
  • sqlplus → oracle_query
  • mysql / mariadb → mysql_query
  • net use, dir \\server or copy \\server → the UNC tools (named in the rules only)

  A single command that such a tool covers comes back as Not run: 'cat' has a tool of its own — call read_file instead…, before the pane asks.

  • Only once a turn: the same line sent again goes to the pane as usual, so a real need (an option the tool lacks) still reaches you.
  • Never sent back: pipes and compound lines (cat x | sort, a && b), commands with no tool (git push), tools that are switched off, and (with the police off) a line naming a path outside the working directory.

Ask

Claude

This tab covers the Claude Code CLI, for /claude (you send it a message) and claude_advisor (the model asks it for advice), then the Claude API and the Claude CLI as servers.

With the Claude API switch on and a key set, /server (and the startup picker) lists a Claude API row after the local servers. Picking it sets LLM URL to https://api.anthropic.com/v1 and offers the account's models, then the reasoning level.

• Every message is billed to the key's account.
• Each key goes only to its own server: local servers never see this one, and the Claude API never sees LLM API key.
• A change to one of these four settings reconnects once /tools closes (refused while a reply runs).
• LLM reasoning per model: low…xhigh turn on adaptive thinking at that effort (xhigh is high on the 4.6 models; Haiku 4.5 and older take a thinking budget instead). none turns thinking off where the model allows it. Opus 5.5 and Fable always think, so there none is the lowest effort.
• The context window is the model's max_input_tokens.
• /usage adds Cache and Cost rows. Cost is an estimate at list price, not the bill.

With Claude CLI server on and Claude Code found, /server (and the startup picker) lists a Claude CLI row last. Picking it sets LLM URL to claude-cli (http://claude-cli.localhost/v1, a name that stands for the CLI, never a place) and offers fable, opus, sonnet and haiku as models, then the reasoning level (Claude Code's --effort). /server claude-cli goes straight to it.

• One open session. The first message starts claude and keeps it running: every later message goes to the same process and the same Claude Code session, and only the new message is sent (Claude Code keeps the conversation). A change of model, reasoning, system prompt or offered tools restarts it on the same session (--resume), and so does a crash. /clear, /new and a profile switch start a new session. The session's id is saved with the app's session, so restoring the session resumes it.
• The app's tools, not Claude Code's. Claude Code runs with all its own tools off, your Claude Code skills, hooks, settings files and MCP servers left out, and the app's own system prompt. The model gets the tools this turn offers, through an MCP server the app hosts: Claude Code starts the app's own executable as a small relay to it (--mcp-relay). Each call runs in the app as any model's does: the shell's approval pane, ask_user, the transcript and LLM max tool iterations all apply.
• ESC interrupts Claude Code and the reply ends where it got to. If Claude Code does not stop within 3 seconds, it is closed, and the next message resumes the session on a new process.
• Requests beside the conversation (a session's title, a skill reflection, a /compact summary, a /botchat bot) each run as a one-off claude -p with no tools and no saved session, so the chat's session never sees them.
• LLM auto compact and the mid-turn context guard do nothing here: Claude Code compacts its own conversation. The context window is 200,000 tokens.
• Messages count against your Claude Code plan (or its API key), as if you had typed them in Claude Code. The log records each turn's cost as Claude Code reports it.
• Switching to another server stops the Claude CLI; the session stays on disk for a switch back.

Home Assistant

You can change which services run without asking under ask in profile.json (homeAssistantSafeServices, with entries like light.* or remote.send_command).

Print

Obsidian

ComfyUI

SQL

Oracle

MySQL

UNC

GitLib

Options

To see a folded block in full, click its line, press Ctrl+O, click ⤡ on the rule above the input row, or use /expand.

MCP servers (/mcp)

Servers

One row per server in mcp.json (the profile's, then the home folder's; the profile's wins on a name clash), with its transport and state: connected · N tools, connecting, failed: … or off.

• Enter or Space turns a server on or off, connecting or disconnecting at once. Enter on a failed server retries.
• Below the servers: edit profile mcp.json, edit global mcp.json, reload, and any skipped entries with the reason.

Tools

Every connected server's tools, as <server>__<tool> with the description the server gives. Enter or Space turns one on or off.

Options

System prompt (/sys)

A read-only view of exactly what the next reply will send, nothing paraphrased.

Prompt

The system prompt section by section, each with its status:

• Persona (default or persona.md)
• Operating rules (default or operata.md; the reply-format and tool sentences live here)
• Project notes (NEON.md / AGENTS.md)
• Memory
• Skills (the catalog)
• Voice directive (default or vocalia.md; spoken turns only, always last)

Tools

Every tool the reply may call, grouped (Clock, Timers, Files, GitLib, Shell, Obsidian, SQL, ComfyUI, Claude, Web, Memory, Skills, Sessions, one group per connected MCP server, Plan in plan mode, Questions), with the description the model reads. Tools and groups that are switched off are left out; /tools lists everything.

Plan mode

/plan <requirement> has the model research and present a plan before anything changes. It needs LLM offer tools, and is refused while a reply runs.

• Tools: only the read-only ones (reading and searching files, git status/log/diff, the web, SQL, Oracle, MySQL, the UNC shares' reads, the vault, recall, skills, sessions, ask_user) plus present_plan. Every tool that writes, runs or starts something, and every MCP tool, is held back until the plan is approved.
• Presenting: the model asks what it needs (your later messages add detail), then presents the plan. The plan is printed and saved as .neon/plans/<kebab-name>.md under the working directory. A new plan never overwrites an older one, and each revision overwrites its own file. 📝 shows on the status strip while planning.
• Approving: a pane offers Approve & run (a), Approve, clear context & run (f), Keep refining… (r, with what should change) or Cancel plan (c). The cursor starts on Keep refining, and ESC picks it too. Approving marks the file status: approved and sends a turn with every tool to carry the plan out, ticking its checkboxes as it goes. The fresh-context choice starts a new conversation with the plan's text in the message.
• Tracking: once every checkbox is ticked, the file is marked done. While some are left, it is incomplete with a progress: 3/7 line, reported again when the count changes or the reply is stopped.
• /new, /clear and a profile switch leave plan mode. A restored session is still planning.

Bot conversations

/botchat [profile ...] [topic] lets profiles talk to each other until you stop them.

• Cast: the profiles you name, or every profile when you name none. The current profile always joins and speaks first.

• Topic: the first word that isn't a profile starts the topic (/botchat ada max the best pizza). After --, the rest is always the topic (/botchat ada -- max speed of light). Without a topic, the bots pick their own.

• Turns: each reply is in the speaker's persona (persona.md) and, with speech on, in its own voice. A bot named in the last line (yours or the last reply) speaks next. Otherwise the next speaker is random, but never the one who just spoke. All bots run on this profile's LLM, or each on its own under Botchat LLM mode multi.

• Tools: none, except pictures (see Botchat pictures) and load_skill (Botchat skills enabled).

• Joining in: a line you type joins the chat before the next reply.

• ESC works in steps:

  • The first press stops the speaking bot's voice (with speech on).
  • The next cuts the replying bot short (its words so far stay), and the next bot answers.
  • One more, before that bot has shown or said anything, ends the chat.
  • A further ESC at the idle line clears your draft.

  /exit, /clear and /new end the chat, then run.

• Resume: /botchat --resume [line] continues this run's last chat (same cast, topic, lines and session row). A line after it joins as yours.

• Embedded bots: under multi, bots on the embedded URL either share one server (Botchat multi-embedded parent-server) or get one per model (multi-server). With Botchat multi-embedded kill off, a multi-server chat leaves its extra servers running; /botchat --kill stops them, but never this profile's own server. Typed during a chat, it runs once the chat ends.

• Pronouns: each bot is told the others' pronouns, taken from their profile's first TTS voice: am_, bm_… are male, anything else female.

• Saved: with Session logging on, the chat is saved as a session of its own. The current conversation is left as it was.

Claude Code from the chat

/claude <message> runs the claude CLI without its interface (headless) in the working directory.

• Its reply streams in under Claude's name, with each tool it uses on a dim line and a footer with the cost and tokens. With speech on, the reply is spoken.
• The question and reply join the conversation, tagged [to Claude] and [Claude], so the local model can build on them. Claude doesn't see the local conversation.
• Each session has one Claude conversation. The next /claude resumes it, even after a restart once the session is restored. /claude new, /clear, /new and a profile switch start another.
• What Claude may do is set by Claude slash command permissions (the Claude tab of /tools). Anything beyond that is denied, never asked.
• ESC or Ctrl+C stops Claude and keeps the reply so far. It works with no LLM server, and is refused while a reply runs.
• Your own Claude Code setup applies: its sign-in, CLAUDE.md, skills, MCP servers and hooks. /usage shows what the runs cost.

Loops

• An optional delay after the count waits after each reply: /loop infinite 1m check the build. It is one word (30s, 5m, 1h30m), up to 24 hours. ESC or Ctrl+C during the wait stops the loop.
• A cancelled, withdrawn or failed turn ends the loop.
• The message may be /imagine … or /speak …, which the loop runs itself with no model in between: /loop infinite 5s /imagine score_9, 1girl. A failed generation, a bad path or ESC ends it. /speak waits for each reading to be heard. Only the last pass's pictures go with your next message.
• No other commands can be looped.

Benchmark tests

/test <name> runs the nine tests of the companion LLMTester project against the connected model. Each is one request, graded in code, with no model judging another.

• /test reasoning, /test structured and /test long run a group. /test all runs every test, with context saturation last as the heaviest.
• Each test sends only its own messages: no system prompt, no history, no tools. Sampling and reasoning are the connected model's own (/sampling, /reasoning), as in chat.
• The structured tests send their schema as response_format (json_schema, strict: true, the schema exactly as written). A reply wrapped in a code fence fails. The invoice schema's root is an array, which llama.cpp, vLLM and SGLang accept. Over the Claude API these two tests are skipped.
• The long-context tests are sized from the context window (from the settings or the server). The retrieval haystack takes up to half of it (at most ~66k tokens), and saturation fills it. When the window is unknown, they use ~66k tokens. The LLM request timeout applies, and a refused or timed-out request counts as an error.
• A run starts the way /clear leaves things: the screen is cleared, the conversation and its session are forgotten, and the token figures leave the hint row.
• Results show as one line per test (a failure shows what the model answered), then a table with the time, tokens and tok/s. ESC stops the run and keeps what finished.
• While it runs, the input row and the toolbar and hint-row glyphs work as they do during a reply: a pane command or glyph opens its pane over the run, a quick command runs when it ends, /clear, /new or /exit stops it as ESC does, and a message is queued.
• Runs are saved in the profile's tests.json (the last 50), each with the reasoning level and sampling it ran with, shown under its table and in /test history. /test history lists them, and a bare /test shows each test's last verdict for the connected model. Nothing enters the conversation.

Imagine options

• The picture is drawn in the transcript, saved in ComfyUI output folder, and handed to the model with your next message.
• The first word names the workflow when it matches one (the argument list completes the names). Without a name, an offered workflow is used.
• -- <negative> sets the negative prompt. --no-negative sends none, not even the workflow's default.
• --count is capped by ComfyUI max pictures per call.
• --image2 / --image3 feed a workflow that takes several pictures. A workflow with no prompt (a face swap) runs on its pictures alone: /imagine faceswap --image a.png --image2 b.png.
• /loop repeats it: /loop 10 30s /imagine ….

Folder picker

/cwd browse, and the Working directory and Obsidian vault rows, open a folder tree on the pane, headed 📂 Folders.

• ⌂ profile (the profile's files\ folder) and ▣ splash (its splash\ folder) sit above the drives. The tree opens on the directory in use.
• Space, → and ← open and close folders; - collapses all. Clicking a folder's glyph, or double-clicking its name, opens or closes it.
• Only Enter chooses. Choosing ⌂ profile saves the default, like /cwd ~.

Picture viewer

The picture viewer is a window of its own (Windows only). Elsewhere, the app registered for the file opens instead, and /view always draws in the transcript. It opens from:

• A double-click on a picture in the transcript (a sent one, one a tool fetched or generated, /view --chat, /imagine, the splash). The viewer opens on the picture's folder, showing that picture. A pasted picture or the built-in splash has no file, so it is written to %TEMP%\NeonSidekick\pictures first. Only a failure prints anything. Image viewer can send these to another program.
• /view <image or folder>: it stays on the image, or on a folder's newest picture while following new ones.
• /comfy view, or the 🎞️ at the left of the picture strip's rule: the ComfyUI output folder (created if missing), following new pictures as they are generated. It works while a reply runs.

The window follows the theme unless Themed image viewer is off. It gets a dark title bar in the theme's colours with an accent edge on Windows 11 (Windows 10 gets a plain dark bar), and the theme's background. A /theme change reaches an open viewer the next time it is focused. There is one viewer window per app, and it closes with the app.

The viewer opens where it was last closed, always at the default size. It remembers the window's normal position even when you close it maximized or in full screen. The position is saved in the profile. If that spot is no longer on any monitor, Windows moves the window back into view.

The viewer and the ComfyUI picture strip follow each other:

• Browsing in the viewer (←/→, Home/End, the next picture after a delete) highlights the same picture in the strip. A picture the strip doesn't hold is ignored, and the slide show and newly arriving pictures leave the strip alone.
• ←/→ on the strip, or a click on one of its pictures, moves an open viewer on the strip's folder to that picture, without bringing the viewer to the front.

Profiles

• A name is 1 to 32 letters, digits, - or _, and can't be neon or one of the verbs.
• A name starting with _ is temporary: it loads as usual, but the next launch opens default (the profile itself is kept).
• --profile <name> (or NEONSIDEKICK_PROFILE) opens a profile for one launch, temporary ones included, without changing which one the next launch opens. An unknown name exits with code 2. A --headless run with neither opens default.
• A reset keeps these settings: LLM URL, LLM model, LLM API key, TTS HTTP URL, Claude API key, Web browser path, Web search method, Web SearXNG URL, Claude executable, Obsidian vault, ComfyUI URL, Home Assistant URL and Home Assistant API key. --all resets those too. default can only be reset while it is loaded.
• push <name> copies the loaded profile's settings over another's; pull <name> copies another's over the loaded one's. Both ask for confirmation first.
  • Only profile.json is copied, and the target keeps its own working directory. Memories, persona, operating rules, voice directive and MCP servers stay as they are.
  • Any profile can be overwritten, default included. A pull clears the conversation, as a reset does.
• The LLM API key, Claude API key and Home Assistant API key are kept in profile.json, encrypted for your Windows account (DPAPI, Windows' built-in per-user encryption; stored as dpapi:…). A key typed into the file by hand is encrypted the next time the profile loads (the empty placeholder stays as it is). An encrypted key can only be read by the same Windows user on the same machine.

Custom themes

Your own themes are JSON files in the themes folder of the home (%USERPROFILE%\.neonsidekick\themes, or under NEONSIDEKICK_HOME), shared by every profile. They appear after the built-ins in /theme, its argument list and the Theme setting, sorted by name. A file named like a built-in theme replaces that built-in: it takes the built-in's place in the list, and any theme whose base is that name (including the default base, synthwave) builds on your file. The folder is read each time one of those opens, so a new or edited file shows up without a restart; pick the theme again to see an edit.

Fifty ready-made themes come with the repo in assets/themes, one folder per category. To use one, copy its file into the themes folder itself (subfolders aren't read) and pick it with /theme. To compare them all side by side, open Theme Atlas.html in a browser. It previews these fifty and the ten built-ins. The built-in folder holds the built-ins as files. Copy one in as it is, or edited, to replace that built-in, or rename it (the file and its "name") to keep it as a theme of its own.

The easiest start is /theme export <name> [new-name]. It writes any theme to themes\<new-name>.json with every colour filled in. The new name defaults to <name>-custom, and an existing file is never overwritten. Give a built-in's own name (/theme export noir noir) to start a file that replaces it.

{
  "name": "dracula",                 // optional: the file name when left out
  "description": "vampire purple",   // optional: the note beside the name ("custom theme" when left out)
  "base": "synthwave",               // optional: a built-in or another of your themes (synthwave when left out, or the built-in a file replaces)
  "colors": { "primary": "#FF79C6", "secondary": "#8BE9FD", "ink": "#F8F8F2", "bg": "#282A36", "panelBg": "#44475A" },
  "gradient": ["#8BE9FD", "#BD93F9", "#FF79C6", "#FFB86C", "#F1FA8C"],
  "styles": {
    "codeComment": { "fg": "#6272A4", "italic": true },
    "codeKeyword": { "fg": "primary", "bold": true },
    "menuHighlight": { "bg": "#44475A" }
  }
}

• A file only says what it changes. Anything left out comes from base: colours, gradient and style changes. A base that is itself a file can build on another, as long as the chain doesn't loop. A file that replaces a built-in builds on the original built-in when its base is left out or names itself, so noir.json with only a primary is noir with that primary.
• Names are 1 to 32 lower-case letters, digits, - or _, starting with a letter or digit, and not export. A file named like a built-in replaces it. A file named like a theme an earlier file (by file name) already took is skipped.
• Colours are #RRGGBB or #RGB. Comments and trailing commas are allowed.
• Derived colours. On synthwave and most built-ins, warn is the highlight and the gradient runs secondary → tertiary → primary → warm → highlight. If the base works that way and your file sets neither, they are worked out again from your colours, so the banner wears your accents. A base that sets its own (netrunner's gradient, noir's warn) passes it on unchanged.
• Problems. A file that can't be read, isn't valid JSON, has a bad name or a missing or looping base is skipped. A misspelled key or a bad colour is ignored, and the rest of the theme still loads. Each problem shows as a warning naming the file when /theme or the Theme setting opens.

Colour roles (colors). Every style below is made from these.

gradient is the banner title and its rule, left to right, with 2 to 16 stops.

Style changes (styles). Each entry can set fg and bg (a hex colour, or a role name such as "dim" meaning that role in this theme) and turn bold, italic, underline, dim or strikethrough on (true) or off (false). Anything an entry leaves out stays as the theme makes it. The styles are:

• Text: body, dimText, accent, accentSecondary, accentTertiary, label, errorText, goodText, warnText.
• Screen: user (your lines), assistant (the reply), systemText (notices), sectionHeading, border, tableHeader, spinner, paneRule, hint, trailerMark, pasteLabel, placeholder, selectedText.
• Menus: menuHighlight, menuHighlightDim, menuDisabled.
• Replies: markdownBold, markdownItalic, markdownCode, markdownCodeBlock, markdownCodeLabel, thinking, markdownHeading1, markdownHeading, markdownBullet, markdownQuoteBar, markdownQuote, markdownLinkUrl, markdownRule.
• Code highlighting: codeKeyword, codeType, codeString, codeNumber, codeComment, codePunctuation, codeFunction, codeVariable, codeAttribute, codeTag, codeHeading, codeInserted, codeDeleted.

Some styles start as copies of another: user, spinner and markdownHeading copy accentSecondary; assistant copies body; systemText, hint, markdownCodeLabel, markdownQuote and markdownLinkUrl copy dimText; sectionHeading copies accentTertiary; markdownHeading1 copies accent; markdownBullet and markdownQuoteBar copy trailerMark; markdownRule copies paneRule; codeAttribute copies codeType; codeTag copies codeKeyword. Changing the original changes its copies too, unless a copy has a change of its own. Anything drawn straight in a role's colour rather than through one of these styles follows colors only.

Clock

Timers

Files

All paths are relative to the working directory. Nothing outside it can be reached.

GitLib

These tools run git inside the app (LibGit2Sharp), for when the shell is off or the model should never run git.exe. Turn GitLib tools off to leave git to the shell.

• Local only: no fetch, pull, push or clone.
• The repository's root must be the working directory or a folder under it. Every tool takes an optional path: the file or folder it targets, which also tells it which repository to use.
• gitlib_delete starts off. Switch it on in the Offered tab of /tools.
• Renamed on 2026-09-30: the tools were git_status, git_log and so on, and the settings Git native …. A profile from before starts with the GitLib settings at their defaults (the tools off, the email and name unset), and gitlib_delete switched on: switch it off again in the Offered tab if you want it off.
• Commits need an identity. Set GitLib email and GitLib name on the GitLib tab of /tools, then run /gituser to write them into the repository's config.

Obsidian

The vault tools work on the vault's files directly: no plugin, no network, and Obsidian doesn't need to be running.

Notes are found by name, [[wikilink]], alias or path. Inline tags and frontmatter properties both count. Dot-folders (.obsidian) are ignored, and line endings are kept as they were. Overwriting a note replaces it in place; only vault_delete uses the vault's .trash.

SQL

Read-only queries against SQL Server over named connections. The app talks to the server itself (Microsoft.Data.SqlClient), so no ODBC driver is needed. Connections live in sql.json: the one in the home folder is read by every profile, and a profile's own file wins when both use the same name.

Connection settings

• server: host, host,port or host\instance.
• auth:
  • sql: a SQL login (user and password).
  • windows: your own Windows account.
  • runas: another Windows account (user as DOMAIN\name or name@domain, plus password). It works like runas /netonly: the app runs as you on this machine but signs in to the server as that account. SELECT SUSER_SNAME() shows which account the server sees.
• encrypt: strict, mandatory (default) or optional.
• trustServerCertificate: true accepts a self-signed certificate.
• connectTimeoutSeconds: 1–120 (default 15).
• passwordStore:
  • file (default): a password typed into the file is encrypted in place the next time the app reads it. The encryption (DPAPI, built into Windows) means only your Windows account on this machine can read it.
  • credman: the password is kept in Windows Credential Manager (NeonSidekick/sql/<connection_name>), and the file holds none.

Managing connections

• SQL add connection (the SQL tab of /tools) walks you through a new connection, one page per choice: the file (profile or global), name, server, database, sign-in, account, password store and password (masked), encryption, certificate trust, connect timeout and description.
  • The summary can test the draft (SELECT @@VERSION, nothing written), and saves it into the file with its comments kept.
  • Its save rows offer the new connection to the model, or save it hidden until ticked in SQL connections offered.
  • ESC steps back a page; Enter on a summary row changes that choice.
  • It only adds connections. To change an existing one, edit the file.
• SQL set password updates a connection's password.
• Or edit the files directly (comments and trailing commas are allowed): %USERPROFILE%\.neonsidekick\sql.json (global) and %USERPROFILE%\.neonsidekick\profiles\<profile>\sql.json.

{
  "connections": {
    // SQL Auth: Password encrypted in-place by DPAPI after first read
    "adventureworks": {
      "server": "127.0.0.1,1433",
      "database": "AdventureWorks2022",
      "auth": "sql",
      "user": "reader",
      "password": "type-password-here-once",
      "encrypt": "mandatory",
      "trustServerCertificate": true,
      "description": "Sample sales database"
    },
    // Windows Auth: Current account, no password required
    "reports-me": {
      "server": "sqlhost01.example.com,1453",
      "database": "Reports",
      "auth": "windows",
      "encrypt": "mandatory"
    },
    // RunAs Auth: Alternate account with password in Windows Credential Manager
    "reports-admin": {
      "server": "sqlhost01.example.com,1453",
      "database": "Reports",
      "auth": "runas",
      "user": "CONTOSO\\svc-reader",
      "passwordStore": "credman",
      "encrypt": "mandatory"
    }
  }
}

Safety

sql_query runs one read-only statement:

• It is first parsed with SQL Server's own parser (ScriptDom). Only a single SELECT (or a WITH CTE ending in one) passes. Multi-statement batches, DDL, EXEC, INTO, DELETE and linked servers are refused before anything reaches the server.
• It runs in a read-only-intent transaction that is always rolled back. You should still give the login read-only permissions on the database.
• Values go in as @name parameters.
• Results come back as a Markdown table, with floating-point numbers at full precision. CLR types (geography, hierarchyid) need .ToString() in the query.

Oracle

Read-only queries against Oracle over named connections, the SQL Server tools' twin. The app talks to the database itself through ODP.NET Core, Oracle's fully managed driver, so no Oracle Client or Instant Client is needed. Connections live in oracle.json, a home folder file and a profile file as with sql.json; the profile's wins on a name clash.

Connection settings

• dataSource: EZConnect host:port/service (localhost:1521/FREEPDB1; the port is 1521 when left out), or a whole (DESCRIPTION=…).
• user: the database user. SYS (and any … AS SYSDBA sign-in) is refused: Oracle does not hold SYS to a read-only transaction.
• schema: the schema a call works in when it names none (ALTER SESSION SET CURRENT_SCHEMA); the user's own by default.
• connectTimeoutSeconds: 1–120 (default 15).
• passwordStore: file (default, encrypted in place with DPAPI) or credman (Windows Credential Manager, NeonSidekick/oracle/<connection_name>), exactly as for sql.json.

Managing connections

• Oracle add connection (the Oracle tab of /tools) walks you through a new connection: the file, name, data source, default schema, user, password store and password (masked), connect timeout and description.
  • The summary can test the draft (nothing written): who it signed in as, which container, the server's version. When the account could change data (write privileges, CREATE …, … ANY …, tables it owns), it says so: the tools never write, but a read-only account is the real guard.
  • It only adds connections. To change an existing one, edit the file.
• Oracle set password updates a connection's password.
• Or edit %USERPROFILE%\.neonsidekick\oracle.json (global) and %USERPROFILE%\.neonsidekick\profiles\<profile>\oracle.json directly.

{
  "connections": {
    // Password encrypted in place by DPAPI after first read
    "hr": {
      "dataSource": "localhost:1521/FREEPDB1",
      "user": "hr_reader",
      "password": "type-password-here-once",
      "schema": "HR",
      "description": "The sample human-resources schema"
    },
    // A full descriptor, the password in Windows Credential Manager
    "ledger": {
      "dataSource": "(DESCRIPTION=(ADDRESS=(PROTOCOL=TCP)(HOST=dbhost01.example.com)(PORT=1521))(CONNECT_DATA=(SERVICE_NAME=LEDGER)))",
      "user": "ledger_ro",
      "passwordStore": "credman"
    }
  }
}

Safety

oracle_query runs one read-only statement, behind four layers:

1. The gate. Oracle has no managed parser, so the text is lexed (comments, '…', q'[…]' and n'…' literals, "quoted" names and :binds understood, so a keyword can't hide in or behind them). Only one SELECT (or WITH … SELECT) passes. Refused before anything reaches the server: a second statement, PL/SQL (BEGIN, DECLARE, WITH FUNCTION), FOR UPDATE, INTO, NEXTVAL (a sequence never rolls back), database links (@remote), inline external tables and BFILENAME (files on the server), every DML and DDL word, and packages that reach outside or past the gate (UTL_HTTP, UTL_FILE, DBMS_PIPE, DBMS_SQL, DBMS_XMLGEN, DBMS_SCHEDULER, …).
2. The session. On 23ai and later, ALTER SESSION SET READ_ONLY = TRUE first: the server refuses any DML or DDL (ORA-28193), even from an autonomous-transaction function the query calls.
3. The transaction. SET TRANSACTION READ ONLY (DML and row locks refused, ORA-01456), and it is always rolled back.
4. The account. Give the user only SELECT grants (or ALTER USER … READ ONLY on 23ai); the wizard's test warns of one that can write.

Values go in as :name parameters. Results come back as a Markdown table; a NUMBER past 28 digits keeps every digit, a CLOB or BLOB shows its first part and its length. Object types (SDO_GEOMETRY, XMLTYPE) need converting to text in the query. The listings leave out Oracle's own schemas.

--oracle-check <connection> proves the tools against a real database on the published exe (every type, the read-only layers, a cancel and a timeout; it only reads).

MySQL and MariaDB

Read-only queries against MySQL 8.0.16+ and MariaDB 10.2+ over named connections, the Oracle tools' twin. The app talks to the server itself through MySqlConnector (fully managed, MIT), so no client library is needed. Connections live in mysql.json, a home folder file and a profile file as with the others; the profile's wins on a name clash.

Connection settings

• host, port (3306 by default), database: the database a call works in when it names none. Without one, the listings cover every database the user can see.
• user, and the password: passwordStore file (default, DPAPI-encrypted in place) or credman (NeonSidekick/mysql/<connection_name>), as for the others.
• sslMode: preferred (default), required, verify-ca, verify-full or none.
• allowPublicKeyRetrieval: true only for a caching_sha2_password account over a connection without TLS (off by default: a man in the middle could hand over its own key).
• connectTimeoutSeconds: 1–120 (default 15).

{
  "connections": {
    "shop": {
      "host": "localhost",
      "port": 3306,
      "database": "shop",
      "user": "shop_reader",
      "password": "type-password-here-once",
      "description": "The sample retail database"
    },
    "billing": {
      "host": "db01.example.com",
      "database": "billing",
      "user": "billing_ro",
      "passwordStore": "credman",
      "sslMode": "verify-full"
    }
  }
}

MySQL add connection on the MySQL tab of /tools walks through a new one (file, name, host, port, database, user, password store and password, TLS mode, timeout, description) and can test it first: who it signs in as, the server's version, and a warning when SHOW GRANTS says the account could change data. MySQL set password updates a password.

Safety

mysql_query runs one read-only statement, behind these layers:

1. The gate. The text is lexed by MySQL's rules (# and -- comments, '…' and "…" strings with backslash escapes, `quoted` names, @name binds). Only one SELECT (or WITH … SELECT) passes. Refused before anything reaches the server: a second statement, executable comments (/*! … */, which the server runs as code), INTO (OUTFILE, DUMPFILE), FOR UPDATE/FOR SHARE/LOCK IN SHARE MODE, LOAD_FILE, named locks, MariaDB sequence moves, and every DML and DDL word (INSERT, REPLACE and TRUNCATE only as statements: as functions they're fine).
2. The session. NO_BACKSLASH_ESCAPES and ANSI_QUOTES are stripped from sql_mode, so the server reads strings exactly as the gate did. The server caps each statement's run time (max_execution_time on MySQL, max_statement_time on MariaDB). The driver never runs LOAD DATA LOCAL and never sets user variables.
3. The transaction. START TRANSACTION READ ONLY refuses any write to a real table, even from a stored function (ERROR 1792), and it is always rolled back.
4. The account. Give the user SELECT grants alone; the wizard's test warns of one that can write.

--mysql-check <connection> proves the tools against a real server on the published exe (every type, the gate, the session's string reading, the read-only transaction, a cancel and a timeout; it only reads).

UNC shares and outside folders

The UNC tools reach named network shares (\\server\share, or a folder under one) and local folders outside the working directory (D:\Data), without mapped drives. Each share is reached either as you (windows) or as another Windows account (runas, like runas /netonly: your own identity locally, the other account's credentials for the network sign-in). Shares are read-only unless two keys say otherwise. Shares live in unc.json, a home folder file and a profile file as with the SQL connections; the profile's wins on a name clash.

Share settings

• path (required): \\server\share, a folder under it, or a full local path (D:\Data). In JSON a backslash is doubled ("\\\\fs01\\eng") or written as / ("//fs01/eng"). A device path (\\?\…), a relative path or a whole drive (D:\) is refused.
• auth: windows (default) or runas. Under runas, user is DOMAIN\name or name@domain, and the password is kept as for SQL: passwordStore file (default, DPAPI-encrypted in place) or credman (NeonSidekick/unc/<share_name>).
• access: read (default) or readwrite. A readwrite share can be changed only while UNC writes is on (the UNC tab of /tools, off by default): both keys are checked at every call.
• description: what the share holds; the model reads it to pick a share.

{
  "shares": {
    "eng": { "path": "//fs01/eng", "description": "Engineering specs and drawings" },
    "finance": {
      "path": "//fs02.corp.local/finance/reports",
      "auth": "runas",
      "user": "CORP\\svc_reader",
      "passwordStore": "credman"
    },
    "data": { "path": "D:/Data", "access": "readwrite" }
  }
}

UNC add share on the UNC tab of /tools walks through a new one (file, name, path, sign-in, account, password store and password, access, description) and can test it first by listing its root under its account; it never writes. UNC set password updates a runas password.

How it signs in

• A runas share gets a LOGON32_LOGON_NEW_CREDENTIALS token for each call. That token is a logon session of its own, so it never collides with your mapped drives ("multiple connections to a server by the same user") and leaves nothing behind in net use. Windows checks the password only when the server is reached: a wrong one comes back as "unknown account or wrong password".
• A windows share uses whatever your own sign-in has for that server (a mapped drive's credentials, or a cmdkey /add:server entry).
• Use the UNC path rather than a mapped drive letter: a mapping belongs to one sign-in, and a runas token or an elevated app may not see it. The wizard warns of a drive letter that is a mapped network drive.
• Prefer server names to IP addresses: an address falls back from Kerberos to NTLM, which a domain may block.
• Testing runas against \\localhost proves nothing: Windows signs a loopback session in with your own token, whatever account the share names.
• Each call starts a fresh logon session, so the first access to a server costs a sign-in (tens to a few hundred milliseconds).

Safety

• Paths are judged as in the working directory: relative to the share's root (or a full path under it), never above it. A path naming a stream (file.txt:secret) is refused. Walks skip reparse points, so a DFS link inside a share isn't followed; add the link's target as a share of its own.
• Writes need UNC writes on and the share's access set to readwrite. The changing tools aren't offered otherwise, and each call checks both again.
• Changes are permanent. An overwrite replaces the file in place (its permissions and attributes kept), and unc_delete removes a file or folder for good. unc_delete is off in a fresh profile even under UNC writes; switch it on in the Offered tab. A file server's Previous Versions may still have a copy.
• Audit. Every change logs a line with the share, the account and the path.
• Budgets. A search reads at most 256 MB with four readers and looks at 100,000 entries, then says it stopped early. A preflight gives up on a share that doesn't answer in 10 seconds.
• The shell can't reach a share through the app's sign-in: a runas share's token is the UNC tools' alone. For the same reason open refuses a runas share on the network (Explorer or the editor would sign in as you): unc_fetch the file into the working directory, then open the copy.

share can be left out when path is a full path under a share; otherwise the default share (or the first) is used. The changing tools (unc_write through unc_put) appear only under both keys.

--unc-check <share> proves the tools against a real share on the published exe (its reach, the runas token on every worker thread, a listing and a search; it only reads).

Home Assistant

The Home Assistant tools control your own Home Assistant over its REST API, using a long-lived access token (Home Assistant URL, Home Assistant API key). Whatever Home Assistant has connected works: Hue lights and scenes, a TV, sensors, to-do lists.

• Names, not ids. The model says "the den", "kitchen and hallway", "Den Corner Lamp" or "all". A room goes to its group light (a Hue room) when it has one, otherwise to every light in it. A name that fits several things comes back as a question listing them, and a name that fits nothing lists what is close, so the model never guesses an id.
• The action policy. Under ask (the default), the safe services run and anything else shows the pane first, with the service, the device and the data. If you say no, the model is told not to retry. See Home Assistant action policy.
• Fresh states. The states are read at most every 30 seconds, and again after any change. So "turn off the den, then tell me what's on" sees the new state.

Printing

/print and the two print tools send work to any printer Windows has installed, local or shared.

• Drawn by the app. These file types are laid out by the app itself:
  • Text and code files print as a monospace listing: tabs become four columns, long lines wrap, and a form feed starts a new page.
  • Markdown (.md) prints formatted: headings bold and stepped in size, bold, italic and code runs, lists, quotes, code blocks, rules, links with their address, and tables cut to fit.
  • A picture (PNG, JPEG, GIF, WebP, BMP) is fitted to one page, and never enlarged past its own size.
  • Every page carries the file's name, the time and page N of M, with a 0.6-inch margin. The paper size, tray and quality are the printer's own settings.
• Anything else (a PDF, a Word or Excel file) goes to the program Windows has registered to print it, and only on the Windows default printer. A printer, copies, pages or landscape given with such a file is refused rather than ignored. A file type no program can print is refused.
• The policy. Under ask (the default), the model's print_file shows the pane first, with the file, the printer and the sheets. If you say no, the model is told not to retry. See Print action policy.

Images (ComfyUI)

The image tools run your own ComfyUI workflows on your server (ComfyUI URL). They save the pictures under the working directory and show them to the model in the next message, so it can describe or refine them.

Adding a workflow

With the wizard (ComfyUI add workflow on the ComfyUI tab of /tools, one page per choice):

• Build makes a standard text → image or image → image workflow from your server's lists: checkpoint, family, folder (this profile's or every profile's), name, CLIP skip, sampler and scheduler, default size, steps, CFG, denoise, negative and description.
• Import takes a workflow exported from ComfyUI (Workflow → Export (API)).
  • It finds the prompt, negative, seed, steps, CFG, size and input-image nodes, puts the placeholders in, and keeps the export's values as defaults.
  • It reads both a plain KSampler graph and the custom-sampler graph FLUX.2 uses (SamplerCustomAdvanced with its RandomNoise, scheduler and guider; CFG sets the FluxGuidance).
  • A value fed by a primitive node gets its placeholder there. A value set by another node (a switch, a resolution picker) is left as built, and the wizard says so.
• FLUX.2, Krea 2, Z-Image, Qwen Image, Ernie Image, Boogu, LongCat Image, HiDream I1 and Ideogram 4 load as separate model files, which Build can't wire up. For these, export ComfyUI's own template and Import it. (Copybara has no family yet.)
• The summary can test the draft (one small run of at most 512 px and 8 steps; nothing saved), and saves it as <name>.json + <name>.md. Its save rows offer the new one to the model, or save it hidden until ticked in ComfyUI workflows offered. ESC steps back a page.

By hand:

1. Build the workflow in ComfyUI and export it in the API format: Workflow → Export (API) (or enable dev mode and use Save (API)). The regular save, with nodes and links, is refused with a note saying so.
2. Put placeholders where the call's values go, then drop the file into <profile>\comfy\ (this profile) or <home>\comfy\ (every profile; the profile's copy wins when both have the same name). The file name is the workflow's name. Workflows are re-read at every call.

3. Optionally, a sidecar file <name>.md beside it sets the defaults and tips:

---
description: Anime portraits on Pony Diffusion XL
family: pony          # pony, illustrious, juggernaut, sdxl, flux, flux2, flux2klein, krea2, zimage, qwenimage, sd35, ernie, boogu, longcat, hidream, ideogram4, sd15 or other (guessed from the file name otherwise)
width: 832
height: 1216
steps: 25
cfg: 7
negative: score_6, score_5, score_4, blurry
reinforce: false      # optional: send this negative as written, nothing appended (ComfyUI reinforce negatives)
image: the picture to restyle   # optional, per input picture: its role, shown to the model (image, image2, image3)
---
Prefer source_anime; keep rating_safe unless asked.

Prompts

• Describe what you want ("a cozy neon ramen stall at night") and the model writes the prompt in the style of the workflow's family (below). The family's default negative is added unless the sidecar names one.
• Give your own prompt ("use this prompt: score_9, …") and the model passes it through unchanged with verbatim: true. Nothing is added, not even the family's default negative.
• Skip the model: /imagine score_9, score_8_up, source_anime, 1girl -- score_4, blurry --seed 42 sends it straight to ComfyUI. --no-negative in place of -- … sends no negative at all.
• Choose what the model may use with ComfyUI workflows offered. With only one ticked, the model has no choice to make.

Several-picture workflows (face swaps)

A workflow can take up to three pictures ({{image}}, {{image2}}, {{image3}}). For a face swap:

1. Install the ReActor node pack on your ComfyUI server and build the swap there (two LoadImage nodes → ReActorFaceSwap → SaveImage).
2. Export it with Export (API) and Import it. The LoadImage nodes become {{image}} and {{image2}} in node-id order (the wizard says which got which). A graph with no sampler is fine.
3. Say which picture is which in its .md, so the model puts them the right way round:

---
description: Face swap (ReActor)
image: the picture whose face is replaced
image2: the face to put in
---

Then "put my face from [Image #2] on the person in [Image #1]" works in chat, or /imagine faceswap --image target.png --image2 face.png without the model.

Import still expects a CLIPTextEncode prompt when there is a sampler. A Qwen-Image-Edit graph, whose prompt goes into TextEncodeQwenImageEditPlus, needs {{prompt}} put in by hand.

The tools

• When ComfyUI refuses a run, the message names the node and input at fault (a missing checkpoint, a bad value).
• image is a path under the working directory, or a pasted picture's [Image #N] label.
  • A pasted picture is sent at its original size, not the 2048 px copy the model saw.
  • The first time it is used, it is saved into the output folder's .pasted\ subfolder (comfy_images\.pasted\pasted-20260924-153012.png); a dropped file keeps its own name. The result names the saved file.
• image2 and image3 are the further pictures, in the roles the workflow's .md names. Without a workflow name, the one that takes that many pictures is used.

Shell

Runs commands on your machine. Commands start in the working directory; workdir picks a folder under it. Shell command policy and Shell police outside paths guard it (see Shell guards). When a command is denied, the model gets an error telling it not to work around it.

• Child processes run hidden, with no window. Output is read as UTF-8, with colours and pagers turned off.
• stdin (the command's input) is closed. Background processes are the exception: they keep it open so process can write to it.
• A command that times out is killed along with everything it started. Background processes stop when the app closes. If the app crashes, running commands are left running.

Headless runs

HEADLESS.md has worked examples of every flag, the slash commands that work headless, yolo runs and scheduled jobs.

• --headless has no approval pane, so under ask only allow-listed commands run. Anything else is refused, and the model is told to say what couldn't run instead of retrying or working around it.
• If any command was refused (by the allow list or the path police), the run ends with a [notice] N commands were not run: … line and exit code 3. Exit code 0 means nothing was refused; 2 means a bad argument or an unknown profile.
• --yolo (or NEONSIDEKICK_COMMAND_POLICY=yolo; the flag wins) allows every command for one launch and is never saved. The path police still applies; --no-police (or NEONSIDEKICK_SHELL_POLICE=off) lifts it. Used together, they leave no guard at all: any command, on any path, with your account's rights.
• A headless run loads the default profile, not the one the TUI last used. --profile <name> (or NEONSIDEKICK_PROFILE; the flag wins) names another. That profile's settings, memory, sessions and allow list apply for this launch only, and settings.json is left alone. An unknown name lists the profiles and exits with code 2.

Get-Content job.txt | NeonSidekick.exe --headless --yolo --cwd D:\Repo\MyApp
Get-Content job.txt | NeonSidekick.exe --headless --profile work

Web

Memory

Skills

Sessions

Claude advisor

Questions

Plan

MCP servers

Each connected server is its own tool group. The servers connect in the background, shown as 🔌 and a count on the hint row. A reply started meanwhile gets the servers already connected, and /mcp's connect, disconnect and reload rows wait until the connecting is done.

• Its tools are named <server>__<tool> (gateway__get_current_time), so they never collide with the app's own tools.
• Each keeps the description its server gives.
• Switching a server off on the Servers tab of /mcp removes its whole group; the Tools tab switches single tools.

Where and who

LLM

Embedded LLM

Shell

Claude

Speech

Integrations

Set by the app

While Shell tool bridge is on, the app passes NEONSIDEKICK_BRIDGE_ADDRESS and NEONSIDEKICK_BRIDGE_TOKEN to an execute_code script, for the bundled neon_tools modules. Don't set them yourself. To find shells and interpreters, the app also reads the standard PATH, PATHEXT, ProgramFiles, ProgramW6432 and LocalAppData.

Test suite

These only matter when running the test suite from source. Each live test is skipped unless its resource is there.

• NEONSIDEKICK_TEST_LLM_URL, NEONSIDEKICK_TEST_TTS_URL, NEONSIDEKICK_TEST_SQL_CONNECTION: a server to test against.
• NEONSIDEKICK_TEST_ORACLE_CONNECTION: an ODP.NET connection string (`User Id=…;Password=…;Da