User guide

Version 0.0.6-alpha.2 for Windows. Twelve short guides, one per area of the app. Every button name, menu path, keyboard shortcut and on-screen message below was taken from the installed build, and every screenshot is of that build running a small demo project.

New to Catalase? Read Getting started, then dip into whichever section you need.

What's in this guide

1. Getting started

Install Catalase, finish the welcome steps, and open your first project.

Install

1. Run Catalase-Setup-0.0.6-alpha.2.exe and choose an install folder.
2. If Windows shows "Windows protected your PC", choose More info → Run anyway.
3. Upgrading? Run the new installer over your existing copy. Your API keys, preferences and conversations are kept, and your panels keep their current order.

Get the installer from the download page.

First launch

1. Catalase starts its AI backend in the background. The status line under the chat box reads 🔌 Plugging in… for up to about 30 seconds the first time after a restart, then ✅ Connected.
2. The Welcome to Catalase screen checks two things:
   • 1 · Local model (required for inline suggestions). If Ollama isn't found, install it and click Re-check, or click Browse models.
   • 2 · Plan (optional). Connect a subscription you already have, or add an API key in Settings.
3. Click Done, or Skip to set things up later.
4. Open a project with File → Open Folder…. Catalase reopens that folder next time.

Finding your way around

• Left: Explorer and Source Control. Centre: the editor, with the terminal below it. Right: Chat.
• Rearrange panels by dragging the ⠿ grip in any panel's header. Your order is remembered, including if you quit straight afterwards.
• Toolbar (top right): Move chat · Watch your agent · Conversations · Marketplace · Settings (Ctrl+Shift+,). At narrow widths the toolbar wraps so every button stays reachable.

2. Explorer

Open a project folder and manage its files. Left panel.

Open a project

• Click Open Folder, or use File → Open Folder….
• From a terminal or shortcut: Catalase.exe "C:\path\to\project". A folder given this way wins over the remembered one.
• File → New Project… starts one from scratch: pick a location, type a name, and Catalase creates that folder and opens it. If the name is already taken it says so rather than writing into the existing folder.
• File → Close Folder puts you back to the no-folder state without quitting.
• If the remembered folder has been moved or deleted, Catalase starts with no folder open.

Manage files

Catalase won't overwrite: creating or renaming onto an existing name is refused with a message. Files show their git state (modified, staged, untracked) next to the name.

3. Editor

Edit code in tabs, with AI suggestions as you type and Python code intelligence.

Everyday shortcuts

The full list is in Settings → Keybindings.

AI suggestions as you type

1. Make sure a local model is installed (see Models and providers).
2. Turn on Settings → Editor → Inline suggestions.
3. Type. Grey ghost text appears: Tab accepts, Esc dismisses, Alt+] shows the next suggestion.

Speed can vary with your hardware: roughly 50–200 ms with a dedicated GPU, 0.5–3 s on CPU only, where a smaller model is recommended.

Appearance

Settings → Editor offers Dark, Light and High Contrast, plus font size and tab size. Changes persist across restarts.

4. Terminal

A PowerShell terminal inside the window, opened in your project folder.

• Show or hide it with Ctrl+` or View → Toggle Terminal.
• Run → Focus Terminal moves the cursor into it.
• In chat, type @terminal to give the AI the terminal's recent output, for example to explain an error.

"Waiting for input"

If a command stops to ask something (a password, Continue? (y/n)), a banner reads ⚠ Waiting for input: "…", so you (or the agent) know it's waiting. Answer in the terminal and the banner clears.

5. Source Control

Review changes, commit with an AI-written message, publish your work. Left panel, below the Explorer.

Commit your changes

1. Changed files are grouped into Staged Changes, Changes and Untracked. Click ⟳ to refresh.
2. Stage what you want. Click a file to see its diff, and 💬 Explain for a plain-language summary.
3. Type a message, or click Generate to have AI write one from your staged changes.
4. Click Commit. If nothing is staged, Catalase offers to stage everything and commit.

Branches and publishing

6. Chat

Ask questions about your code. Chat panel, centre by default.

Ask a question

1. Choose a model in the picker: local, API-key, or a connected subscription.
2. Optionally choose a kind of help: Ask anything, Explain, Refactor, Debug, Generate tests or Document.
3. Type and press Enter. Shift+Enter makes a new line.

Add context

• Mention files: type @ and pick a file, or @terminal for recent output.
• The + menu: attach a file, mention a project file, clear the conversation, rewind, switch model, set effort, toggle thinking.
• Images: attach screenshots for vision-capable models. Images are sent in regular chat, not in Agent mode.

While it's answering

• Press the stop button to interrupt.
• Send another message and it waits its turn: a banner shows it queued, with Cancel if you change your mind. It sends automatically when the current turn ends.
• Set Effort (low, medium, high) for models that support it.
• If a message fails, Catalase can retry with the next available model.

Reading the status line

7. Agent mode

Let the AI read files, make edits and run commands in your project, with your approval.

Start an agent task

1. Open a project folder. Agent mode needs one.
2. Pick Agent from the mode dropdown at the top of the chat panel. The same dropdown holds Chat (answers only, never touches your files) and Plan (writes a plan first and asks before doing anything).
3. Choose how much it should ask you, describe the task, and send.

Review what it does

• Each proposed action appears as a card with its risk level. Approve or reject it.
• After a file change runs, Undo on its card is designed to reverse that change.
• In Plan mode the plan opens in a read-only tab; click Execute plan when happy.
• Open Watch your agent (toolbar) to see what it's doing. The scene is draggable and resizable.

8. Commands and memory

Slash commands, your own project commands, project memory and MCP tools. Chat input.

Built-in commands

Type the whole command and press Enter. You don't have to pick it from the dropdown, and one Enter is enough. Type / on its own to browse the list, or run /help for the current one.

Your own commands

1. Create .catalase/commands/ in your project.
2. Add a Markdown file, e.g. changelog.md, containing the prompt. Use $ARGUMENTS where text typed after the command should go.
3. Type /changelog since last release. Custom commands also appear in the / list.

MCP tools

Add your servers to .catalase/mcp_servers.json in the project; their tools become available to the agent. Run /mcp to check they connected.

9. Conversations

Find, resume and branch past conversations. Toolbar → Conversations.

• + New conversation starts fresh.
• Search by title; click a conversation to resume it.
• Rename or archive to tidy the list; tick Show archived to see archived ones.

Go back or branch off

Hover an earlier message of yours:

10. Project snapshots

Pick up where you left off. Catalase saves a picture of your project's structure and gives it to the AI when you resume.

How it works

• A snapshot (a dependency-graph image plus a text summary) is taken when you close the app, every 30 minutes (skipped when nothing changed), and when you run /remember, which is designed to take one as well.
• Snapshots live in your project's .catalase\context folder, one per day.
• Progress shows as 📸 VCM Snapshot in the Agent Activity panel.

Resume a session

1. Open the project. If a snapshot from today exists, a banner reads A project snapshot from today is available (experimental).
2. Click Resume. With a vision-capable model the image goes with your first message; other models get the text summary.
3. Click Dismiss to start without it.

11. Models and providers

Choose where AI comes from: local models, API keys, or subscriptions you already pay for.

Three ways to connect

Model routing

Settings → Model routing lets you pick a model per task: Chat, Commit messages, PR title/body/changelog, Explain diff and Code review. Leave any on Use default. For example: a fast local model for commit messages, a stronger cloud model for code review.

The Model picker

Clicking the model name opens a picker split into two parts:

• The top section is what you can use right now: your local Ollama models, any subscription CLI you have installed, and any provider you have saved a key for.
• "Needs setup" is collapsed, and lists what you could use once you add a key or sign in. Its entries are greyed out with a lock and cannot be selected; the link inside it takes you straight to Settings.

Switching quickly

Use /model sonnet in chat. /model alone lists everything available; an ambiguous query lists the candidates instead of guessing.

Large local models with llama.cpp (advanced)

1. Open Settings → Local inference backend. Catalase shows your RAM and GPU, recommends Ollama or llama.cpp, and suggests a quantization level.
2. Install Python with pip install llama-cpp-python.
3. Pick that Python from the suggested list or enter its path. You can either save it (Catalase launches it to check it works) or click Install llama-cpp-python, which runs a real pip install against that interpreter and streams the progress.

12. Privacy, cost and activity

Keep code on your machine, control spending, see what's running. For what leaves your machine and when, read the privacy page.

See what's running

• Agent Activity lists Running, Scheduled and Completed jobs: chat and agent turns, repo map indexing, snapshots, commit messages, diff explanations, model downloads and the language server.
• Watch your agent (Agent Office) shows the agent at work and offers Review in chat when it's done.

Catalase 0.0.6-alpha.2 for Windows · guide prepared 2026-10-04. Every instruction, message and screenshot here comes from the installed build. Screenshots use a small demo project, so no real code appears in them.