Skip to main content

​
Conversations

A conversation is the basic unit of work in Headmaster. You type a message, the agent responds, and the exchange is saved as a session you can resume later.

​
Creating a new conversation

Click New chat in the sidebar. A fresh conversation starts with no context from previous chats. When you start a new conversation, you pick:
  1. An agent — the built-in engine (default), or any detected CLI agent (Claude Code, Codex, Gemini CLI, etc.). Each agent has its own model list.
  2. A model — from the agent’s available models. Use the selector at the bottom-left of the composer.
  3. A specialist (optional) — a pre-configured persona with rules and skills. See Specialists.
The agent and model you pick are remembered for this conversation. New conversations start with your default agent and model.

​
Streaming responses

The agent’s response streams into the chat window token by token. You see it being written in real time. While the agent is working, you can:
  • Watch the response as it streams.
  • Scroll up to review earlier parts while still generating.
  • Interrupt by clicking the stop button next to the composer.

​
What appears in a response

​
Follow-up messages

After the agent responds, type a follow-up and press Enter. The agent has the full conversation context and responds accordingly. Selection reply: Select text in the agent’s response and a reply button appears. Click it to quote the selected text in your follow-up — useful for asking about a specific part of the response.

​
Editing and undo

  • Edit your last message — click the edit button on your most recent message. Edit it, re-send, and the conversation continues from the edited point.
  • Undo — click the undo button to back up one turn. Your message and the agent’s response are removed. Undo multiple turns as needed.

​
Interrupting and steering

If the agent is going in a wrong direction, click the stop button. The agent stops and the partial response stays in the chat. Send a corrective message to redirect:
Mid-run steering: You can also redirect mid-task without breaking context. While the agent is working, type a new message and send it. The agent pauses, reads your instruction, and adjusts.

​
Multiple conversations

You can have many conversations open at once — each with independent memory, model, specialist, and project folder. Switch between them in the sidebar. Start a new one with New chat.

​
Running tasks in parallel

  • Run a code review in one chat.
  • Generate a deck in another.
  • Research a topic in a third.
All at the same time, all with their own context, with no bleed-through between conversations.

​
Project (working folder)

Open a folder as a project to give the agent scoped file access:
1

Click the + button

Click the + button next to the composer and select Open folder.
2

Pick a folder

Choose a folder from the file dialog. The Workspace panel appears on the right with the folder tree.
3

Work within the folder

The agent can read and write files inside the project folder without per-access approval. Files outside the folder still require approval each time.
A folder is locked per conversation. To work in a different folder, start a new chat. This prevents the agent from confusing two projects’ file trees.

​
Workspace panel

The Workspace panel shows:
  • File tree — folder hierarchy with expand/collapse.
  • File tabs — open files in tabs, switch between them.
  • Context menu — right-click a file for options (open, rename, delete, copy path).
  • File change list — when the agent modifies files, a list of changes appears at the top.

​
File upload

Attach files to your message in several ways:
  • Drag and drop files directly into the composer.
  • Click the + button and choose files from disk.
  • Paste files from your clipboard.
  • @file: mention syntax — reference a file in your message:
Supported file types: text files, images, code files, PDFs, Office documents (.docx, .xlsx, .pptx), archives (.zip, .tar.gz), and more.

​
Mention dropdown

Type @ in the composer to open the mention dropdown. It shows:
  • Files — files in your current project folder.
  • Specialists — available specialists to mention.
  • Skills — available skills to reference.

​
Slash commands

Type / in the composer to open the slash command menu:

​
Session persistence

Conversations are saved automatically. When you close and reopen Headmaster, your conversation list is in the sidebar exactly as you left it. Click any conversation to resume — the agent picks up with the full context. Sessions are stored in <data folder>/sessions/. Each session is a JSON file with the full transcript, tool call records, and metadata.

​
Managing your conversation history

The sidebar shows conversations most recent first. Each entry shows the first message (as a title), the date, the specialist used (if any), and whether the session was triggered by a scheduled task. You can:
  • Search conversations by typing in the search bar at the top of the sidebar.
  • Pin important conversations to keep them at the top.
  • Rename a conversation by clicking its title.
  • Delete a conversation — removes the session file permanently.
  • Group conversations by date (Today, Yesterday, This Week, Earlier).

​
Stale session recovery

If the runtime restarts while a conversation is mid-stream, the session becomes stale. Headmaster detects this and shows a Recover button. Click it to resume — the agent picks up where it left off with the full transcript preserved.

Memory

How the agent remembers facts across conversations.

Modes

Work Along, Run It Yourself, Hands-Off, and Autopilot explained.