Skip to content
Sign in

flagon-io/g1t

public
0

Commit

Docs: the inbox, what lands in it and why, its tabs and actions

PLAN.md says what is built of the inbox and what is still to come.

syntaqxcommitted Parent56961f7Browse files
4 files+103−10/4 viewed
+1−0
6464 items: [
6565 { label: 'Quickstart', slug: 'quickstart' },
6666 { label: 'How g1t works', slug: 'concepts/overview' },
67+ { label: 'Your inbox', slug: 'guides/inbox' },
6768 { label: 'Search and Explore', slug: 'guides/search' },
6869 { label: 'Status and incidents', slug: 'guides/status' },
6970 ],
+85−0
1+---
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.
4+---
5+
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.
10+
11+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.
14+
15+## What lands there
16+
17+Each item comes from something that happened on g1t. Who is told depends on
18+what it was:
19+
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 |
31+
32+"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.
35+
36+You only see items about repositories you can read. If you lose access to a
37+repository, its items leave your inbox the next time you open it.
38+
39+## Tabs
40+
41+| Tab | Shows |
42+| --- | --- |
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 |
48+
49+The count beside each tab is what is unread under it.
50+
51+## Work through it
52+
53+1. Select the bell in the top bar. The inbox opens beside the page.
54+2. Select an item to open what it is about. It is marked read, and the inbox
55+ closes.
56+3. Point at an item (on a phone, the buttons are always there) to act on it
57+ without opening it:
58+
59+| Action | What it does |
60+| --- | --- |
61+| **Done** (✓) | Moves the item out of the inbox and into Done |
62+| **Mark as read** / **Mark as unread** | Changes whether it counts as unread |
63+| **Save** | Keeps it under Saved, even after it is done |
64+| **Snooze until** | Hides it for 3 hours, until tomorrow, or for a week, then brings it back |
65+
66+**Mark all read** marks everything under the tab you are on as read.
67+
68+## The full inbox
69+
70+**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:
73+
74+| View | Shows |
75+| --- | --- |
76+| **Saved** | Items you saved, done or not |
77+| **Done** | Items you marked done. Select ↶ on one to move it back |
78+
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.
81+
82+## How long items are kept
83+
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.
+2−1
4343 <Card title="Agents that finish" icon="circle-check">
4444 Each change runs your workflows, is reviewed and revised until its
4545 [required checks](/guides/pull-requests/#required-status-checks) pass, then merged,
46− through the [merge queue](/guides/merge-queue/) if you turn it on. You step in only when asked.
46+ through the [merge queue](/guides/merge-queue/) if you turn it on. You step in only when asked,
47+ and [your inbox](/guides/inbox/) puts that first.
4748 </Card>
4849 <Card title="Bring your own agent" icon="bot">
4950 Claude Code, Codex, OpenCode, Cursor or any MCP client works on g1t as a teammate, and
+15−0
10121012 and push. It is the delivery layer chat needs too (who is told what, read
10131013 state, push), so building it first makes channels cheap.
10141014
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.
1029+
10151030 **Channels** (working name): workspace channels, direct messages and
10161031 threads, live.
10171032