Docs

Threads

This page tells you how Pensieve makes a thread for each goal, how it sets the state, and how you share a thread.

What a thread holds

Every thread has the same core: the problem, the goal, the state and what is next. It also holds the question that waits on you. The rest of the thread is its resources, the evidence behind the core:

The folders where the work is: the repo, the branch, the worktree, uncommitted files, and how far the branch is ahead or behind.
The PRs, with their state, CI checks and review.
The tickets, with their status and assignee.
The agent sessions, and the command that resumes the last one.
When you ask, coworkers' recent commits in the same folders, and related tickets and threads.

A short note says what is done and what is left. Your agent writes the note when it does Pensieve's pending work. Until then, the thread has its evidence but no note.

How Pensieve joins a thread

Pensieve joins sessions, branches, commits and connection items into one thread by these links:

A ticket key such as ABC-123 in a branch name, a commit subject, a session or a ticket.
The git branch that a session ran on. This applies only to feature branches. A default branch holds many threads.
For work with no ticket: sessions in the same repo, at most 3 days apart, that edited the same files.
Session titles that mostly match, within 3 days.

Pensieve leaves out sessions in temporary folders and under ~/Library. Apps and scripts start those.

The five states

Pensieve sets each state from the thread's evidence. Material work is edits, commits, a branch or a PR.

State	Meaning	Set automatically when
To do	A ticket that you did not start.	A ticket that is not done, or with an unknown status, and no edits, commits, branch or PR.
Open	You work on it now.	A session runs now. Or the thread has material work and activity in the last 3 days, and it is not done.
Loose ends	It is not done and it is quiet. Go back to it.	It has material work that is not done, with no activity in the last 3 days.
Complete	Done.	A PR is merged, nothing happened after the merge, and no PR is open. Or its own PR is merged and no PR is open. Or its PRs are merged or closed, or its ticket is done, or its work is in the default branch, and nothing is uncommitted. Its work is in the default branch when its branch is merged or squash-merged, or when its commits are there and its note says that nothing is left.
Forgotten	Not finished, and it will probably stay that way.	Material work that is not done, quiet for 21 days, with no open PR and no uncommitted work. Or a conversation with no ticket and no edits, after its session ended.

You can set a state on the thread. An agent closes a thread in git, GitHub or the tracker, and Pensieve sees the evidence. It does not set the state. A state set by hand stays until the thread has new activity. Then the automatic state applies again. Pensieve keeps each change by hand, so a thread has a history of its states.

Saved versions

A thread follows one goal over time. Pensieve saves a version of a thread when it changes, for example when a PR opens, a commit lands or the next step changes. The version chip on a thread opens its saved versions. “New session from thread” starts an agent that reads the thread first. Agents get the same data from thread with version.

The Share button on a thread opens a preview. Pensieve reads the local resources whole and writes a summary of each one. Then you can do these steps:

Write what you need from the reader.
Edit the core and the summaries.
Clear the resources that do not belong.
Save the thread as one HTML page in Downloads.

The page has no outside files. A person opens it in a browser. The page also holds the thread as JSON in a <script type="application/json" id="pensieve-thread"> element, so the reader's agent reads the same file. Agents share a thread with the share_thread MCP tool. Pensieve does not send the file. You or your agent attach it to a message.

What a shared thread keeps

Each resource has a reach: who can open it. The reach sets what a shared thread does with the resource.

Reach	Resources	In a shared thread
local	Session transcripts, agent memory files, uncommitted or unpushed changes, files outside git, folders	A summary, written from the whole document when you share. No path.
git	The branch on the remote, files at a pushed commit, PRs	A link (a permalink at the commit)
mcp	Tickets, messages and pages from your connections	A link and its service, with a summary. A message goes as a link only, without its text.
restricted	Claude artifacts	A link marked “may need access”, with a summary
public	Public web pages	A link
private	Direct messages, group messages, private channels	Nothing: no link, no text, no summary

A shared thread has no local paths, session ids, resume command or secrets. Pensieve replaces text that looks like a key or a token with [secret]. It also removes sentences about your own computer from the core.

Threads from the command line

pensieve thread <thread id> -o thread.html    # the thread as one HTML page
pensieve thread <thread id> --json            # the thread as JSON
pensieve thread <thread id> --share -o thread.html   # the thread to send

A thread follows the pensieve-thread/2 JSON schema. Pensieve also reads files in the older context-card/1 format. The threads MCP tool gives the thread ids.

Threads for your agents

Agents get the same threads over MCP. threads lists the threads that are not done, the closest to done first, with their steps left. thread gives one thread. At the start of a session and at natural pauses, the agent offers to close the thread closest to done (the pensieve-wrap-up skill). With the Claude Code prompt hook, a prompt such as “where did I leave off on ABC-12” gets the thread before the agent starts.

Something wrong or missing? Tell us on GitHub.