flagon-io/g1t

public

Docs: inbox threads, reasons, subscriptions, watching, email, API and MCP

The inbox guide covers threads, every reason, who is told of what, subscriptions, watching, email and the settings page; the MCP reference has the notifications tool, authentication the new scopes, and the API overview, llms.txt and PLAN.md say what is built and what is still to come.

syntaqxcommitted 3d agoParent24841cbBrowse files

323	323		\| Workflows \| `workflows:read`, `workflows:write` \|
324	324		\| Memory & search \| `memory:read`, `memory:write` \|
325	325		\| Account \| `account:read`, `account:write` \|
	326	+	\| Notifications \| `notifications:read`, `notifications:write` \|
326	327		\| Workspace \| `workspace:read`, `access:read`, `webhooks:read`, `secrets:read` \|
327	328		\| Runners \| `runners:read` \|
328	329		\| Dangerous \| `repo:admin`, `packages:delete`, `workspace:admin`, `access:admin`, `webhooks:admin`, `secrets:admin`, `runners:admin` \|
⋯
352	353		\| `memory:write` \| Save memory for the next agent \|
353	354		\| `account:read` \| Read your email addresses, invites and invitations \|
354	355		\| `account:write` \| Change your email addresses, make invites and answer invitations \|
	356	+	\| `notifications:read` \| See your [inbox](/guides/inbox/), its threads, and what you subscribe to and watch \|
	357	+	\| `notifications:write` \| Mark notifications read, done, saved or snoozed, subscribe to threads and watch repositories \|
355	358		\| `workspace:read` \| Read workspace invites, integrations and model routes \|
356	359		\| `workspace:admin` \| Create and delete workspaces, invite members, connect integrations \|
357	360		\| `access:read` \| See who has access to repositories \|
⋯
398	401		\| Preset \| Scopes \|
399	402		\| --- \| --- \|
400	403		\| Read only \| Every `read` scope. Changes nothing. \|
401		−	\| Agent \| Every `read` scope except `runners:read`, and `code:write`, `issues:write`, `pull_requests:write`, `agents:run` and `memory:write`. Reads everything, works on issues and pull requests, pushes code and puts g1t to work. No admin scope. \|
	404	+	\| Agent \| Every `read` scope except `runners:read`, and `code:write`, `issues:write`, `pull_requests:write`, `agents:run`, `memory:write` and `notifications:write`. Reads everything, works on issues and pull requests, pushes code, puts g1t to work, and answers your inbox. No admin scope. \|
402	405		\| CI \| `repo:read`, `code:read`, `code:write`, `packages:read`, `packages:write`, `workflows:read` and `workflows:write`. Clones and pushes code, pushes and pulls packages, and runs workflows. \|
403	406		\| Full access \| Everything you can do, including deleting repositories and changing who has access. Marked Dangerous. \|
404	407
⋯
474	477
475	478		An application that asks for no scopes in particular gets the
476	479		[Agent preset](#presets): every `read` scope except `runners:read`, and `code:write`,
477		−	`issues:write`, `pull_requests:write`, `agents:run` and `memory:write`.
	480	+	`issues:write`, `pull_requests:write`, `agents:run`, `memory:write` and
	481	+	`notifications:write`.
478	482		It never gets an admin scope unless it asks for one and you leave it
479	483		ticked.
480	484

1	1		---
2	2		title: Your inbox
3		−	description: What needs you, and what you follow, as it happens. An agent waiting on you comes first; failures, merges, mentions and comments follow. Mark items read or done, save them, or snooze them.
	3	+	description: What needs you, and what you follow, as it happens. One thread per issue, pull request, workflow or deployment, with why you were told. Choose what you hear of with subscriptions, watching and email settings.
4	4		---
5	5
6	6		Your inbox tells you when something needs you, or when something
7		−	happens to work you answer for: an agent is waiting on you, checks failed
8		−	on your pull request, g1t finished a change you asked for, someone mentioned
9		−	you. You are never told about what you did yourself.
	7	+	happens to work you answer for or follow: an agent is waiting on you,
	8	+	someone asked you to review a pull request, checks failed on your pull
	9	+	request, a deployment failed, someone mentioned you. You are never told
	10	+	about what you did yourself.
10	11
11	12		Open it from the bell in the top bar. The number on the bell is what is
12		−	unread. It is amber while an agent is waiting on you, red while a failure is
13		−	unread, and green otherwise.
	13	+	unread. It is amber while something is waiting on you, red while a failure
	14	+	is unread, and green otherwise.
	15	+
	16	+	## Threads
	17	+
	18	+	Your inbox holds one thread for each thing you were told about:
	19	+
	20	+	- an issue
	21	+	- a pull request
	22	+	- a workflow on one branch
	23	+	- a deployment: a project's production, or one pull request's preview
	24	+
	25	+	When something new happens on a thread, it comes back to the top of your
	26	+	inbox, unread, even if you had marked it done. It is not added a second
	27	+	time. A thread that is snoozed stays snoozed until its time.
	28	+
	29	+	Each card shows the latest activity's title, why you were told (see
	30	+	[reasons](#reasons)), and, when more than one thing has happened, how many,
	31	+	such as 3 updates. g1t keeps the last 10 activities of each thread.
	32	+
	33	+	While a thread is unread it keeps the most urgent of what happened since
	34	+	you last read it. A failure followed by a comment still shows as a failure
	35	+	until you read it.
	36	+
	37	+	## Reasons
	38	+
	39	+	Every thread says why you were told of its latest activity. When you are
	40	+	told of one thing for more than one reason, the first that applies in this
	41	+	table is shown.
	42	+
	43	+	\| Reason \| Shown as \| Why you were told \|
	44	+	\| --- \| --- \| --- \|
	45	+	\| `agent` \| agent waiting \| An agent is waiting on you: it asked a question, or it stopped until a person steps in. \|
	46	+	\| `review_requested` \| review requested \| Someone asked you to review a pull request, or you are one of its reviewers. \|
	47	+	\| `assign` \| assigned \| You were assigned, or you are an assignee. \|
	48	+	\| `mention` \| mentioned \| Someone mentioned you with `@username`, or you were mentioned on it before. \|
	49	+	\| `ci_activity` \| CI activity \| A check, workflow or deployment on your work finished badly, or recovered. \|
	50	+	\| `security_alert` \| security alert \| A security alert on a repository you look after. g1t does not send these to the inbox yet. \|
	51	+	\| `state_change` \| state changed \| It was closed, reopened or merged. \|
	52	+	\| `author` \| your work \| You opened it, or you asked g1t for it. \|
	53	+	\| `comment` \| commented \| You commented on it. \|
	54	+	\| `manual` \| subscribed \| You subscribed to it yourself. \|
	55	+	\| `subscribed` \| watching \| You watch its repository. \|
14	56
15	57		## What lands there
16	58
17	59		Each item comes from something that happened on g1t. Who is told depends on
18	60		what it was:
19	61
20		−	\| What happened \| Who is told \| Shown as \|
21		−	\| --- \| --- \| --- \|
22		−	\| Another agent asked a question of the agent on a pull request, or handed it work \| The person the pull request belongs to, and the issue's author and assignees \| Needs you \|
23		−	\| Checks failed, or could not run, on a pull request \| The person the pull request belongs to \| Error \|
24		−	\| A workflow failed on a pull request \| The person the pull request belongs to \| Error \|
25		−	\| A workflow failed on a branch \| Whoever pushed the commit it ran on \| Error \|
26		−	\| g1t finished a change and marked it ready for review \| The person who asked g1t for it \| Success \|
27		−	\| g1t reviewed a pull request \| The person the pull request belongs to \| Success when approved, Info when it asks for changes \|
28		−	\| A pull request was merged \| The person the pull request belongs to \| Success \|
29		−	\| Someone mentioned you with `@username` in a comment \| You \| Info \|
30		−	\| Someone commented on an issue or pull request you opened \| You \| Info, or Success for an approval \|
	62	+	\| What happened \| Who is told \| Reason \| Shown as \|
	63	+	\| --- \| --- \| --- \| --- \|
	64	+	\| An agent asked a question of the agent on a pull request, or handed it work \| The person the pull request belongs to, and its issue's author and assignees \| `agent` \| Needs you \|
	65	+	\| g1t stopped on a pull request until a person steps in \| The same people \| `agent` \| Needs you \|
	66	+	\| Someone asked for reviews on a pull request, or opened one with reviewers \| The reviewers asked \| `review_requested` \| Needs you \|
	67	+	\| Someone assigned people to an issue or pull request, or opened one with assignees \| The people newly assigned \| `assign` \| Info \|
	68	+	\| Checks failed, or could not run, on a pull request \| The person the pull request belongs to \| `ci_activity` \| Error \|
	69	+	\| A workflow failed on a pull request \| The person the pull request belongs to \| `ci_activity` \| Error \|
	70	+	\| A workflow failed on a branch \| Whoever pushed the commit it ran on \| `ci_activity` \| Error \|
	71	+	\| A preview of a pull request failed to deploy \| The person the pull request belongs to, and people watching deployments \| `ci_activity`, or `subscribed` for watchers \| Error \|
	72	+	\| Production failed to deploy \| Whoever pushed or started it, and people watching deployments \| `ci_activity`, or `subscribed` for watchers \| Error \|
	73	+	\| A deployment went live \| People watching deployments; after a failure, also whoever was told of the failure \| `ci_activity`, or `subscribed` for watchers \| Success \|
	74	+	\| g1t finished a change and marked it ready for review \| The person who asked g1t for it \| `author` \| Success \|
	75	+	\| g1t reviewed a pull request \| The person the pull request belongs to \| `author` \| Success when approved, Info when it asks for changes \|
	76	+	\| A pull request was merged \| Everyone subscribed to it, and people watching pull requests \| `state_change`, or `subscribed` for watchers \| Success \|
	77	+	\| An issue or pull request was closed, or an issue was reopened \| Everyone subscribed to it, and people watching its kind \| `state_change`, or `subscribed` for watchers \| Info \|
	78	+	\| Someone mentioned you with `@username` in a comment \| You \| `mention` \| Info \|
	79	+	\| Someone commented on an issue or pull request \| Everyone subscribed to it, and people watching its kind \| Why each is subscribed, or `subscribed` for watchers \| Info, or Success for an approval \|
	80	+	\| An issue or pull request was opened \| People watching its kind \| `subscribed` \| Info \|
31	81
32	82		"The person a pull request belongs to" is its author, or, for a change g1t
33		−	made, the person who asked for it. g1t itself is never told. A mention in
34		−	code or in a quoted line does not count.
	83	+	made, the person who asked for it. An approval or a request for changes
	84	+	always reaches that person. g1t itself is never told. A mention in code or
	85	+	in a quoted line does not count.
	86	+
	87	+	Some threads close themselves once they no longer need you:
	88	+
	89	+	- When an agent was waiting on you, the thread moves to Done as soon as the
	90	+	agent picks back up: it resumes, its pull request changes, a merge is
	91	+	asked for, or the pull request is merged or closed.
	92	+	- When a review request to you is removed, that thread moves to Done.
	93	+
	94	+	New activity brings either back, as with any thread.
35	95
36	96		You only see items about repositories you can read. If you lose access to a
37	97		repository, its items leave your inbox the next time you open it.
38	98
	99	+	## Subscriptions
	100	+
	101	+	You are subscribed to an issue or pull request, and hear of what
	102	+	happens on it, without doing anything when you:
	103	+
	104	+	- opened it, or asked g1t for it
	105	+	- are assigned to it
	106	+	- are one of its reviewers
	107	+	- commented on it
	108	+	- were mentioned in it
	109	+
	110	+	You can also subscribe to any issue or pull request yourself, or
	111	+	unsubscribe from one.
	112	+
	113	+	\| You are \| You hear of \|
	114	+	\| --- \| --- \|
	115	+	\| Subscribed \| Everything in [What lands there](#what-lands-there) that goes to everyone subscribed: comments, closes, reopens and merges. \|
	116	+	\| Unsubscribed \| Only what is asked of you or is about your own work: an agent waiting on you, a review request, an assignment, a mention, and failed checks, workflows and deployments. Commenting on it, or being mentioned in it, subscribes you again. \|
	117	+	\| Ignoring it \| Nothing on it at all, not even a mention. Only you can undo this. \|
	118	+
	119	+	To subscribe to an issue or pull request, or unsubscribe:
	120	+
	121	+	1. Open the issue or pull request.
	122	+	2. In the sidebar, under Notifications, select Subscribe or
	123	+	Unsubscribe.
	124	+
	125	+	The line under the button says where you stand, such as "You're subscribed
	126	+	because you were assigned.", "You're not subscribed. You'll still hear if
	127	+	you're mentioned or asked to review." or "You ignore this thread."
	128	+
	129	+	To ignore an issue or pull request, use the API:
	130	+	`PUT /repos/{owner}/{name}/issues/{number}/subscription` with
	131	+	`"ignored": true`, or the `notifications` tool's `subscribe` action with
	132	+	`ignored`. See [from the API and agents](#from-the-api-and-agents). While
	133	+	you ignore one, its button reads Stop ignoring, which puts you back to
	134	+	the default: subscribed only while you take part.
	135	+
	136	+	## Watching a repository
	137	+
	138	+	How you watch a repository decides what you hear of on it beyond what
	139	+	you take part in.
	140	+
	141	+	\| Level \| You hear of \|
	142	+	\| --- \| --- \|
	143	+	\| Participating and @mentions \| Only what you take part in or are mentioned in. The default. \|
	144	+	\| All activity \| Also every issue and pull request opened, commented on, closed, reopened or merged, and every deployment. \|
	145	+	\| Ignore \| Nothing on the repository at all, not even a mention or a review request. \|
	146	+	\| Custom \| What you take part in, and the kinds you choose: Issues, Pull requests, Deployments and Security alerts. g1t does not send security alerts to the inbox yet. \|
	147	+
	148	+	To change how you watch a repository:
	149	+
	150	+	1. Open the repository.
	151	+	2. In the header, open the Watch menu.
	152	+	3. Select a level. For Custom, tick the kinds you want. Unticking
	153	+	every kind puts you back on Participating and @mentions.
	154	+
	155	+	A repository you create is watched the way you choose in
	156	+	[your settings](#settings): All activity unless you change it.
	157	+
	158	+	## Email
	159	+
	160	+	You can also be emailed when you are told of something. By default, g1t
	161	+	emails you for three reasons: agent waiting, review requested and
	162	+	mentioned. Each time you are told of something for a reason you chose,
	163	+	g1t sends one email with what happened and a link to it.
	164	+
	165	+	An email is sent only when:
	166	+
	167	+	- your account's email address is confirmed, and
	168	+	- you can still read the repository it is about.
	169	+
	170	+	The foot of each email says why you got it, and links to
	171	+	[g1t.sh/settings/notifications](https://g1t.sh/settings/notifications).
	172	+
	173	+	## Settings
	174	+
	175	+	Settings → Notifications, at
	176	+	[g1t.sh/settings/notifications](https://g1t.sh/settings/notifications),
	177	+	holds your choices:
	178	+
	179	+	\| Setting \| What it does \| Default \|
	180	+	\| --- \| --- \| --- \|
	181	+	\| Email \| One checkbox per reason: you are also emailed when you are told of something for it. \| agent waiting, review requested, mentioned \|
	182	+	\| Repositories you create \| How you watch a new repository you create: Participating and @mentions or All activity. \| All activity \|
	183	+	\| Watched repositories \| Every repository you watch other than the default way, with how. \| \|
	184	+
39	185		## Tabs
40	186
41	187		\| Tab \| Shows \|
42	188		\| --- \| --- \|
43		−	\| All \| Everything, with what an agent is waiting on first \|
44		−	\| Needs you \| What an agent is waiting on you for \|
45		−	\| Errors \| Failed checks and workflows \|
46		−	\| Success \| Merges, approvals and finished agent work \|
47		−	\| Info \| Mentions and comments \|
	189	+	\| All \| Everything, with what is waiting on you first \|
	190	+	\| Needs you \| What is waiting on you: an agent, or a review asked of you \|
	191	+	\| Errors \| Failed checks, workflows and deployments \|
	192	+	\| Success \| Merges, approvals, finished agent work, and deployments that went live \|
	193	+	\| Info \| Mentions, comments, assignments, and what you watch \|
48	194
49	195		The count beside each tab is what is unread under it.
50	196
⋯
58	204
59	205		\| Action \| What it does \|
60	206		\| --- \| --- \|
61		−	\| Done (✓) \| Moves the item out of the inbox and into Done \|
	207	+	\| Done (✓) \| Moves the thread out of the inbox and into Done, until something new happens on it \|
62	208		\| Mark as read / Mark as unread \| Changes whether it counts as unread \|
63	209		\| Save \| Keeps it under Saved, even after it is done \|
64	210		\| Snooze until \| Hides it for 3 hours, until tomorrow, or for a week, then brings it back \|
⋯
68	214		## The full inbox
69	215
70	216		Open inbox, at the foot of the panel, goes to
71		−	[g1t.sh/inbox](https://g1t.sh/inbox). It has the same tabs, every item a page
72		−	at a time, and two more views:
	217	+	[g1t.sh/inbox](https://g1t.sh/inbox). It has the same tabs, every thread a
	218	+	page at a time, and two more views:
73	219
74	220		\| View \| Shows \|
75	221		\| --- \| --- \|
76		−	\| Saved \| Items you saved, done or not \|
77		−	\| Done \| Items you marked done. Select ↶ on one to move it back \|
	222	+	\| Saved \| Threads you saved, done or not \|
	223	+	\| Done \| Threads you marked done. Select ↶ on one to move it back \|
	224	+
	225	+	Beside the tabs, the Reason filter shows only threads told for one
	226	+	reason: select Any reason or one of the [reasons](#reasons). It is kept
	227	+	in the address as `?reason=`, such as
	228	+	[g1t.sh/inbox?reason=review_requested](https://g1t.sh/inbox?reason=review_requested),
	229	+	so you can bookmark it.
	230	+
	231	+	Mission control shows a Needs you card with the newest unread threads
	232	+	waiting on you, then failures. It is hidden when there are none.
78	233
79		−	Mission control shows a Needs you card with the newest unread items an
80		−	agent is waiting on, then failures. It is hidden when there are none.
	234	+	## From the API and agents
81	235
	236	+	Everything here is also in the REST API and the MCP server, for a personal
	237	+	access token or an OAuth sign-in. A workspace's token cannot use it, and
	238	+	neither can g1t's own agents: they act as `g1t`, which has no inbox.
	239	+	Reading needs the `notifications:read` scope, and changing anything
	240	+	`notifications:write`; the Agent [preset](/guides/authentication/#presets)
	241	+	has both.
	242	+
	243	+	\| Route \| MCP action \| What it does \|
	244	+	\| --- \| --- \| --- \|
	245	+	\| [`GET /notifications`](/reference/api/notifications/list-notifications/) \| `list` \| Your unread threads, latest first. Filter by `reason`, `severity`, `participating`, `since` and `before`; `all` adds read ones; `view` lists `saved` or `done`. \|
	246	+	\| [`PUT /notifications`](/reference/api/notifications/mark-notifications-read/) \| `mark_all_read` \| Mark everything read up to `last_read_at`. \|
	247	+	\| [`GET /notifications/threads/{id}`](/reference/api/notifications/get-notification-thread/) \| `get` \| One thread, its last 10 activities, and your subscription. \|
	248	+	\| [`PATCH /notifications/threads/{id}`](/reference/api/notifications/mark-thread-read/) \| `mark_read` \| Mark a thread read, or unread. \|
	249	+	\| [`DELETE /notifications/threads/{id}`](/reference/api/notifications/mark-thread-done/) \| `done` \| Mark a thread done. \|
	250	+	\| [`PUT /notifications/threads/{id}/saved`](/reference/api/notifications/save-thread/) \| `save` \| Save a thread; `DELETE` unsaves it. \|
	251	+	\| [`PUT /notifications/threads/{id}/snooze`](/reference/api/notifications/snooze-thread/) \| `snooze` \| Snooze a thread until `until`; `DELETE` brings it back. \|
	252	+	\| [`PUT /repos/{owner}/{name}/issues/{number}/subscription`](/reference/api/notifications/set-issue-subscription/) \| `subscribe` \| Subscribe to an issue or pull request, unsubscribe, or ignore it. `GET` reads it and `DELETE` unsubscribes. The same works at `/notifications/threads/{id}/subscription`. \|
	253	+	\| [`PUT /repos/{owner}/{name}/subscription`](/reference/api/notifications/set-repo-subscription/) \| `watch` \| Watch a repository at a `level`. `GET` reads it and `DELETE` goes back to the default. \|
	254	+	\| [`GET /user/subscriptions`](/reference/api/notifications/list-watched-repos/) \| `watched` \| The repositories you watch other than the default way. \|
	255	+
	256	+	`GET /repos/{owner}/{name}/notifications` and
	257	+	`PUT /repos/{owner}/{name}/notifications` list and mark one repository's
	258	+	threads. Every action of the `notifications` tool is in
	259	+	[MCP tools](/reference/mcp/#notifications).
	260	+
	261	+	For example, to list the reviews waiting on you:
	262	+
	263	+	```sh
	264	+	curl "https://api.g1t.sh/notifications?reason=review_requested" \
	265	+	-H "Authorization: Bearer $G1T_TOKEN"
	266	+	```
	267	+
82	268		## How long items are kept
83	269
84		−	Items you mark done are removed after 30 days. Any item is removed after 180
85		−	days. Saved items are kept until you unsave them.
	270	+	Threads you mark done are removed 30 days after you mark them. Any other
	271	+	thread is removed once nothing has happened on it for 180 days. Saved
	272	+	threads are kept until you unsave them.

3	3		description: The g1t MCP server's resource tools, each action they take with its required inputs and scope, and how to call them.
4	4		---
5	5
6		−	The MCP server at `https://mcp.g1t.sh` exposes 13 tools, one per kind of
	6	+	The MCP server at `https://mcp.g1t.sh` exposes 14 tools, one per kind of
7	7		thing on g1t: `search`, `repository`, `issue`, `pull_request`, `agent`,
8		−	`plan`, `memory`, `workflow`, `secret`, `webhook`, `access`, `workspace`
9		−	and `account`. Each tool takes an `action` that says what to do. Every
	8	+	`plan`, `memory`, `workflow`, `secret`, `webhook`, `access`, `workspace`,
	9	+	`notifications` and `account`. Each tool takes an `action` that says what to do. Every
10	10		action is the same operation as a route of the [REST API](/reference/api/),
11	11		with the same inputs, permissions and results, so the two always agree.
12	12
⋯
51	51		}
52	52		```
53	53
54		−	- `action` is required, except on two tools that have a default:
55		−	`search` runs `code`, and `account` runs `whoami`, when it is left out.
	54	+	- `action` is required, except on three tools that have a default:
	55	+	`search` runs `code`, `notifications` runs `list`, and `account` runs
	56	+	`whoami`, when it is left out.
56	57		- The input schema that `tools/list` returns is one flat object: `action`,
57	58		then every field any of the tool's actions takes. The `action` field's
58	59		description lists each action with the fields it needs, such as
⋯
450	451		\| [`get_model_routes`](/reference/api/integrations/get-model-routes/) \| Which provider and model each kind of work goes to. Members only. \| `workspace` \| `workspace:read` \|
451	452		\| [`set_model_routes`](/reference/api/integrations/set-model-routes/) \| Replace them: each route has `task`, `connection_id` (null for g1t's models) and `model`. Owners only. \| `workspace`, `routes` \| `workspace:admin` \|
452	453
	454	+	## `notifications`
	455	+
	456	+	Your [inbox](/guides/inbox/): one thread per issue, pull request, workflow
	457	+	on a branch or deployment, with why you were told (`reason`), and what you
	458	+	subscribe to and watch. `list` is the default action. It is your own: a
	459	+	personal access token or an OAuth sign-in can use it, a workspace's token
	460	+	cannot. Name an issue or pull request by a thread's `id`, or by `repo` and
	461	+	`number`.
	462	+
	463	+	\| Action \| What it does \| Required \| Scope \|
	464	+	\| --- \| --- \| --- \| --- \|
	465	+	\| [`list`](/reference/api/notifications/list-notifications/) \| Your unread threads, latest first. With `all`, read ones too; `view` `saved` or `done` lists those instead. Filter by `reason`, `severity`, `participating`, `since`, `before` or `repo`. \| None \| `notifications:read` \|
	466	+	\| [`get`](/reference/api/notifications/get-notification-thread/) \| One thread, its last 10 activities, and your subscription to it. \| `id` \| `notifications:read` \|
	467	+	\| [`mark_read`](/reference/api/notifications/mark-thread-read/) \| Mark a thread read, or with `read` false, unread. \| `id` \| `notifications:write` \|
	468	+	\| [`mark_all_read`](/reference/api/notifications/mark-notifications-read/) \| Mark every thread read, or one repository's with `repo`. Threads with activity after `last_read_at` (now, when left out) stay unread. \| None \| `notifications:write` \|
	469	+	\| [`done`](/reference/api/notifications/mark-thread-done/) \| Move a thread to Done; new activity brings it back. With `done` false, move it back now. \| `id` \| `notifications:write` \|
	470	+	\| [`save`](/reference/api/notifications/save-thread/) \| Save a thread so it is kept, or with `saved` false, unsave it. \| `id` \| `notifications:write` \|
	471	+	\| [`snooze`](/reference/api/notifications/snooze-thread/) \| Hide a thread until `until` (RFC 3339). Leave `until` out to bring it back now. \| `id` \| `notifications:write` \|
	472	+	\| [`subscription`](/reference/api/notifications/get-thread-subscription/) \| Whether you are subscribed to an issue or pull request, or ignore it, and why. \| `id`, or `repo` and `number` \| `notifications:read` \|
	473	+	\| [`subscribe`](/reference/api/notifications/set-thread-subscription/) \| Subscribe (`subscribed`, true unless you say), unsubscribe (`subscribed` false), or ignore it (`ignored` true). \| `id`, or `repo` and `number` \| `notifications:write` \|
	474	+	\| [`unsubscribe`](/reference/api/notifications/delete-thread-subscription/) \| Unsubscribe until you comment or are mentioned. What is asked of you directly still reaches you. \| `id`, or `repo` and `number` \| `notifications:write` \|
	475	+	\| [`watching`](/reference/api/notifications/get-repo-subscription/) \| How you watch a repository: `participating`, `all`, `ignore` or `custom`, with `events`. \| `repo` \| `notifications:read` \|
	476	+	\| [`watch`](/reference/api/notifications/set-repo-subscription/) \| Watch a repository at a `level`, with `events` (`issues`, `pulls`, `deployments`, `security`) for `custom`. \| `repo` \| `notifications:write` \|
	477	+	\| [`unwatch`](/reference/api/notifications/delete-repo-subscription/) \| Go back to the default: only what you take part in or are mentioned in. \| `repo` \| `notifications:write` \|
	478	+	\| [`watched`](/reference/api/notifications/list-watched-repos/) \| The repositories you watch other than the default way. \| None \| `notifications:read` \|
	479	+
453	480		## `account`
454	481
455	482		Who the token acts as and its workspaces, your email addresses, your
⋯
489	516		\| Plan \| The same reading actions, and `issue` `create` and `search` `ticket`. \|
490	517		\| Catch up \| The reading actions only. \|
491	518
492		−	No agent's token can use the `workspace`, `access`, `secret` or `webhook`
493		−	tools, the controls of `workflow`, or `pull_request` `merge`, `agent`
	519	+	No agent's token can use the `workspace`, `access`, `secret`, `webhook` or
	520	+	`notifications` tools (g1t acts as `g1t`, which has no inbox), the controls of `workflow`, or `pull_request` `merge`, `agent`
494	521		`assign` and `delegate`, `plan` `create` and `apply`, `issue` `import`, or
495	522		any `repository` action that creates, changes, renames, archives,
496	523		transfers, deletes, restores or purges a repository, or dismisses or

267	267		Every one of these is also on the MCP server. Its tools are resources,
268	268		each with an `action`: `search`, `repository`, `issue`, `pull_request`,
269	269		`agent`, `plan`, `memory`, `workflow`, `secret`, `webhook`, `access`,
270		−	`workspace` and `account`. Call `tools/call` with the tool's name and
	270	+	`workspace`, `notifications` and `account`. Call `tools/call` with the tool's name and
271	271		`arguments` holding `action` and its inputs, such as
272	272		`{"name": "issue", "arguments": {"action": "get", "repo": "acme/web", "number": 12}}`.
273	273		The flow above is: `issue` `get`, `memory` `recall`, `pull_request`
⋯
276	276		`statuses` and `required_checks` on `pull_request` `get`, and
277	277		`repository` `check_names` for the names a branch can require. `agent` `delegate` and `agent` `assign` hand work
278	278		to g1t's agent; `plan` `create`, `get` and `apply` plan an outcome;
279		−	`memory` `remember` saves a fact. `search` runs `code` and `account` runs
280		−	`whoami` when `action` is left out. A call missing a required field says
	279	+	`memory` `remember` saves a fact. `notifications` reads and answers the
	280	+	inbox of the person a token acts for: `list` (unread threads, each with a
	281	+	`reason` such as `agent` or `review_requested`), `done`, `subscribe`,
	282	+	`watch` and more; g1t's own token cannot use it. `search` runs `code`,
	283	+	`notifications` runs `list` and `account` runs `whoami` when `action` is
	284	+	left out. A call missing a required field says
281	285		which, such as "issue.get needs number.". The earlier one-tool-per-operation
282	286		names (`get_issue`, `create_pull_request`, …) still answer for now but are
283	287		no longer listed. Every tool and action, with its required fields and
⋯
292	296
293	297		Every access token and OAuth sign-in has scopes, `resource:level`:
294	298		`repo`, `code`, `issues`, `pull_requests`, `workflows`, `memory`,
295		−	`account`, `access`, `webhooks`, `secrets`, `runners` (read, write or admin
	299	+	`account`, `notifications`, `access`, `webhooks`, `secrets`, `runners` (read, write or admin
296	300		as each has them), `agents:run`, `workspace:read` and `workspace:admin`. A higher
297	301		level includes the lower. A token may expire. It reaches every workspace
298	302		and repository its owner can (a workspace's token, that workspace only);
⋯
301	305		`{"error": {"code": "forbidden", "message": "This access token needs the issues:write scope to use create_issue.", "needed_scope": "issues:write"}}`.
302	306		Pushing needs `code:write`; cloning a private repository `code:read`. For
303	307		an agent, use the Agent preset (every read scope but `runners:read`, plus `code:write`,
304		−	`issues:write`, `pull_requests:write`, `agents:run`, `memory:write`).
	308	+	`issues:write`, `pull_requests:write`, `agents:run`, `memory:write`,
	309	+	`notifications:write`).
305	310		OAuth clients may send `scope`;
306	311		the person can untick any; asking for none gives the Agent preset. Tokens
307	312		from device sign-in (above) have full access. Guide:

1012	1012		and push. It is the delivery layer chat needs too (who is told what, read
1013	1013		state, push), so building it first makes channels cheap.
1014	1014
1015		−	Built: the events service keeps it (`services/events/src/inbox.rs`,
1016		−	migration `0005_inbox` on the `g1t-events` database), writing items as
1017		−	events arrive from the bus; work's `inbox_subject` says what each event
1018		−	names. Who is told: `agent.asked` (the pull request's owner and its issue's
1019		−	people, as needs you), failed `checks.completed` and `workflow.completed`
1020		−	(error), `review.completed`, `pull.ready` for g1t's changes and
1021		−	`pull.merged` (success), and `comment.created` (mentions, then the owner).
1022		−	Never the actor, never g1t. On the site: a bell in the top bar opening a
1023		−	sheet with tabs (All, Needs you, Errors, Success, Info), Done, Save, Snooze
1024		−	and Mark all read; `/inbox` with Saved and Done; a Needs you card on
1025		−	mission control. Ask AI sits beside the bell, disabled. Still to come:
1026		−	review requests and an agent stalling on a person (`stage = needs_you`),
1027		−	which publish no event yet; deploy results, which deployments does not
1028		−	publish; email digests and push; the REST and MCP surface.
	1015	+	Built: the events service keeps it (`services/events/src/inbox.rs` and
	1016	+	`subscriptions.rs`, migrations `0005_inbox` and `0006_inbox_threads` on the
	1017	+	`g1t-events` database), writing items as events arrive from the bus; work's
	1018	+	`inbox_subject` says what each event names. Each person has one thread
	1019	+	per issue, pull request, workflow on a branch or deployment: new activity
	1020	+	brings it back unread with a count and its last 10 activities, and while it
	1021	+	is unread its most urgent severity is kept. Each item has a reason
	1022	+	(`agent`, `review_requested`, `assign`, `mention`, `ci_activity`,
	1023	+	`security_alert`, `state_change`, `author`, `comment`, `manual`,
	1024	+	`subscribed`). Who is told: `agent.asked` and `pull.stalled` (needs you,
	1025	+	closed again by `pull.resumed` and the like), `pull.review_requested`
	1026	+	(needs you, closed by `pull.review_request_removed`),
	1027	+	`issue.assigned`/`pull.assigned`, failed checks and workflows,
	1028	+	`deployment.failed` and a recovering `deployment.succeeded`, g1t's reviews
	1029	+	and finished changes, closes, reopens and merges to everyone subscribed,
	1030	+	and comments to the people mentioned and everyone subscribed. Never the
	1031	+	actor, never g1t. Subscriptions: authors, assignees and reviewers are
	1032	+	subscribed without a row; commenting or being mentioned subscribes; anyone
	1033	+	can subscribe, unsubscribe (still told of what is asked of them) or ignore.
	1034	+	Watching a repository: participating (the default), all, ignore, or
	1035	+	custom (issues, pulls, deployments, security); whoever creates a repository
	1036	+	watches it at their default, all activity unless they change it.
	1037	+	Settings: which reasons are also emailed (agent, review_requested and
	1038	+	mention by default) and the default watch for new repositories; email goes
	1039	+	through identity's `notify_by_email`, to a confirmed address only while the
	1040	+	person can still read the repository. REST and MCP: 14 operations under
	1041	+	`/notifications`, `/repos/:owner/:name/subscription` and
	1042	+	`/user/subscriptions` (scopes `notifications:read` and
	1043	+	`notifications:write`, in the Agent preset), and the `notifications` MCP
	1044	+	tool; never usable by g1t's own tokens. On the site: a bell in the top bar
	1045	+	opening a sheet with tabs (All, Needs you, Errors, Success, Info), Done,
	1046	+	Save, Snooze and Mark all read; `/inbox` with Saved, Done and a reason
	1047	+	filter; reasons and update counts on each card; a Notifications box on
	1048	+	issue and pull request pages; a Watch menu in the repository header;
	1049	+	Settings → Notifications; a Needs you card on mission control. Ask AI sits
	1050	+	beside the bell, disabled. Still to come: security alerts (the security
	1051	+	service publishes no event yet), email digests and push, Ask AI, and
	1052	+	channels.
1029	1053
1030	1054		Channels (working name): workspace channels, direct messages and
1031	1055		threads, live.

176	176		\| [List repository events](/reference/api/repositories/list-events/) \| 50 \| `before`: the id of the last event you have \|
177	177		\| [List workflow runs](/reference/api/actions/list-workflow-runs/) \| `per_page`, at most 100 and 50 if not given \| None \|
178	178		\| [List webhook deliveries](/reference/api/webhooks/list-webhook-deliveries/) \| 50 \| None \|
	179	+	\| [List notifications](/reference/api/notifications/list-notifications/) \| `per_page`, at most 100 and 30 if not given \| `cursor`: the `next` of the page before \|
179	180		\| [Read a session](/reference/api/sessions/read-session/) \| None \| `after`: the last `seq` you have \|
180	181		\| [Get a job's log](/reference/api/actions/get-job-logs/) \| 500 chunks \| `after`: the last `seq` you have \|
181	182
⋯
195	196		\| --- \| --- \|
196	197		\| [Accounts](/reference/api/accounts/whoami/) \| Signing in from a tool, and who a token acts as. \|
197	198		\| [Workspaces](/reference/api/workspaces/create-workspace/) \| Creating a workspace. \|
	199	+	\| [Notifications](/reference/api/notifications/list-notifications/) \| Your inbox: its threads, why you were told of each, marking them read, done, saved or snoozed, and what you subscribe to and watch. See [your inbox](/guides/inbox/). \|
198	200		\| [Invites](/reference/api/invites/list-invites/) \| Your invites while g1t is invite-only, and inviting people into a workspace by email. \|
199	201		\| [Repositories](/reference/api/repositories/list-repos/) \| A repository, how it handles pull requests, and its timeline. \|
200	202		\| [Access](/reference/api/access/list-collaborators/) \| Who has which role on a repository, invitations, outside collaborators, and a workspace's base permission. \|

45	45
46	46		\| Choose \| For an agent \|
47	47		\| --- \| --- \|
48		−	\| Scopes \| The Agent preset: every `read` scope except `runners:read`, and `code:write`, `issues:write`, `pull_requests:write`, `agents:run` and `memory:write`. Untick `agents:run` if it should not start g1t's agents, which spends the workspace's money. \|
	48	+	\| Scopes \| The Agent preset: every `read` scope except `runners:read`, and `code:write`, `issues:write`, `pull_requests:write`, `agents:run`, `memory:write` and `notifications:write`. Untick `agents:run` if it should not start g1t's agents, which spends the workspace's money. \|
49	49		\| Expires \| The shortest that fits the work, such as 30 days. \|
50	50
51	51		A token reaches every workspace and repository you can. To keep an agent