Using Kucatoo-Code

1. Choosing a model

The left column lists every configured model (Kimi, GLM, DeepSeek, Qwen, MiniMax). Click one to select it — it gets a green glow. The temperature slider in the header snaps to that model's default.

• no key badge — the API key for that model isn't set in .env; the model is skipped until you add one.
• The default badge marks the model used when none is selected.

2. The Prompt & Response panels

Type your request in the Prompt box (middle column). Press Ctrl+Enter (or Cmd+Enter on Mac) — or click Run — to send it. The answer streams into the Response box on the right as it's generated.

• Run turns into Stop while streaming; click it again to cancel.
• The ⎘ (copy) and 💾 (save) icons copy or save the prompt/response to disk.
• The footer shows token usage and elapsed time after each run.

Run controls: Stop, Pause/Resume, New session

• Stop — while a query streams, Run turns into Stop; click it to cancel the run.
• Pause — freezes the stream display mid-run; the button becomes Resume and the footer shows paused. Click Resume to continue exactly where you left off. (Pause holds back the stream client-side; a few already-buffered tokens may appear instantly on resume.)
• ✚ New session — clears the response, thinking block and agent trace, and starts a fresh conversation context (previous exchanges no longer influence the model). Any running query is cancelled.

3. Direct vs Agent mode

The Direct / Agent toggle in the header controls how your prompt is processed:

Direct mode (default)

Your prompt is sent straight to the selected model and the answer streams back token-by-token. Fast, single-shot, like a normal chat. Best for most questions, writing, and code.

Agent mode

The prompt is handed to an agent that runs a reasoning loop — it can think, call tools, observe results, and take several steps before giving a final answer. Use this for multi-step tasks like "read this file and summarize it" or "find the bug and fix it".

• In Agent mode, an agent type dropdown appears: react (act-observe loop), planner (breaks the goal into a plan first), or reflective (self-corrects on failure).
• The mode buttons in the header pick what the agent may do: Explore (read-only investigation), Plan (read-only, asks you clarifying questions, then produces a structured plan), Write & Test (full access, runs code/tests to verify its work), or Write (no test) (full write access, but never runs tests, validators, or builds unless you ask). Write modes ask for approval on each write unless you tick auto-approve.
• An Agent trace panel appears under the Response box, showing each thought, tool call, and observation live as it runs.
• The final answer still lands in the Response box.

4. The Agent trace

In Agent mode, a Trace button appears in the Prompt column header. Click it to swap the prompt editor for the Agent trace: the agent's reasoning loop live, one row per event, auto-scrolling as it runs (the button becomes Prompt — click again to switch back). Each row has a coloured label on the left:

• thought (grey) — the agent's reasoning about what to do next.
• tool (orange) — a tool call, with its arguments as JSON, e.g. write_file {"filepath": "recipes/pie.md", ...}.
• obs (accent) — the observation: the result the tool returned, which the agent reads before its next thought.
• step — a step boundary/status marker in the reasoning loop.
• failed (red) — a step that failed; the agent typically self-corrects on the next step (especially with the reflective strategy).

Header controls

• Agent type dropdown — the reasoning strategy: reflective (self-corrects on failure), react (thought → act → observe loop), or planner (writes a plan first, then executes it).
• steps input — maximum reasoning steps (3–60, default 30) before the agent stops, as a guard against runaway loops.
• Auto-approve writes/tests checkbox — when ticked, tools that modify disk or run code (write_file, execute_python) run immediately without asking. When unticked, each such call pauses the run and shows an Approve / Deny card above the trace — the run waits until you answer.
• × button — clears the trace. The trace is also cleared automatically when you start a new run.
• 💾 button — saves the trace to disk (the traces directory) on its own, without saving the response.
• 🔍 button — analyzes the trace with AI (see below).

Analyzing the trace with AI

The 🔍 (analyze) icon in the trace header saves the current trace and opens the Trace Analysis panel at the side of the window. The trace is summarized, sent to an LLM, and the panel shows a read-out of the run: what the agent did, where it struggled, and how it reached its answer.

• Model dropdown — which LLM performs the analysis. Your choice is remembered for the session; the default comes from the saved analysis-model preference.
• Ask about this trace… — the input at the bottom of the panel asks follow-up questions (why did the agent call delete_file?); the conversation keeps the trace as context.
• Copy / Save icons — export the analysis transcript as Markdown, to the clipboard or as a downloaded trace_analysis_*.md file.
• × — closes the panel. The conversation is kept for the session and restored when you reopen the analysis.

Analyzing prompts & responses

The same panel analyzes more than traces. The 🔍 icon in the Response column header analyzes the current prompt + response pair — does the answer actually address the prompt, where it falls short, and how to improve it. When the run has an agent trace, an Include trace checkbox appears in the panel (on by default) so all three — prompt, response, and trace — are analyzed together for deeper process insight; untick it and the analysis re-runs on the pair alone.

The History tab has an Analyze series button: it reviews the sequence of prompt/response pairs recorded under the active workspace — recurring themes, repeated failure modes, and how the work is evolving. Only runs made under workspace tagging count, so the series builds up as you use the app.

Quantified improvement: every analysis ends with a machine-readable SCORES: line (1–10 ratings) and is appended with objective metrics (steps, tool calls, failures, tokens, run counts) to analysis_log.jsonl in the data directory. GET /api/analysis/log returns the records plus mean-score aggregates, so you — or an LLM — can diff two periods and measure whether things are actually getting better.

Saving the trace

The 💾 (save) icon in the Response header saves the response text to the responses directory and, if a trace is present, writes a companion file with the same name plus a .trace.txt suffix, so the two files sort together and you can see exactly how the answer was produced.

Tip: the final answer always lands in the Response box — the trace is the "working out", not the result.

5. Tools & "Run tool"

Tools are actions the agent (or you) can invoke: read_file, write_file, list_files, web_search, and execute_python. They live in the Tools tab of the right-hand console.

Enabling tools for an agent run

Tick the checkboxes next to the tools you want available. When you next run in Agent mode, only the checked tools can be used. (Direct mode ignores tools — it's a plain completion.)

"Run tool" — calling a tool directly

You don't need an agent to use a tool. At the bottom of the Tools tab:

1. Type a tool name (e.g. read_file). Both fields are multi-line — drag their lower edge to make them taller.
2. Enter its arguments as JSON, e.g. {"filepath": "README.md"}.
3. Click Run tool.

The result appears in the output box below. This is handy for quick file reads or testing a tool before wiring it into an agent.

Examples

• read_file — {"filepath": "notes/todo.md"} returns the file's contents (add "max_lines": 50 to cap it).
• write_file — {"filepath": "recipes/pie.md", "content": "# Pie\n…"} writes the file (asks for confirmation first).
• list_files — {"pattern": "*.md"} lists matching files in the workspace (add "directory": "recipes", "recursive": true to search a subfolder tree).
• web_search — {"query": "kucatoo pie", "top_k": 3} searches the web (needs TAVILY_API_KEY).
• execute_python — {"code": "print(sum(range(10)))"} runs sandboxed Python (no file/network access; asks for confirmation).

Where files live: the file tools are sandboxed to the agent workspace — the WORKSPACE_DIR setting in .env (default: a workspace folder next to the data directory). Paths outside it are refused.

Note: write_file and execute_python are marked confirm — they modify disk or run code, so they require confirmation.

6. Memory

The harness remembers things across runs in a tiered store (short / medium / long term). The Memory tab lets you search and add to it.

• Recall — type a query and hit Recall (or Enter). It returns the most relevant stored memories by semantic similarity. Example: pie recipes finds "the user likes fruit pies" even though the words differ.
• Remember — type a fact (e.g. "the user prefers concise answers" or "workspace files go to D:/kucatoo-code/workspace") and click Remember to store it for future runs.

In Agent mode, the agent automatically pulls relevant memories into its context, so things you've remembered influence its answers. Example: after remembering "the user is allergic to nuts", a later agent run asked for a cake recipe will avoid nuts without being told.

Remembering from chat (memory proposals)

In Direct mode you can store a fact straight from the chat: start your prompt with a trigger phrase like remember that…, remember this…, note that…, don't forget…, memorize…, add … to memory, or keep in mind…. The app detects the intent before calling the model (no tokens are spent), extracts the fact, and shows a confirmation card in the chat with Remember and Dismiss buttons. Example: typing remember that my editor is Neovim proposes the fact "my editor is Neovim".

• Remember stores the fact via the same endpoint the Memory tab uses — it behaves exactly as if you had typed it there.
• Dismiss stores nothing; the card collapses to "Not stored — kept in conversation context." The prompt still lives in your session history, so the model can use it for the rest of the conversation — it just won't survive into future sessions.
• Each proposal gets its own card, so several remember-prompts in one session can be confirmed or dismissed independently.

Detection is deliberately conservative: the trigger phrase must lead the prompt and yield a usable fact. Questions such as "do you remember my name?" are not intercepted — they go to the model as normal chat. Likewise, indirect phrasings ("hey, could you maybe remember…") intentionally fall through to normal chat rather than risk false positives. To switch proposals off entirely, set direct_chat_memory_proposals: false in the harness YAML config and restart the server.

Try it: type remember that my editor is Neovim and click Remember, then recall which text editor does the user like in the Memory tab — semantic search finds it even though the wording differs.

7. Voice: dictation, editing & spoken responses (STT/TTS)

You can talk to the app instead of typing, and have it read answers back to you. Two buttons control this: the mic button (🎙) in the Prompt panel header for dictation (speech to text), and the Speak toggle (🔊) in the Response panel header for spoken responses (text to speech).

Dictation uses the browser's Web Speech API, which is available in Chrome and Edge — on other browsers (e.g. Firefox) the mic button stays hidden. The first time you click the mic, the browser asks for microphone permission; allow it once and it sticks. Spoken responses use the browser's built-in speech synthesis, which works in most browsers; if it's unavailable, the Speak button stays hidden.

A typical dictation workflow

1. Click the mic button — a red pulsing dot shows you're recording, and the dictation panel opens below the prompt box.
2. Dictate naturally. Each time you pause, that spoken chunk is cleaned up (filler words, false starts and speech-to-text glitches removed) and appended to the draft.
3. Watch the two panes: Raw transcript (everything verbatim) on the left, Interpreted draft (the cleaned version) on the right.
4. Fix anything by hand-editing the draft, or with a voice command (see below) — e.g. "computer, make that more formal".
5. Click Apply prompt — the draft is copied into the prompt box. Clear empties both panes and closes the panel.
6. Review the prompt and hit Run when ready. Nothing is ever sent automatically — your voice only ever fills the prompt box; you always press Run yourself.

How the cleanup works (STT details)

Cleanup is pause-triggered, not continuous: each time an utterance finalizes (you pause), that chunk is sent to a small cleanup model which fixes speech-to-text artifacts, disfluencies and false starts, and resolves explicit self-corrections ("born in Hanoi — no wait, Saigon" keeps Saigon). The cleaned text is appended to the interpreted draft, so your manual edits are never overwritten by new utterances — only edit commands replace the draft. The raw pane always preserves the verbatim transcript.

If the cleanup model is unreachable, dictation silently falls back to raw transcripts only — nothing breaks. Controlled by stt_assist_enabled (default true) and stt_assist_model (default deepseek-v4-flash) in the harness YAML config; restart the server after changing them.

Voice editing

• Wake word — start an utterance with computer and it becomes an edit instruction applied to the draft instead of dictation content.
• Push-to-talk command mode — hold the Space bar (while not typing in a text box) and everything you say until you release it is an edit instruction. The panel border highlights while command mode is active.

Example instructions:

• delete the last sentence
• make it more formal
• change Saigon to Hanoi
• start over (clears the draft)
• apply prompt (or send it) — moves the draft into the prompt box, same as the Apply prompt button; still never auto-sends
• clear draft / clear raw / clear prompt / clear all — empties the interpreted draft, the raw transcript, the prompt box, or everything (panel stays open)

You can always hand-edit either pane instead — draft edits are kept and new dictated chunks are appended after them.

Spoken responses (TTS)

Toggle Speak (🔊) in the Response panel header and each finished direct-mode answer is read aloud. Toggling it off — or starting a new query — stops playback immediately. Code blocks are summarized as "code block" rather than read character by character. Voice and quality depend on the speech voices installed in your OS/browser.

Tips

• Dictate punctuation explicitly (comma, period, new line) — the cleanup handles the rest.
• Speak in complete chunks rather than single words — fewer, better cleanups.
• Use command mode (or the wake word) for edits so instructions don't land in the draft as content.
• Troubleshooting: Chrome dictation routes audio through Google's speech service, so VPNs/firewalls can block it (symptom: recording dot pulses but nothing is transcribed) — check chrome://speech-internals for error codes such as network or not-allowed.

8. Skills

Skills are higher-level, pre-built capabilities that combine a model with a prompt and (optionally) tools — e.g. code_review, summarizer, translator, debugger. The Skills tab lists them.

To run one — example with summarizer:

1. Enter the skill id: summarizer.
2. Provide its parameters as JSON, e.g. {"text": "The long article text goes here…"} (each skill lists its required params under its name).
3. Click Run skill.

The skill's output appears below — for summarizer, a condensed version of the text you passed. Other examples: translator with {"text": "Hello", "target_language": "French"}, or code_review with {"filepath": "run_webapp.py"}. Skills are a shortcut for common, well-structured tasks.

9. Status

The Status tab shows a live snapshot of the whole harness — click Refresh to update it. You'll see:

• capabilities — which subsystems are wired (provider mesh, tools, agents, memory, workflows, skills, domains, profiles).
• health — per-model circuit-breaker state (healthy / degraded / down). Example: if Kimi returns errors, its entry flips to degraded and routing avoids it until it recovers.
• cost — cumulative token spend, by model and total. Example: {"total_tokens": 15420, "cost_usd": 0.0123}.

Useful if a model is failing — check here whether it's marked down. Example workflow: a query fails with 402 Insufficient Balance → open Status → the model shows down → top up that provider or pick another model.

10. Workspaces

Workspaces are project folders. The workspace root is set by WORKSPACE_DIR in the app's .env file — the root itself and every subdirectory of it is a selectable workspace, so you can keep one folder per project and switch between them.

The workspace bar (second header row) has a dropdown of all workspaces, a New button to create a project folder, and a Stats button. Switching workspaces changes the root that all file tools, the Files tab, and context files operate on; the choice is remembered across restarts.

Per-workspace stats

Every query is recorded against the active workspace. Click Stats to see, for the current workspace: total queries, tokens (prompt / completion / cached), cost in USD, cumulative elapsed time, and a per-provider/model breakdown with first and last activity. Stats persist on disk, so they survive restarts.

11. Context files

You can attach files from the active workspace to any query — their contents are injected into the prompt as a === Context files === block, in both Direct and Agent mode. There are two ways to attach:

• Drag & drop — drop files from your OS anywhere on the prompt panel (it highlights). Dropped files are uploaded into the active workspace first, then attached.
• Attach file button (📄, next to the image button) — opens a picker that browses the active workspace; tick multiple files and choose Attach selected.

Attached files appear as removable chips under the image thumbnails and are cleared after each run. Limits: up to 20 files, 20 KB per file, 200 KB total; binary files are skipped. You can also attach files straight from the Files tab via Add to context.

12. The Files tab

The Files tab is a file explorer for the active workspace. While it is open, the console column widens to four times the width of the Prompt/Response columns (which shrink accordingly) to give you room to work; switching to another tab restores the normal layout.

• Browse — click a directory to enter it, use the breadcrumbs or Up to go back. .git, venv, __pycache__, node_modules and backup folders are hidden.
• View & edit — click a text file to open it in the editor, edit, then Save (the previous version is backed up automatically). Image files (PNG, JPG, …) open in an image viewer.
• Select — tick individual files or use the all checkbox to select everything in the current directory, then use the toolbar:

• Zip — download the selected files/folders as a zip (auto-generated and venv content excluded).
• Backup — copy the selection into a timestamped backup under .kucatoo_backups/ in the workspace.
• Restore — pick a file, choose one of its backups, and revert to it (the current content is backed up first).
• Delete, New folder — with a confirmation prompt.
• +.gitignore / −.gitignore — add or remove the selected paths in the workspace's .gitignore (created if missing).
• Add to context — attach the selected files to your next query (see Context files).

13. The Sites tab

The Sites tab is the control panel for the whole Kucatoo site family. It reads the registry (Kucatoo-Sites' projects.json) and merges in live status, so one row per site shows everything at a glance:

• Status dot — green: something answers HTTP on the site's registered port. Grey: offline. The check is done live each time the list loads, so Refresh re-probes every port.
• Group — the harness folder the site lives under (Qwen-Code, Kucatoo-Code, Legacy, Archive), per the file-structure layout.
• Stage badges — dev is always present; beta/prod light up once those worktrees exist. When prod exists, the row also shows the tag it sits on (e.g. prod@v1.0.0).

Slow actions (starting a big site, running the backup mirrors) show the rainbow spinner with a timer in the corner of the panel.

Start / Stop / Log

• Start runs the site's registered start script (start.bat / run.bat) detached, with output appended to data\site_logs\<site>.log. If the port already answers, Start refuses — that's your signal it's already up.
• Stop finds the process that owns the site's port and kills its whole process tree (after a confirmation). Use it instead of hunting PIDs.
• Log shows the tail of the launch log — the first place to look when a site won't come up.
• Kucatoo-Code itself is protected: its row has no Start/Stop buttons. Manage it with the server controls in the header, so the console can't saw off the branch it's sitting on.

Staging: what beta and prod are

Each site is a git repo checked out at Sites\<Group>\<Site>\dev. The +beta and +prod buttons create the other stages as git worktrees — additional working directories that share the same repository history. A worktree is not a copy: there is one .git, and each stage directory simply has a different commit checked out. This makes staging cheap and exact: prod\ can sit on a release tag while dev\ moves ahead.

• +beta creates beta\ on a stage-beta branch at dev's current HEAD — a release-candidate sandbox you can run and test in parallel.
• +prod creates prod\ the same way. You normally don't need to click it by hand — Promote creates the prod worktree automatically on first use.

Promote, in detail

Promote is the release button: it takes whatever is committed on dev right now and makes it the production version. Clicking it asks for a tag name, then does exactly this:

1. Validates the tag name and refuses if the tag already exists (so you can't silently overwrite a release).
2. Tags dev HEAD — an annotated git tag (e.g. v1.0.0) is created on the latest commit of the site's dev checkout. Only committed work is tagged — uncommitted edits in dev are not included, so commit first.
3. Points prod at the tag — if there is no prod\ worktree yet, it is created as a checkout of the tag; if one exists, it is switched (git checkout) to the new tag. Either way, prod\ afterwards contains exactly the tagged code.

The row then shows prod@v1.0.0 (or whatever the tag is), which is read live from the prod worktree on every Refresh.

• Typical flow: work in dev\ → commit → optionally test in beta\ → Promote v1.1.0 → run the site from prod\.
• Rollback: point prod at an older tag with git — git -C prod checkout v1.0.0 (Promote deliberately refuses existing tags, so rollback is a git command, or you promote a fix forward as a new tag). Promote never deletes or rewrites tags.
• Failure modes are explicit: a duplicate tag name is rejected up front; if the prod checkout fails after tagging, the error says so and the tag remains (safe to retry after fixing the checkout problem, e.g. uncommitted edits inside prod\).
• Never edit inside prod\ — it is a checkout of a tag; changes there are detached from any branch and will block the next promote.

Run backup

Mirrors F:\Kucatoo\Sites, F:\Kucatoo\Data, and F:\customers to D:\Backups\Kucatoo\ with robocopy (venvs, node_modules, model weights excluded — they're reproducible). The summary of each job appears in the panel output, and the full log is appended to data\site_logs\backup.log. The spinner runs for the duration — the first full mirror can take minutes, later ones only copy changes.

Rule of thumb: edit only in dev\; prod\ should always sit on a tag.

14. Tips & shortcuts

• Ctrl/Cmd + Enter in the prompt box = Run.
• The temperature slider is sent with each query; higher = more creative, lower = more deterministic. (Kimi models require temperature 1.)
• The theme toggle (☼) switches dark/light high-contrast and is remembered across reloads.
• The A− / A+ controls adjust font size.
• If a model errors with 402 Insufficient Balance or no key, it's an account/config issue — see the Status tab and your .env.
• The History tab (console column) records every completed run automatically — prompt, response, model, elapsed time. Click an entry to reload it into the Prompt/Response boxes.
• Help opens in a new browser tab, so you can keep it next to the app.