Thread context¶
codenib threads gives a coding agent what it needs from a GitHub issue or
pull request in one read: the ask, what people decided, review comments, the
failing checks, the threads it is linked to, and the code those threads point
at. It fits the result into a token budget, and when the agent comes back to
the thread later it returns only what changed. It runs on your machine and
calls no model.
An agent that reads a thread itself spends a tool call on each piece: the issue, its comments, the linked pull request, the reviews, the checks, a log. Every call carries the whole conversation so far, so the cost is the number of calls, not the size of the thread. Putting one prepared context in front of the agent removes most of those calls.
Preview
Thread context is a preview. It reads GitHub only, and its code locations come from names, paths and diffs in the thread, not from the code graph.
What the agent receives¶
One Markdown document, built by code alone:
- Status. Open, closed or merged, labels, and the checks of the latest commit. These are computed from GitHub's own events.
- Coverage. One line that says whether everything people wrote is included in full, or how many posts were shortened or left out. An agent can then tell whether it still has to read the thread. The thread's own posts are kept whole before anything from linked threads.
- What a pull request changes. Its files and size, so nobody asks for the diff to find out.
- The ask. The title and body of the issue or pull request.
- Code locations. Paths, stack frames, review positions and symbol names from the thread, resolved to files, symbols and line ranges at a commit, with the source of the symbols that matter most.
- Failing CI. How many checks fail and pass, then the lines around each error. Jobs that fail the same way appear once.
- Also in progress on this code. Open pull requests, outside this thread, that change the same symbols or source files. An agent working one thread cannot otherwise see that someone else is changing the same function.
- Linked threads. Each linked issue or pull request with its state, what it changed and how it was reviewed, followed by what people wrote there.
- Discussion and review comments, each review comment with the lines it was made on, newest kept first when the budget is tight.
Bot comments, quoted replies and passing checks are left out, and a paragraph
that one thread repeats from another appears once. Every part carries the id of
the event it came from, such as #812/comment/2990023933.
Use it¶
Thread context needs CodeNib, Git, and a GitHub token in GH_TOKEN, or an
installed and signed-in gh. Run it inside a clone of the repository:
codenib threads show 812 # print the context of issue or PR 812
codenib threads show 812 --budget 1500 # a tighter budget
codenib threads context 812 # write THREAD_CONTEXT.md for an agent
The first call fetches the thread and the threads it links to. Pass --sync
to fetch again.
Before an agent starts¶
Run codenib threads context from whatever starts your agent, and point the
agent at the file. This does not depend on the agent choosing to call a tool:
Work many threads at once¶
A ticket is one piece of work that starts from an issue or pull request. It follows that thread and the threads linked to it, and it remembers what it has already read, so nobody has to keep a cursor.
codenib threads open 812 --dir ../work/812 # start: writes THREAD_CONTEXT.md there
codenib threads poll # fetch what changed, for all tickets
codenib threads inbox 812 # what ticket 812 has not read yet
codenib threads board # all tickets at a glance
codenib threads close 812
- One inbox per ticket.
inboxreturns what any followed thread gained since the ticket last read, and marks it read. A thread that became linked since then, such as a new pull request for the issue, joins the ticket. - One thread, many tickets. When two tickets follow the same thread, it is fetched and stored once, and each ticket reads it from its own position.
- A poll costs what changed.
pollasks GitHub once which threads changed and fetches only those some ticket follows. With 24 tickets following 71 threads ofastral-sh/ruff, fetching everything took 278 requests, and a poll with nothing new took 13. - The board lists each ticket with its unread count, the other tickets whose threads name the same symbol, and open pull requests that change those symbols.
A comment edited after a ticket read it comes back in the inbox with its new text.
See who else is changing the same code¶
Index the open pull requests of the repository, and each context then names the ones that change the same code:
Run it again to refresh. In astral-sh/ruff, 30 of the 59 most recently
updated open pull requests changed a symbol that another of them also changed
(November 2026).
When an agent comes back¶
Each context ends with a cursor, the id of the newest event it saw. Pass it back to get only what happened since: new comments and reviews, a status change, new check results.
From an agent, over MCP¶
codenib threads mcp serves the same context to any agent that speaks the
Model Context Protocol. It is a separate server from CodeNib's code search, so
adding it does not change which code tools the agent sees.
| Tool | Returns |
|---|---|
thread_context |
The context of one thread, or what followed a cursor |
ticket_open |
The first context of a ticket; remembers what was read |
ticket_inbox |
What the ticket's threads gained since it last read |
tickets_board |
All tickets, unread counts and shared code |
thread_events |
Raw events by id, including a failed check's log |
Writing the context into a file before the agent starts does not depend on the agent choosing to call a tool, so prefer it for the first context and use the tools for what comes later.
From Python¶
from pathlib import Path
from codenib.threads import ThreadStore, TicketBook, open_ticket, read_inbox
book = TicketBook(ThreadStore("acme/widget"))
ticket, context = open_ticket(book, 812, checkout=Path("."))
news = read_inbox(book, ticket) # None when nothing is new
show, open, inbox and board also print JSON with --json.
Check a citation¶
How well it works¶
With two coding agents, the prepared context cut the input tokens of a task
by a fifth to a half against letting the agent read threads with gh, and
the agents found the files to change about as often. With Codex the result is
the same. With Claude Code the gap is too small to tell from chance at this
sample size.
The agent was asked which files and symbols have to change, and its answer was
compared with what the merged pull request changed. Three ways of getting
thread context were compared: the agent reads threads itself with gh; every
thread event is pasted into the prompt unprocessed; or the prompt carries the
codenib threads context. Codex ran gpt-6.1-sol and Claude Code ran Claude
Opus 5.5, both at medium effort.
| Agent and task | Tasks | Files found: gh / pasted / CodeNib |
Input tokens against gh |
Against pasted |
|---|---|---|---|---|
| Codex, take over a pull request after review or a failed check | 76 | 0.74 / 0.75 / 0.75 | −21% | −32% |
| Codex, the same, threads over 20,000 tokens | 22 | 0.63 / 0.65 / 0.63 | −34% | −52% |
| Codex, take over an issue before any fix exists | 47 | 0.82 / 0.85 / 0.85 | −25% | +2% |
| Claude Code, take over a pull request | 76 | 0.83 / 0.78 / 0.80 | −45% | −69% |
| Claude Code, the same, threads over 20,000 tokens | 22 | 0.70 / 0.60 / 0.61 | −63% | −84% |
What to take from this:
- It saves tokens, more so on long threads. On short threads, pasting everything costs as little.
- Answers hold. With Codex the files found are the same.
- With Claude Code the answers are close, 0.80 against 0.83. An agent that reads the threads itself explores more code. The same happens when the whole thread is pasted (0.78), so it comes from handing context over, not from what the prepared context leaves out. If finding every file matters more to you than cost, let the agent read for itself.
For Claude Code the reported cost of the 76 tasks was $8.37 with the prepared
context, $11.34 reading with gh, and $17.49 with everything pasted.
For an agent that returns to a thread, a first context followed by updates took a median of 2,897 tokens over the life of an issue, against 21,103 for reading the whole thread each time (151 issues, a median of 6 returns each).
Scope and method
- Repositories:
astral-sh/ruff,caddyserver/caddyandpydantic/pydanticfor pull requests; the first two for issues. - Each task shows the thread as it stood at a cut-off, and a snapshot of
the repository at that point with no history, so no arm can read the fix.
A read-only replica of
ghlimited to the cut-off is available in every arm. Both agents ran with no network access. - Codex (gpt-6.1-sol, medium effort): its
ghand pasted arms ran once per task and the CodeNib arm twice; the two runs differed by 6% in total input tokens on pull requests and 1% on issues. Claude Code (Claude Opus 5.5, medium effort): every arm ran once. - Intervals are 95% paired bootstrap over tasks. Codex pull requests: −27%
to −14% against
gh, −40% to −23% against pasted. Codex issues: −31% to −19% and −4% to +9%. Claude Code: −57% to −30% and −78% to −59%; files found −0.03 againstgh(−0.07 to +0.02). - The Codex figures predate one line the context now ends with, which tells the agent that it covers the threads and not the code. With Claude Code that line moved files found from 0.79 to 0.80.
- Pasted context keeps the last 200 lines of each failed job log and stops at 60,000 tokens.
- In the pull request tasks no arm could see the pull request's own diff as of the cut-off.
- The answer does not show that an agent then writes a better fix. It shows where the agent would work, and what reaching that cost.
- Reproduce with
scripts/benchmark_threads_context.py;--agentselects Codex or Claude Code.
Reference¶
| Command | Does |
|---|---|
codenib threads sync N... |
Fetch threads and the threads they link to |
codenib threads sync --open-pulls [N] |
Index what open pull requests change |
codenib threads show N |
Print the context |
codenib threads context N |
Write the context to a file |
codenib threads open N |
Start a ticket and write its first context |
codenib threads inbox N |
Print what a ticket has not read; --peek leaves it unread |
codenib threads poll |
Fetch what changed on the threads tickets follow |
codenib threads board |
List tickets, unread counts and shared code |
codenib threads close N |
Stop following a ticket's threads |
codenib threads mcp |
Serve context and tickets over MCP |
codenib threads events ID... |
Print raw events by id |
| Option | Meaning | Default |
|---|---|---|
--budget |
Target size in tokens, source excluded. A thread's own posts stay whole up to three times this before they are shortened; linked threads are cut first | 3000 |
--code-budget |
Extra tokens for the source of referenced symbols | 1500 |
--since ID |
Return only what followed this event | |
--rev |
Commit that code locations are resolved against | HEAD |
--at TIME |
Serve the thread as it was at an ISO time | |
--sync |
Fetch from GitHub before serving | |
--offline |
Never call GitHub | |
--no-anchors |
Skip code locations | |
--repo |
owner/name |
the origin remote |
--checkout |
Clone used to resolve code locations | . |
--store |
Where thread logs are kept | CodeNib home |
--api-url |
GitHub REST API root, for GitHub Enterprise; pass --repo too |
$GITHUB_API_URL, else github.com |
Thread logs are stored as files under ~/.codenib/threads/<owner>/<repo>/.
Nothing is written into your checkout. A log is append-only: syncing twice
changes nothing, and an edited comment is kept beside the original.
Thread text is treated as data. CodeNib executes and follows nothing in a comment, and only reads from GitHub. The text still reaches your agent, as it would if the agent read the thread itself, so anyone who can comment on a thread can address your agent. Give the agent no more permissions than you would when it reads GitHub directly.