User guide

Threads Partly available

A thread is the record of one agent session in one repository. GitMaster captures the conversation, every tool call the agent made and every file edit, stores it in a database inside the repository's .git directory, and shows it on the Threads page. You can search old threads, open an agent's edit as a diff, link a thread to a commit, and delete what you do not want to keep.

Threads are captured by the agent integration. Install it first: see Agent integration.

What a thread holds#

A thread does not hold the model's reasoning, images or other attachments. An image shows as a placeholder with its type and size.

Claude Code wraps some of what it writes in its own tags: slash commands, the output of commands and of bash runs, and context it gives the agent. GitMaster shows a slash command as you typed it (/model opus), shows command output and interruptions as notices, and leaves out the reminders the agent was given.

A thread belongs to the repository where the agent ran. A session started in a linked worktree is stored with the repository, and every worktree sees it. A session that ran outside a Git repository is not captured.

Open the Threads page#

Choose Threads in the sidebar, or run Show Threads from the command palette. The list is on the left and the selected thread is on the right.

Each row of the list shows the title, the agent, the branch, how long ago the last event was, and how many edits the thread made. A dot marks a session that is still open. A redacted mark shows when GitMaster removed a secret from the thread.

The title comes from your first prompt, as plain text: the first non-empty line, with the Markdown markers, emphasis and links removed. A title is cut at 80 characters. You can rename it.

Read a thread#

The header of the thread takes two lines. The first has the title, then the star button, Copy as Markdown and ⋯. The star is filled when the thread is starred. The ⋯ button opens the less used actions, listed under Keep and clean up. The second line has the agent, the branch, when the thread started and whether it is still open, then the chips: N commits, N files, N edits and, when the thread has one, Note.

A commit chip, a file chip or the Note chip opens a details panel under the header. Only one panel is open at a time, and a click on its chip closes it. The commits panel lists each commit with whether it was created during this thread or linked by you; a link you made has Unlink. The files panel lists each edited file once, with the lines its edits added and removed. A path inside the worktree is shown relative to it, a path inside your home folder starts with ~, and a long path is cut at its start so the file name stays visible. The Note panel shows the note in full. A panel is at most six rows high and scrolls past that.

The thread is grouped by turn. A turn is one prompt of yours and everything the agent did until it stopped. Each turn starts with a thin divider that says Turn n; the first turn has no divider.

• Your prompt is marked You in the left column and has a thin accent bar. The agent's text shows in full, as Markdown: headings, bold, italic and strikethrough, lists and task lists, quotes, tables, code blocks and links, and it is marked Agent in the left column. A run of replies with no prompt between them names the agent once, on the first. A code block in a language GitMaster knows is coloured, and a link shows its text without being followed. Tool arguments and results stay plain text.
• Each tool call is one line with the tool, a short summary of its arguments, whether it worked and how long it took. Select the line to expand the arguments and the result. A Delete entry control appears at the line's right end while the pointer is over it.
• Each edit is one line with the path, +n −m, its state, Open Diff and View File. Open Diff expands the patch under the line, and View File opens the file in the Code page.

The thread loads as you scroll. The first entries appear at once, and the next page is read when you come near the end of what is shown. A search result opens at its entry, and the entries before it are read when you scroll to the top. A line at the end says Loading… while a page is read and End of thread when there is nothing more.

Tool calls that follow each other in a turn form a group. Its header says how many calls there are and which tools ran, most used first:

▸ 5 tool calls: Edit ×2, Read ×2, Bash ×1 · 2 edits

A group shows its edits and any failed call even while it is closed. Select the header to open the group, and select a call inside it to see its arguments and result. The Expand all and Collapse all buttons above the thread open or close every group at once. A group is closed when you open a thread, except the one that holds a search result.

An edit has one of these states, worked out each time you open the thread from the files themselves:

An edit that GitMaster could not measure from the file, for example because the file was too large, is marked From tool input and shows what the agent asked for, not what the file contained.

Changes that are not edits#

Only the agent's file-editing tools produce edits. A change made by a shell command, a formatter or a code generator appears as the command and its output, not as an edit.

Search threads#

Type in the search box above the list. There is no search syntax.

Search covers what you and the agent said: your prompts and the agent's replies, and the names of the files the agent edited. It does not search the tool calls or their output, such as the arguments of a command, the output of a command or the text of a file the agent read. Those stay in the thread and you can read them there, but a word that appears only in them does not match.

• Words are matched as the start of a word, and all of them must appear. retry back finds retry backoff.
• Put words in double quotes to match them as a phrase.
• Identifiers match whole, so file_index finds file_index and not every file.

When these matches are few (fewer than eight), GitMaster also looks further, after the exact matches:

• Text inside a word. The letters you type are found anywhere in a word, whatever the case: index finds file_index, and stream finds HistoryStream. These hits are marked approx..
• Close misspellings. A word with a letter swapped, missing or wrong is found when most of its letters appear in the same order in a word of the thread: bakcoff finds backoff. These hits are marked approx. too.

Words shorter than three characters are matched at the start of a word only, so in does not find join. In quotes, the text is matched exactly, inside words too, and a phrase is never matched by misspelling.

Each thread appears once, with its best match: a snippet around the match, the agent, the branch, when the thread started and how many edits it made. The results load a page at a time as you scroll. When a search with a filter finds nothing, GitMaster says which filter, removed, would bring matches back. Select a result to open the thread at that entry.

Narrow the list with the Starred and Has edits chips. To list the threads that edited one file, choose Show Threads for File on that file in the Working Copy. A removable chip shows the file.

Search runs on your machine over the prompts, replies and edited file names stored for each thread, and its indexes are kept in the same local database. Nothing is sent anywhere.

Link threads to your work#

Threads for a file or a commit#

Choose Show Threads for File in the menu of a file in the Working Copy to list the threads that edited that file.

Select a commit in History and its panel lists the threads linked to it, under THREADS. Each row shows the title, the agent and how long ago the thread was active. Select a row to open that thread on this page, even when a filter would leave it out. The section lists the newest ten threads, and says so when more follow.

How a commit gets linked#

GitMaster links a thread to a commit in two ways only:

• Created during this thread. The commit appeared on the thread's branch between two events of the thread. This says when the commit was made, not who made it: a commit you made yourself in the same period also counts.
• Linked by you. Choose Link Thread to Commit… in the ⋯ menu of the thread's header and pick the commit. The thread's Commits panel shows the link as linked by you, with Unlink beside it. Unlinking removes the link only; the commit is untouched.

The Commits chip of the header counts both kinds. The Files panel lists the files the thread edited, and a file you linked by hand, with its own Unlink.

GitMaster never guesses that a thread produced a commit because the contents look alike.

Threads in a workspace#

An agent started in a workspace works in several repositories at once. Its thread is stored once, in the workspace repository, and names the member each part belongs to:

• Edits. An edit of a file inside a member names that member. Its state, in working tree, in HEAD or changed since, is read from the member: from its files and from its own HEAD.
• Commits. A commit that appeared on a member's branch between two events of the thread is linked as created during this thread, the same rule as for the workspace's own branch. The Commits panel shows the member beside each commit.

Each member's repository keeps a list of the workspaces it belongs to, in its .git directory, written when the member is added and removed with it. When you open the member's repository on its own, the THREADS section of a commit in History also lists the workspace threads linked to that commit, each marked with the workspace's name. Selecting one opens the workspace in its own window.

After a rewrite#

A rewrite gives commits new ids: a rebase, an amend or a squash makes new commits from the old ones. A commit link follows the rewrite as follows:

• A restack in GitMaster keeps every link. GitMaster records which commit replaced each old one and moves the links with it.
• A rewrite made elsewhere, with another tool or in a terminal, reattaches a link only when exactly one commit in the rewritten range has the same patch as the old commit. GitMaster does not match commits by how alike their text looks.

A link that cannot be matched shows gone, with the subject, author and date that GitMaster saved when it made the link, so you still see what it pointed to. A commit is gone when no branch, tag or other reference reaches it any more. When two commits in the rewritten range have the same patch, the link shows ambiguous and GitMaster does not pick one.

Link threads#

Link one thread to another to record how their work connects. A link has one of three kinds:

Choose Link to Thread… in the ⋯ menu of a thread's header, or in its right-click menu, and pick the kind and the other thread. Each link is a row that shows who made it, you or an agent. GitMaster never infers a link from what two threads say.

Understand why code is the way it is#

Select lines in a text file on the Code page and choose Show Why This Code Is Here… from the viewer's right-click menu or the command palette. The panel beside the viewer shows the result.

Ask GitMaster why a file, or a range of lines in it, is the way it is. GitMaster works back from the code to the agent sessions that wrote it:

1. It finds the commits that last changed each line.
2. It finds the threads linked to those commits, and in each thread the edits that match the code.
3. It shows the prompts and replies around each matching edit, and the labels and linked threads of that thread.

Every result states the evidence that ties it to the code. The strongest evidence comes first:

Other rules:

• If several edits match the same lines, GitMaster lists all of them and marks the result ambiguous. It does not pick one.
• An edit that GitMaster cannot compare shows as unverifiable, not as "no match". That covers an edit whose text was redacted, an edit cut at the size limit, and an edit known only from the agent's input (From tool input).
• A formatter run after the edit changes the lines, so the match stops. Whitespace is compared exactly.
• The match is by content, not by commit id, so the result holds after a rebase, a squash or a reorder.
• A result shows at most 10 commits, 5 threads for each commit and 200 edits of the file for each commit. When a result is cut, it says so.
• Asking changes nothing in the repository or in any thread.

Labels#

A label is a name for things that belong together, such as auth-refactor or needs-review. A label belongs to the repository. It has a name, an optional description and an optional color, and it shows as a chip wherever it is attached.

You can attach a label to:

• a thread, with Tags… in the ⋯ menu of the thread's header. Enter the names separated by commas, such as bug, auth;
• a file, which keeps the label when the file is renamed;
• a commit, which keeps the label through a rewrite as a commit link does (see After a rewrite);
• another label.

Open the Labels entry in the sidebar to see every label. Choose one to list everything attached to it: threads, files, commits and other labels. Use Rename Label… and Delete in a label's menu. Deleting a label removes its attachments too.

You create labels, attach them and remove attachments. Only you can rename or delete a label. An agent connected through MCP can create a label and attach it; the label and each attachment it made show the agent's name, and you can remove them.

Keep and clean up#

These actions are in the ⋯ menu of the thread header, in the thread's right-click menu in the list, or in the command palette. The header's Copy as Markdown and star are buttons beside the title.

A delete is final. GitMaster overwrites the deleted text in the database file, and it does not keep a copy. It does not touch the agent's own session files; see What is not removed.

Only you can delete a thread or an entry, and rename or delete a label. An agent connected through MCP can read threads, and it can create labels and attach labels and links. Each row an agent makes shows the agent's name, and you can remove it.

Secrets#

Agents read files and run commands that can print passwords and keys, and the session carries them. GitMaster removes secrets before anything is saved: the database, the search index and the temporary files never hold the original text.

A matched secret is replaced with [REDACTED:name], where name is the pattern that matched, for example [REDACTED:github-token]. The thread keeps a count of redactions per pattern, never the values.

What is redacted#

GitMaster ships patterns for private key blocks, cloud and API keys and tokens from common services, JSON web tokens, Authorization headers, passwords in URLs, and values assigned to names such as password, secret, token and api_key. It also replaces the content of any file whose path matches a sensitive path, such as .env, *.pem and id_rsa*, while keeping the path.

Add your own patterns#

Add patterns for secrets that are specific to you, such as an internal token format or a private host name, in Threads Settings… from the command palette, or with the Settings… button on the Threads page. You can also set them in Git's configuration, in ~/.gitconfig for every repository or in one repository's .git/config. See Configuration for the keys.

[gitmaster-redact "acme-token"]
	regex = acme_[A-Za-z0-9]{32}
[gitmaster "threads"]
	redactPath = .env
	redactPath = .env.*
	redactPath = *.pem
	redactPath = secrets/**

A pattern is a regular expression. Use the test field in Threads Settings…, or gitmaster thread redact-test, to try a pattern on sample text before you rely on it. The command reads the sample from standard input, or from --text:

echo 'token ghp_abcdefghijklmnopqrstuvwxyz0123456789' | gitmaster thread redact-test

token [REDACTED:github-token]
redacted: github-token x1

The second line goes to standard error. It names each pattern that matched and how many times.

A pattern that is not a valid regular expression pauses capture in every repository until you fix or remove it. Events that arrive while it is paused are not stored. The Threads page says how many were skipped and which pattern is at fault. GitMaster stops capturing rather than risk storing a secret.

Apply a new pattern to old threads#

A pattern you add applies to what is captured from then on. To apply it to threads you already have, run Scrub Threads… from the command palette. GitMaster runs the current patterns over every stored thread and tells you how many entries changed. Scrub can only remove more text, never restore any.

Export and Copy as Markdown do not apply the patterns again. They write the stored text as it is, so a thread you export has the same redactions as the thread in GitMaster. To make an export follow a new pattern, run Scrub Threads… first.

What is not removed#

• Redaction cannot reach the agent's own session files. The agent keeps its original text there, and GitMaster only reads them.
• A pattern catches what it describes. A secret written as ordinary words is not caught. Add a pattern, or delete the thread.
• Redaction cannot be undone. GitMaster does not keep the original.

Pause or stop capturing#

• Turn off Capture Threads in Threads Settings… to stop capturing everywhere. Threads already stored stay.

• Remove the plugin to stop the agent from reporting at all. See Agent integration.

Where threads are stored#

Threads are stored in .git/gitmaster/threads.db, in the Git common directory of the repository. The file is readable only by you. Nothing is written to the working tree, so no .gitignore entry is needed. Deleting the repository deletes its threads. See Configuration.

Search from an agent#

Once the MCP server is on, an agent searches the same threads with the same words as the search box. It can also list threads without a query, for example every thread that edited a path in the last week. The agent filters by role, turn range, thread, agent, model, branch, commit, path, label, star, edits and time. Each thread appears once with its best entry unless the agent asks for every match, and the results come in pages. An agent that finds no hit is told which filter removed the most hits.

The agent reads the text of a thread marked as untrusted, because it came from earlier prompts and tool output. See MCP tools for every argument.

Label from an agent#

An agent can mark a thread for you. It creates a label with label_create, attaches the label to a thread, a file, a commit or another label with label_attach, and links one thread to another with thread_link. Each of these records the agent's name as its origin, so you can tell what an agent wrote:

• A label name is created once. Creating a name that exists returns that label as it is, and does not change its description or color.
• Attaching the same thing twice changes nothing. The attachment keeps the origin that made it, so a label you attached yourself stays yours.
• A label an agent creates is listed by labels_list, and threads_search finds the threads it is attached to with its label filter.
• A link says that a thread continues, relates to or supersedes another, with the kinds described under Link threads.

An agent cannot rename or delete a label, detach one, remove a link, or delete a thread or an entry. The record tools are listed in MCP tools.

Summary#

A thread can carry a short summary of what you asked for and what came out of it. An agent writes it when you run /gitmaster:summarize-thread in your agent session; GitMaster does not write it. The summary shows under the title, marked Agent-written, and you can edit or delete it. See Agent integration.

See also#

• Agent integration: install the capture hooks.
• Memories: keep decisions and rules for later sessions.
• Reviewers and gates: have an agent review a branch and record what it found.
• Trust and safety: what GitMaster records and where.
• Configuration: the threads settings and the database file.