flagon-io/g1t

public

docs: channels and crew spec, agents as teammates

Claude-Session:: https://claude.ai/code/session_011tBfr1Kv6Bbf7dhvf3zo9c

Claude and Claude Opus 5.5committed 2d agoParent2e10018Browse files

1		−	# Channels
	1	+	# Channels and crew
2	2
3		−	People and agents talk in the same place the code lives. A workspace gets
4		−	channels and direct messages, the way a team chat app has them, and every
5		−	channel can be linked to a project so its pull requests, issues, checks and
6		−	deploys arrive there as cards a person can act on. Agents are members of
7		−	channels like anyone else.
	3	+	People and agents work in the same place the code lives. You talk to an
	4	+	agent the way you talk to a teammate: message it directly, or invite it into
	5	+	a channel and mention it. You create as many as you want and give each a
	6	+	name, a job and its own limits. Issues and pull requests still exist and
	7	+	still work exactly as they do today, but they become the record of the work,
	8	+	not the way you start it.
8	9
9	10		Design canvas: the "g1t Channels" artifact (v2 row is the target).
10	11
11	12		## The point
12	13
13		−	Today a person reads g1t in two places: g1t itself, and a chat app where
14		−	the team talks about what g1t is doing. Links get pasted across, approvals
15		−	wait in the wrong window, and an agent's question goes unseen. Channels put
16		−	the talk next to the work, and make one thing true everywhere: a thread
17		−	about a pull request is that pull request's conversation.
	14	+	Today you reach an agent through an issue: write it up, assign `g1t`, wait.
	15	+	That is right for planned work and wrong for everything else, which is most
	16	+	of a day: "why is this check flaky", "take #418 over the line", "keep an eye
	17	+	on the deploy", "what changed in billing this week". A chat app with a bot
	18	+	in it answers faster but loses the work: nothing is tracked, nothing is
	19	+	reviewable, and the bot has no business touching your code.
	20	+
	21	+	g1t does both. Conversation is how work starts. Every piece of work an agent
	22	+	takes on is tracked as a task, lands as issues and pull requests when it
	23	+	touches code, and stays linked back to the conversation it came from.
	24	+
	25	+	## What you can do
	26	+
	27	+	- Message an agent. Every agent has a direct message. Ask it something,
	28	+	give it a job, steer it while it works.
	29	+	- Invite agents into channels. Mention one and it joins the thread.
	30	+	Invite it and it can see the channel and answer when mentioned or when
	31	+	its triggers fire.
	32	+	- Create your own crew. "Make me a release manager called Ship" in any
	33	+	chat, or a form. Give it a name, a handle, an avatar, a job, a model, a
	34	+	budget, what it may touch and what wakes it. Make as many as you need.
	35	+	- Talk to several at once. A group chat or channel with three agents
	36	+	and two people works the way you would expect: whoever is mentioned
	37	+	answers, and agents can ask and hand work to each other in the open.
	38	+	- See the work. Every job is a live card in the thread: steps, the
	39	+	pull request it opened, checks, cost so far, and what it is waiting on.
	40	+	- Approve where you are. When an agent needs a person, the approval is a
	41	+	card in the conversation and an item in your inbox. Acting in either
	42	+	place settles both.
	43	+	- Keep using issues. Assign an issue to an agent, mention one in a pull
	44	+	request, run the planner. All of it still works, and shows up in the
	45	+	agent's DM and the linked channels.
	46	+
	47	+	## Better than Grok Bot
	48	+
	49	+	[Grok Bot](https://docs.x.ai/grok-bot) (xAI, in Cursor and SuperGrok plans)
	50	+	sets the bar for named AI teammates: conversational setup, per-bot memory,
	51	+	a persistent cloud computer, group chats, bots handing off to each other,
	52	+	saved skills on a schedule, and Team Bots reachable in Slack. g1t matches
	53	+	each of these and goes past them where Grok Bot is weak.
	54	+
	55	+	\| \| Grok Bot \| g1t \|
	56	+	\| --- \| --- \| --- \|
	57	+	\| Create and name agents \| Yes, by describing the job \| Yes, in chat or a form; also a file (`.g1t/agents/<name>.md`) you can review and version \|
	58	+	\| Where it works \| One cloud computer shared by all your bots: files, logins and sessions are not isolated between them \| Each run in its own sandbox with its own credentials, guardrails and audit log. Nothing leaks between agents unless you share it \|
	59	+	\| Model \| Chosen for you; no picker \| Auto by default, or pin a model per agent; bring your own key or endpoint \|
	60	+	\| Spend \| Counts toward the plan's limit; no per-bot cap; a running bot can overshoot \| A budget per agent and per workspace, enforced before a run starts and during it, shown live on the job card \|
	61	+	\| Approvals \| Asks when it decides it needs you \| Required by policy: rulesets, branch protection, guardrails and the agent's own limits decide what needs a person. Not up to the agent \|
	62	+	\| Code \| Git commits as a routine trigger; Cursor for real coding \| Native: issues, pull requests, reviews, checks, merge queue, previews and deploys \|
	63	+	\| Tracking \| Work lives in chat history \| Every job is a task; code work becomes issues and pull requests linked to the thread; why-blame goes from a line to the conversation that asked for it \|
	64	+	\| Teams \| Team Bots: one shared bot, private chats per person, owner cannot read them \| Agents belong to the workspace; channels are visible to members; DMs are private; the audit log covers every action either way \|
	65	+	\| Memory \| Per bot; hidden \| Per agent and per workspace (Memory and Context pages), readable and editable, with sources \|
	66	+	\| Bots together \| Message each other, hand off \| The same, plus they see what each other is changing (overlap) and ask questions that wait in the open \|
	67	+	\| Triggers \| Schedules, Slack messages, git commits, @bot on X \| Schedules, any g1t event (opened, failed, deployed, mentioned, labelled), channel messages, webhooks \|
	68	+	\| Openness \| Closed; a SuperGrok link can never be undone \| MIT, self-hostable, any MCP client joins as a participant, export everything \|
	69	+
	70	+	The pitch in one line: **Grok Bot's teammates, with their own desks, their
	71	+	own budgets, and a paper trail.**
18	72
19	73		## Product model
20	74
21		−	- Modes. The shell gets a rail: Home, Code, Chat, Agents, Inbox. Code
22		−	keeps today's sidebar exactly. Chat has a sidebar of its own. Inbox is
23		−	shared by both. No mode's sidebar ever lists the other mode's things.
24		−	- Channel. Belongs to a workspace. Public or private. Optionally linked
25		−	to one or more projects, and optionally to a team. Has members: people
26		−	and agents.
27		−	- Message. Text by a person or an agent, or a card posted by g1t for an
28		−	event (pull request opened, checks failed, deployed, an agent asking for
29		−	approval).
	75	+	- Modes. The shell gets a rail: Home, Code, Chat, Crew, Inbox. Code
	76	+	keeps today's sidebar exactly. Chat and Crew have sidebars of their own.
	77	+	Inbox is shared. No mode's sidebar lists the other mode's things.
	78	+	- Agent. A named member of a workspace: handle, display name, avatar,
	79	+	job (its instructions), model choice, budget, scopes (which projects and
	80	+	channels, read or write), skills, triggers and memory. Stored as an agent
	81	+	definition in the workspace library, optionally committed to a repository
	82	+	as `.g1t/agents/<name>.md`. Built-in roles (planner, implementer,
	83	+	reviewer, triage) are agents too, renamable.
	84	+	- Channel. Belongs to a workspace. Public or private. Linked to zero or
	85	+	more projects and optionally a team. Members are people and agents.
	86	+	- Direct message. A channel with no name. Any mix of people and agents.
	87	+	- Message. Text by a member, or a card g1t posts for an event or a job.
30	88		- Thread. Replies under a message. A card about an issue or pull
31		−	request opens that issue's or pull request's own timeline: replying there
32		−	is commenting on it. Other threads belong to the channel.
33		−	- Direct message. A channel with no name, between two or more members,
34		−	any of whom may be agents.
35		−	- Project chat. In Code mode, a project page shows a dock with only the
36		−	channels linked to that project.
	89	+	request opens that item's own timeline: replying there is commenting on
	90	+	it. Other threads belong to the channel.
	91	+	- Task. One job an agent took on: who asked, in which thread, what done
	92	+	means, status, cost, and what it produced (issues, pull requests,
	93	+	deploys, files, answers). Tasks are the bridge: they start in
	94	+	conversation and end in the code.
	95	+	- Skill. A saved procedure an agent can repeat, made by walking it
	96	+	through once in chat. Stored like an agent definition.
	97	+	- Trigger. What wakes an agent without a mention: a schedule, a g1t
	98	+	event, a message in a channel it watches, a webhook.
	99	+
	100	+	## How a task runs
	101	+
	102	+	1. Someone asks in a DM or mentions an agent in a thread.
	103	+	2. The agent replies with what it understood and, if it is not a pure
	104	+	question, opens a task card: the goal, what done means, the budget it
	105	+	will use.
	106	+	3. It works in its own sandbox. The card updates live: steps, logs, cost.
	107	+	4. When it changes code it opens a pull request in the usual way. The
	108	+	pull request links the task, and the card shows its checks. If the work
	109	+	is bigger than one change, it asks the planner, which opens issues with
	110	+	dependencies under the task.
	111	+	5. Anything that needs a person (merging past protection, deploying to
	112	+	production, spending past its budget, reaching outside its scopes)
	113	+	becomes an approval card and an inbox item.
	114	+	6. It posts what it did and closes the task. The thread, the task, the
	115	+	issues and the pull requests all point at each other.
	116	+
	117	+	A plain question ("why did this fail?") never makes a task. Mentioning an
	118	+	agent in a pull request that already has one steers it instead.
	119	+
	120	+	## Creating an agent
	121	+
	122	+	In any chat: "make an agent called Ship that cuts releases for g1t every
	123	+	Tuesday and asks me before tagging." g1t replies with a draft card:
	124	+	name, handle `@ship`, avatar, job, model (Auto), budget, scopes
	125	+	(`flagon-io/g1t`, write), skills (none yet), triggers (Tuesdays 9:00),
	126	+	approvals (tagging a release). You edit any field on the card and confirm.
	127	+	The same card is the form on the Crew page. Saving writes the definition,
	128	+	posts an introduction in the channels it was added to, and opens its DM.
	129	+
	130	+	Inviting an agent into a channel shows what that gives it: the channel's
	131	+	messages and, if the channel is linked to projects, read access to them.
	132	+	Write access is never granted by an invite; it comes from the agent's
	133	+	scopes.
37	134
38	135		## Scaling the sidebar
39	136
40		−	Workspaces will have hundreds of channels. The Chat sidebar never lists
41		−	them all:
	137	+	Workspaces will have hundreds of channels and dozens of agents.
42	138
43		−	- Starred first, chosen by the person.
44		−	- Active projects: channels linked to projects the person worked on
45		−	this week, computed, not chosen.
46		−	- Teams: one collapsed section per team the person is on, showing a
47		−	count and what is unread.
48		−	- Direct messages, newest first.
49		−	- All / Unread / Mentions filter, and a jump box. Everything else is
50		−	behind Browse channels and Muted.
	139	+	- Chat sidebar: Starred; active projects (channels linked to projects
	140	+	you worked on this week, computed); one collapsed section per team you
	141	+	are on, with a count and what is unread; direct messages, newest first;
	142	+	All / Unread / Mentions filter and a jump box. Everything else is behind
	143	+	Browse channels and Muted.
	144	+	- Crew sidebar: agents you talk to, then agents working right now with
	145	+	their task, then All agents. Each shows a status: idle, working,
	146	+	waiting on you.
51	147
52	148		## How it fits what exists
53	149
54	150		\| Need \| Already in g1t \| What changes \|
55	151		\| --- \| --- \| --- \|
56		−	\| Live delivery \| Durable Objects (runner, models) \| One Durable Object per channel holds the open WebSockets, with hibernation. D1 keeps the messages. \|
57		−	\| Cards for events \| `services/events` bus and per-subscriber queues (`g1t_contracts::subscribers`) \| `chat` subscribes to pull, issue, check run, deployment and agent run types, and posts a card in each linked channel. \|
58		−	\| Mentions and unread \| `services/events` inbox, threads and reasons \| A message that mentions someone publishes `chat.message.created`; the inbox tells them with reason `mention`. Thread keys reuse `<repo_id>#<number>`. \|
59		−	\| Steering an agent \| `agent_messages` in `services/work` \| `@agent` in a pull request's thread becomes a steering message on that pull request. \|
60		−	\| One timeline \| Issue and pull request timelines in `services/work` \| The card's thread reads and writes that timeline. Chat stores only a pointer. \|
61		−	\| Navigation \| `workspace-nav.ts`, `shell.tsx` \| A rail, a `mode` beside `SidebarKey`, and a Chat sidebar. \|
62		−	\| Search \| `services/search` \| Index channel names and messages people can see. \|
	152	+	\| Agent definitions \| `.g1t/agents/<name>.md` and the workspace library (PLAN: Defining an agent) \| Adds handle, avatar, scopes, triggers and skills; created from chat \|
	153	+	\| Runs, budgets, models \| Runner contract, AI Gateway, billing, Auto routing \| A run can belong to a task, not only a pull request \|
	154	+	\| Steering and agents asking each other \| `agent_messages` in `services/work` (message, question, handoff) \| Delivered from and posted to threads \|
	155	+	\| Guardrails and audit \| Guardrails, rulesets, audit log \| Decide which steps become approval cards \|
	156	+	\| Live delivery \| Durable Objects (runner, models) \| One Durable Object per channel holds open WebSockets, with hibernation; D1 keeps the messages \|
	157	+	\| Cards for events \| `services/events` bus and per-subscriber queues (`g1t_contracts::subscribers`) \| `chat` subscribes to pull, issue, check run, deployment and agent run types and posts cards to linked channels and to the asking thread \|
	158	+	\| Mentions, approvals, unread \| `services/events` inbox, threads and reasons \| `chat.message.created` and `task.approval_requested` feed the inbox; thread keys reuse `<repo_id>#<number>` and add `task/<id>` \|
	159	+	\| Memory \| Memory and Context pages \| An agent's memory is shown on its profile and editable \|
	160	+	\| Navigation \| `workspace-nav.ts`, `shell.tsx` \| A rail, a `mode` beside `SidebarKey`, Chat and Crew sidebars \|
	161	+	\| Search \| `services/search` \| Channel names, messages and tasks people can see \|
63	162
64	163		## Data
65	164
66		−	A new service, `services/chat` (TypeScript, like `services/projects`,
67		−	because the Durable Object and WebSocket code is simplest there), with its
68		−	own D1 database:
	165	+	A new service, `services/chat` (TypeScript, like `services/projects`, since
	166	+	the Durable Object and WebSocket code is simplest there), with its own D1
	167	+	database:
69	168
70	169		- `channels`: id, workspace, name, kind (`channel` \| `dm`), private, topic,
71	170		team_id, created_by, archived_at.
72		−	- `channel_links`: channel_id, project_id. What makes a channel a
73		−	project's chat, and where cards go.
	171	+	- `channel_links`: channel_id, project_id.
74	172		- `channel_members`: channel_id, principal (person or agent), role,
75	173		starred, section, muted, last_read_id, joined_at.
76	174		- `messages`: id (time-sortable), channel_id, author, kind (`text` \|
⋯
78	176		reply_count, edited_at, deleted_at.
79	177		- `reactions`: message_id, principal, emoji.
80	178
81		−	Unread counts come from `last_read_id` against the newest message id, kept
82		−	in the channel's Durable Object, so the sidebar needs one read per
83		−	section, not per channel.
	179	+	In `services/work`, beside the runs:
84	180
85		−	## Agents in channels
	181	+	- `tasks`: id, workspace, agent, asked_by, channel_id, thread_root, goal,
	182	+	done_when, status (`planned` \| `working` \| `waiting` \| `done` \|
	183	+	`cancelled`), budget, spent, created_at, closed_at.
	184	+	- `task_links`: task_id, kind (`issue` \| `pull` \| `deploy` \| `file`),
	185	+	subject key.
	186	+	- `agent_runs` gains a nullable `task_id`.
86	187
87		−	- An agent is added to a channel like a person, with the agent's own
88		−	credentials, guardrails and audit log. Private channels exclude agents
89		−	unless added by name.
90		−	- A mention in a pull request's thread steers that pull request's agent
91		−	(`agent_messages`). A mention anywhere else starts an agent run whose
92		−	replies post in the thread.
93		−	- Asking a person for approval (merge past branch protection, deploy to
94		−	production) posts a card with the actions on it, and the same item lands
95		−	in the person's inbox. Acting in either place resolves both.
	188	+	Agent profiles (handle, avatar, scopes, triggers, skills) extend the
	189	+	existing agent definition, not a new table elsewhere.
96	190
97	191		## Build order
98	192
99		−	1. Contracts. Channel, message and card types in `packages/contracts`
100		−	and `crates/contracts`; the RPC methods; the new event types.
101		−	2. Channels. `services/chat`, its migrations, a Durable Object per
102		−	channel, and `deploy/stack.jsonc` entries. Create, join, post, edit,
103		−	threads, reactions, read state.
104		−	3. Chat mode. The rail in `shell.tsx`; the Chat sidebar with starred,
105		−	sections, filters and browse; the channel page; the composer with
106		−	mentions. Code mode is unchanged apart from the rail.
107		−	4. Mentions to the inbox. `chat.message.created` and inbox rows with
108		−	reason `mention`.
109		−	5. Project links and cards. Link a channel to a project; the events
110		−	subscriber; cards for pull requests, issues, checks and deploys; the
111		−	project chat dock in Code mode.
112		−	6. One timeline. A card's thread is the issue's or pull request's
113		−	timeline, both ways, with "also send to channel".
114		−	7. Agents. Agents as members, steering by mention, approval cards,
115		−	direct messages with agents.
116		−	8. Scale. Team sections, computed active-project section, muting,
117		−	browse, search.
	193	+	1. Contracts. Channel, message, card, task and agent profile types in
	194	+	`packages/contracts` and `crates/contracts`; RPC methods; new event types.
	195	+	2. Channels. `services/chat`, migrations, a Durable Object per channel,
	196	+	`deploy/stack.jsonc` entries. Create, join, post, edit, threads,
	197	+	reactions, read state.
	198	+	3. Chat and Crew modes. The rail in `shell.tsx`; the Chat sidebar; the
	199	+	channel page; the composer with mentions of people and agents; the Crew
	200	+	page listing agents with status.
	201	+	4. Talk to an agent. DMs with agents; a question gets an answer in the
	202	+	thread with no task; a job creates a task and a live task card; runs
	203	+	with a `task_id`.
	204	+	5. Create your crew. The draft-card flow in chat and on the Crew page;
	205	+	handles, avatars, scopes, budgets; invite to channels.
	206	+	6. Approvals as cards. Guardrails, rulesets and budgets raise approval
	207	+	cards and inbox items; acting in either settles both.
	208	+	7. Project links and the one timeline. Channels linked to projects;
	209	+	event cards; the project chat dock in Code mode; a card's thread is the
	210	+	issue's or pull request's timeline.
	211	+	8. Agents together. Several agents in one thread; questions and
	212	+	handoffs posted in the open; overlap shown on task cards.
	213	+	9. Skills and triggers. Walk an agent through a procedure once and save
	214	+	it; schedules, g1t events and channel messages as triggers.
	215	+	10. Scale. Team sections, the computed active-project section, muting,
	216	+	browse, search.
118	217
119		−	Steps 1 to 4 are a usable chat; 5 and 6 are what no chat app can do.
	218	+	Steps 1 to 4 replace "assign an issue" as the everyday way to reach an
	219	+	agent. Steps 5 to 7 are where g1t passes Grok Bot.
120	220
121	221		## Open questions
122	222
123		−	- Must every channel belong to a project or team? Requiring one makes the
124		−	sidebar's sections better and orphans fewer channels.
125		−	- Do agents get their own mode, or only appear as direct messages?
126		−	- Retention and export for workspaces that need it.
127		−	- Does a self-hosted install ship chat, or is it hosted only at first?
	223	+	- Must every channel belong to a project or team?
	224	+	- Does every task show up in the issue list, or only tasks that produced
	225	+	issues? (Suggested: only those, with a Tasks tab per project.)
	226	+	- Can a person's own Claude Code or Cursor session be invited into a
	227	+	channel as a member, the way it joins over MCP today?
	228	+	- Should agents be reachable from Slack too, one app per workspace with a
	229	+	handle per agent, for teams that will not move their chat?
	230	+	- Retention and export, and whether self-hosted installs ship chat at
	231	+	first.