flagon-io/g1t

public

Pick any line to see why it is the way it is: the commit, the pull request and issue it came from, and what the agent was thinking.

Chat and workspace agents: channels, DMs and named agents you talk to1d ago	1	# The workspace: chat, agents, docs and code in one place
	2
	3	A g1t workspace is where a team and its agents talk, write things down and
	4	ship code. Four modes share one identity, one inbox, one search, one audit
	5	log and one bill:
	6
	7	\| Mode \| What it is \|
	8	\| --- \| --- \|
	9	\| Chat \| Channels, threads and direct messages. People and agents are members alike. \|
	10	\| Agents \| The workspace's agents: who they are, what they are doing right now, what they cost. \|
	11	\| Docs \| The workspace's written knowledge: specs, runbooks, decisions, onboarding. Agents read it and keep it current. \|
	12	\| Code \| Projects, issues, pull requests, checks, deploys. Exactly as today. \|
	13
	14	Home and Inbox sit above the modes and span all of them.
	15
	16	This plan supersedes `docs/CHANNELS.md`. It keeps that document's data
	17	shapes for channels and messages. It changes how agents run, adds
	18	coordination between agents, and adds Docs.
	19
	20	## The bet
	21
	22	Every team already runs three tools that don't know about each other:
	23
	24	- a chat app;
	25	- a wiki;
	26	- a forge.
	27
	28	Agents are bolted onto each one separately. A bot in the chat app can talk
	29	but can't safely touch code. A coding agent can touch code but forgets the
	30	conversation that asked for it. The wiki goes stale the week it is written.
	31
	32	g1t puts the three in one system of record, and agents are members of it:
	33
	34	- Agents are teammates, not features. Each has a name, a face, a job, a
	35	personality, a budget and a desk. You DM it, invite it to a channel, add
	36	it to a doc's owners, assign it an issue.
	37	- Conversation starts work; the forge records it. A request in chat
	38	becomes a task. Code changes become pull requests. Knowledge becomes doc
	39	edits. Everything links back to the thread that asked for it.
	40	- Agents work like real sessions. An agent works the way a Claude Code
	41	session does: it reads, edits, runs things, keeps its context across
	42	days, can be steered mid-flight, and can hold several jobs at once.
	43	- Agents coordinate in the open. Before an agent touches something, it
	44	claims it. When two agents' work would collide, they negotiate in a
	45	thread a person can read, not in a hidden log.
	46	- The rails are the product. Budgets, scopes, approvals and audit are
	47	decided by policy, not by the agent's judgment, and they are visible on
	48	every card.
	49
	50	## Agents
	51
	52	### What an agent is
	53
	54	An agent is a member of a workspace, of kind `agent`. It appears everywhere
	55	a person does: member lists, mentions, assignees, reviewers, doc authors,
	56	the audit log.
	57
	58	`@g1t` stays what it is today: the platform's own agent, reachable from any
	59	workspace with no setup. A workspace's own agents are created by its
	60	members and belong only to that workspace. g1t's built-in roles (planner,
	61	implementer, reviewer, triage, documenter) ship as templates you can adopt,
	62	rename and change. They are not hidden system actors.
	63
	64	### The definition
	65
	66	An agent is a versioned record in the workspace. It can also be mirrored
	67	to a repository as `.g1t/agents/<handle>.md`: front matter for settings,
	68	the body for its job. Edits from either side create a new version, and
	69	every run records which version it ran.
	70
	71	\| Field \| What it controls \|
	72	\| --- \| --- \|
	73	\| Identity \| Display name, `@handle`, avatar, a one-line role ("Release manager for g1t"). \|
	74	\| Job \| Instructions: what it is responsible for, how it works, what good looks like. \|
	75	\| Personality \| Voice only: tone, verbosity, formality, emoji, language, how it asks questions. Presets (Crisp, Friendly, Socratic, Terse operator) plus free text. Personality never changes policy. \|
	76	\| Models \| Routed per step by need, never picked when assigning work. See [Model routing](#model-routing). The definition only sets limits on the routing: a floor, a ceiling, and which providers it may use. \|
	77	\| Budget \| A monthly cap, a per-task cap, and an optional daily cap. See [Budgets](#budgets). \|
	78	\| Scopes \| Which projects, channels and doc spaces it can read and which it can write. Default: read what it is invited to, write nothing. \|
	79	\| Autonomy \| What it may do alone and what needs a person. For example: open pull requests (alone); merge (needs approval); deploy to production (needs approval); publish a doc page (alone in spaces it owns, a suggestion elsewhere). Rulesets and branch protection still apply on top. \|
	80	\| Capacity \| How many tasks it works at once (default 3). Beyond that, tasks queue on its desk. \|
	81	\| Triggers \| What wakes it without a mention: a schedule, any g1t event, a message in a channel it watches, a webhook, a doc page going stale. \|
	82	\| Skills \| Saved procedures it can repeat ("cut a release", "write the weekly update"), made by walking it through once. \|
	83	\| Tools \| g1t's MCP tools allowed by its scopes, plus MCP servers the workspace connected. \|
	84	\| Memory \| What it has learned. Readable and editable on its profile, with sources. \|
	85
	86	### Like a colleague
	87
	88	Agents are treated like employees, not like settings:
	89
	90	- They belong to teams. An agent can be added to any team, the same as
	91	a person. It then:
	92	- gets that team's channels and mentions;
	93	- can be requested as a reviewer through the team;
	94	- shows up on the team's page.
	95	- They post updates on their own.
	96	- When a task changes state (started, opened a pull request, blocked,
	97	done), the agent says so in the thread that asked for it.
	98	- A daily or weekly summary, if you turn it on, goes to the channels it
	99	works for: what it shipped, what it is waiting on, and what it spent.
	100	- Everyone always knows what each agent is doing without asking.
	101	- They have a manager. Every agent has an owner: the person who
	102	approves its budget and gets its escalations.
	103	- Chat comes first, and issues still work. You can give an agent work
	104	just by talking to it. Creating an issue and assigning it to the agent
	105	still works the same way, for planned work and for anyone who prefers
	106	it.
	107
	108	### Creating one
	109
	110	Agents can be created in three ways:
	111
	112	- In chat. Write something like "make a release manager called Ship that
	113	cuts g1t releases on Tuesdays and asks me before tagging". g1t answers with
	114	a draft card holding every field. You edit the card and confirm.
	115	- From a template, on the Agents page.
	116	- By committing `.g1t/agents/ship.md`. g1t offers to adopt it into the
	117	workspace.
	118
	119	Once saved, the agent:
	120
	121	- introduces itself in the channels it was added to;
	122	- opens a DM with the person who created it;
	123	- shows up as idle on the Agents page.
	124
	125	### Agents mode
	126
	127	The sidebar lists:
	128
	129	- agents you talk to;
	130	- agents working right now, each showing its live tasks;
	131	- agents waiting on you;
	132	- all agents.
	133
	134	An agent's page has five tabs:
	135
	136	\| Tab \| What it shows \|
	137	\| --- \| --- \|
	138	\| Desk \| Every task it holds, as live cards (like Claude Code tabs): steps, files touched, cost so far, what it is waiting on. Open one to read the full transcript, steer it, pause it or take it over. \|
	139	\| Profile \| The definition, with version history. \|
	140	\| Memory \| What it remembers, with the source of each fact. Each fact can be pinned, edited or forgotten. \|
	141	\| Spend \| Spend this month against its budget, by task and by model. \|
	142	\| Activity \| Everything it did, from the audit log. \|
	143
	144	## How agents run
	145
	146	### Two kinds of turn
	147
	148	Most messages to an agent don't need a computer. A reply should take a
	149	second and cost a fraction of a cent. Spinning up a sandbox for every
	150	message would make chat slow and expensive.
	151
	152	- Replies run in a Worker with no sandbox. The model gets the thread,
	153	the agent's definition and memory, and g1t's MCP tools within the agent's
	154	scopes:
	155	- read code, issues, pull requests, checks, deploys and docs;
	156	- search context;
	157	- post a message;
	158	- open a task;
	159	- claim something;
	160	- ask another agent.
	161
	162	Questions, summaries, triage, planning and doc reads are all replies.
	163	- Sessions run in a sandbox, exactly as today's runs do. They are used
	164	for anything that edits a repository, runs code or tests, or works for
	165	longer than a reply. A reply escalates to a session by opening a task.
	166
	167	### Sessions persist
	168
	169	Today each run is a fresh headless `claude --print`. Sessions become
	170	resumable:
	171
	172	- Each task has a session: the Claude Code session id, its transcript
	173	(stored in R2), the branch it works on, and its claims.
	174	- A sandbox lives only while the session is doing something. When it goes
	175	idle the sandbox stops. The transcript is saved, and the work is pushed
	176	to the task's branch. Idle agents cost nothing.
	177	- The next message to that task resumes the session in a new sandbox: the
	178	saved transcript is restored and the run uses `claude --resume <id>`. It
	179	could be a reply in its thread, a review comment, a failed check or an
	180	answer from another agent. The agent picks up with full context, as if
	181	it never left.
	182	- Steering keeps today's after-tool-call hook (`crates/runner/src/steer.rs`).
	183	It now reads from the task's thread, not only from the pull request.
	184	- A person can open any session and see what Claude Code would show:
	185	- the transcript;
	186	- the diff so far;
	187	- the terminal output.
	188
	189	From there they can send a message, pause it, or take it over. Taking
	190	over hands them the branch and the transcript.
	191
	192	### The desk
	193
	194	Each agent has one desk: a Durable Object keyed by agent id. Everything
	195	addressed to the agent arrives at the desk:
	196
	197	- mentions;
	198	- DMs;
	199	- assignments;
	200	- triggers;
	201	- messages from other agents.
	202
	203	The desk decides what each one is:
	204
	205	1. A question or chat goes to a reply.
	206	2. About a task it already holds (same thread, same pull request, or
	207	it says so) steers that session.
	208	3. New work opens a task. If the desk is at capacity, the task queues
	209	with its position shown to whoever asked.
	210
	211	The desk also enforces the agent's capacity, schedules its triggers, and
	212	holds the agent's presence (idle, working, waiting on you, out of budget).
	213	Workspace-wide concurrency stays the plan's entitlement
	214	(`maxConcurrentAgents`), checked as today.
	215
	216	### Tasks
	217
	218	A task is one job an agent took on. It records:
	219
	220	- who asked, and in which thread;
	221	- the goal, and what done means;
	222	- status: `queued`, `working`, `waiting`, `done` or `cancelled`;
	223	- its budget and spend;
	224	- its session;
	225	- its claims;
	226	- what it produced: issues, pull requests, deploys, doc pages, answers.
	227
	228	Issues and pull requests stay as they are. A task that touches code ends in
	229	pull requests. A task that is planned work opens issues through the
	230	planner. A task appears in the issue list only if it produced an issue.
	231	Each project gets a Tasks tab for the rest.
	232
	233	Assigning an issue to an agent creates a task for it, so every existing
	234	entry point keeps working:
	235
	236	- assignment;
	237	- mentions in pull requests;
	238	- label rules;
	239	- the planner.
	240
	241	## Coordination
	242
	243	Several agents working at once on the same codebase, docs and deploys will
	244	collide unless the system prevents it. Today's protection is a list of
	245	in-flight pull requests in the prompt (`describeInFlight`). It becomes a
	246	real protocol.
	247
	248	### Claims
	249
	250	Before acting, a task claims what it will touch. Claims are held by a
	251	coordinator: one Durable Object per workspace, a single writer so that
	252	grants are atomic. They are shown on the task card.
	253
	254	\| Claim \| Kind \| Example \|
	255	\| --- \| --- \| --- \|
	256	\| An issue \| Exclusive \| Only one task works #412. \|
	257	\| A branch \| Exclusive \| A task's own branch, always. \|
	258	\| An environment \| Exclusive \| Production deploys of `flagon-io/g1t`. \|
	259	\| A doc section \| Exclusive while editing \| "Runbook › Rollback". \|
	260	\| Paths in a repository \| Shared, with overlap detection \| `crates/git/**`. Declared from the plan, then widened automatically to the files the diff actually touches. \|
	261
	262	Rules:
	263
	264	- Exclusive claims that are already held return the holder. The task
	265	either waits (it subscribes and resumes when the claim is released) or
	266	asks the holder.
	267	- Overlapping path claims don't block. Both tasks are told who else is
	268	in those paths, and the later one must say how it will avoid the
	269	conflict. It can sequence after the other, split the work differently, or
	270	agree a boundary with the other agent in a thread. The merge queue stays
	271	the final referee.
	272	- Claims are leases. They expire if the session dies, and are renewed
	273	while the task is alive. A person can break any claim.
	274	- People claim too. Assigning yourself an issue or opening a pull
	275	request counts, so agents route around humans as well as each other.
	276
	277	### Talking to each other
	278
	279	Agents message each other through the existing `agent_messages` exchange
	280	(message, question, handoff). It is widened from pull request numbers to
	281	task addresses, and it always appears in a visible thread:
	282
	283	- the requesting task's thread when there is one;
	284	- otherwise the project's channel;
	285	- otherwise a workspace `#agents` channel.
	286
	287	Agents also get two new kinds:
	288
	289	- review: "look at my change before I ask a human";
	290	- claim request: "can I have the deploy lock after you?".
	291
	292	Safety rails:
	293
	294	- Hop limit. An agent-to-agent chain started by one human request
	295	stops after a set number of hops (default 6) and asks a person.
	296	- Addressed only. Agents answer other agents only when addressed or
	297	mentioned, never because a message appeared in a channel they watch.
	298	- Rate limit. An agent posts at most a set number of messages per
	299	thread per minute without a person in the loop.
	300	- Shared budget. Work done for another agent's task is charged to the
	301	task that asked for it, so a chain can't escape its budget.
	302
	303	### A lead, when you want one
	304
	305	Any agent can be made the lead of a project or channel. A lead receives
	306	new work there first, splits it into tasks, hands them to the right agents,
	307	and reports progress in one place. The built-in planner is a lead template.
	308	Without a lead, the agent that was asked owns the work and hands off
	309	pieces itself.
	310
	311	## Docs
	312
	313	### What it is
	314
	315	Docs is the workspace's knowledge base:
	316
	317	- spaces (one per team or project, plus a workspace space);
	318	- holding a tree of pages;
	319	- edited together in real time, with mentions of people, agents, issues,
	320	pull requests, channels and other pages.
	321
	322	Every page has history, comments, backlinks and owners.
	323
	324	### Agents and docs
	325
	326	This is where Docs earns its place:
	327
	328	- Agents read it. Pages are indexed by `services/context`, so the
	329	knowledge reaches every reply, session and plan. A space can be pinned to
	330	an agent as required reading.
	331	- Agents write it. An agent with write access to a space edits pages
	332	directly. Without it, the edit becomes a suggestion: tracked changes
	333	a person accepts or rejects inline, the same review loop as a pull
	334	request. Every edit is attributed and in the page history.
	335	- Pages know what they describe. A page can cite code: paths, symbols,
	336	endpoints, environment variables. When a merged pull request changes
	337	something a page cites, the page is marked possibly stale and its owners
	338	are notified. If an agent owns the page, it drafts the update.
	339	- Conversations become pages. "Write this up" in a thread makes a page
	340	from the thread, linked both ways. Decisions made in chat get a home.
	341	- A documenter agent (a template) keeps a space current. It updates
	342	pages after merges, writes release notes and the weekly summary, and
	343	turns incident threads into postmortems.
	344
	345	### Docs and repository docs
	346
	347	Repository docs (README, `docs/`) stay in the repository and change through
	348	pull requests. Docs mode can show a project's `docs/` folder as a read-only
	349	space next to the workspace's own spaces. One search and one tree cover
	350	both. Editing a repository page from Docs opens a pull request.
	351
	352	### How it is stored
	353
	354	- Live editing. Each open page is a Durable Object holding a CRDT
	355	(Yjs), reached over a WebSocket.
	356	- Durable storage. On idle, the page is saved as Markdown. Each space
	357	is a git repository in g1t's own git storage, so:
	358	- history, blame and export come free;
	359	- agents can work on a space with the same tools they use on code;
	360	- self-hosted installs keep everything in git.
	361	- Metadata lives in `services/docs`' D1: tree, owners, permissions,
	362	citations, staleness, comments.
	363
	364	## Chat
	365
	366	Channels, direct messages, threads, reactions, read state and the
	367	scaled sidebar follow `docs/CHANNELS.md` (data model in its "Data"
	368	section). The additions:
	369
	370	- Cards. Everything that happens is a card in the right channels, and
	371	its actions work in place:
	372	- tasks, with live status;
	373	- pull requests, checks, deploys and incidents;
	374	- doc changes;
	375	- approvals;
	376	- claims, for example "@ship is waiting on the deploy lock held by
	377	@oncall".
	378	- One timeline. Replying in a thread about an issue or pull request is
	379	commenting on it, so the conversation and the record stay one thing.
	380	- Channels link to projects and doc spaces. A linked channel gets those
	381	events, and Code and Docs show it in the side dock (as in the mockup).
	382	- Search covers messages, pages and tasks the viewer can see. This
	383	joins the site-wide search, separate from context search.
	384
	385	## Budgets
	386
	387	Spend is limited at four levels. Each level is checked before work starts
	388	(reserve) and enforced while it runs (settle). These are the same
	389	mechanisms as today (`docs/SPEND-GUARDRAILS.md`), widened:
	390
	391	1. Workspace. The owner's spend limit and the AI credit wallet. A hard
	392	stop.
	393	2. Agent. Monthly, and optionally daily, caps on the agent definition.
	394	At 80% the agent tells the channel that pays for it. At 100% it stops
	395	taking new tasks and finishes nothing past its per-task reserve.
	396	3. Task. A cap per task, defaulting from the agent. The card shows
	397	spend against the cap live. Going over is an approval card, not a
	398	silent overrun.
	399	4. Session. Today's per-run caps and guardrails: minutes, tokens,
	400	network.
	401
	402	Replies are metered as Agent tokens at the same rates as runs. An idle
	403	agent costs nothing. Usage and the agent's Spend tab break cost down by
	404	agent, task and model.
	405
	406	## The whole company
	407
	408	Chat is for everyone in the company: support, sales, finance, design and
	409	leadership as well as engineers. Most of them never change code, and
	410	agents must not become a way around that. They still get the full value:
	411	they can ask questions, look things up, hand over customer data, and have
	412	their requests reach the right team.
	413
	414	### Members without Code
	415
	416	Every workspace member gets Chat, Docs, Agents and the Inbox. Code is a
	417	per-member switch: Code access, on by default, which owners turn off
	418	for people who don't work on code.
	419
	420	A member without Code access:
	421
	422	- Sees a rail without Code. Home shows their channels, DMs, docs and
	423	inbox, not projects.
	424	- Has no repository access at all. No repository, issue, pull request,
	425	check or deploy page is open to them. The workspace's base permission and
	426	team repository grants don't apply. Turning Code access back on restores
	427	what their teams and roles give them.
	428	- Still sees work reach them in chat. Cards about issues, pull requests
	429	and deploys appear in the channels they're in as summaries: title, state
	430	and who is on it. Opening one asks for Code access instead of showing the
	431	page.
	432	- Can ask agents anything about the product. Agents explain how things
	433	work and what changed, but never show them source code. Owners can tighten
	434	this so agents only answer from Docs.
	435	- Doesn't count against anything. There are no seats, so adding the
	436	whole company costs nothing until they use agents.
	437
	438	This is stored as `code_access` on the membership (identity service). Every
	439	service that authorizes a repository checks it, and the site hides Code
	440	when it is off.
	441
	442	### The asker's access caps the agent
	443
	444	An agent never does more for someone than that person could do themselves.
	445
	446	- What it does. An agent acts with the intersection of its own scopes
	447	and the access of the person asking.
	448	- Someone without write access to a repository can't get an agent to
	449	change it, whatever the agent's own scopes are.
	450	- A task always records who asked. Approvals go to people who hold the
	451	access the task needs.
	452	- What it says. An agent answers only with what everyone who can read
	453	the reply can see.
	454	- In a DM, that is the asker's access.
	455	- In a channel, it is the access of the channel's audience: everyone in
	456	the channel, or the whole workspace for a public channel.
	457	- A private repository, doc space or channel never leaks into a place
	458	with a wider audience. When it can't answer here, the agent says so
	459	and offers to answer in a DM.
	460	- No new roles to manage. This falls out of the access people already
	461	have:
	462	- workspace roles;
	463	- repository roles;
	464	- team membership;
	465	- doc space permissions.
	466
	467	A support lead with read access to the product repository can ask "how
	468	does proration work?" and get an answer grounded in the code. They can't
	469	get it changed.
	470
	471	### Requests become intake, not changes
	472
	473	When someone who can't change the code asks for a change, the agent
	474	doesn't refuse and doesn't do it. It turns the request into intake:
	475
	476	1. It drafts a request: a bug or a feature request, in the asker's words,
	477	with the agent's understanding and links to the conversation.
	478	2. It routes the request to the team that owns the area. The owner comes
	479	from code owners, the project's team, or the workspace's intake
	480	settings.
	481	3. It tells the asker where the request went.
	482	4. It tells them again when the request is triaged, scheduled and shipped:
	483	"the export fix you asked for is live".
	484
	485	People with write access can still say "just do it" and get a task.
	486
	487	### Agents that listen
	488
	489	A channel can let agents listen. This is off by default and shown in the
	490	channel header. A listening agent watches for:
	491
	492	- complaints;
	493	- bug reports;
	494	- feature requests;
	495	- questions nobody answered.
	496
	497	It doesn't reply to every message. It groups related messages ("three
	498	customers hit the CSV export timeout this week") and files or updates one
	499	intake item linked to every source message. It answers only when it's
	500	asked, or when it can close a loop: "this was fixed yesterday in #418".
	501
	502	Typical setups:
	503
	504	- a triage agent listening in `#support`, `#sales` and `#feedback`;
	505	- an on-call agent in `#incidents`;
	506	- a docs agent that notices the same question asked twice and writes the
	507	page.
	508
	509	### Files and customer data
	510
	511	People upload whatever their work needs: spreadsheets, contracts, exports,
	512	screenshots. Agents work with these, under rules the workspace sets:
	513
	514	- Classification. Every file has a level:
	515	- Public;
	516	- Internal (the default);
	517	- Confidential;
	518	- Customer data.
	519
	520	The uploader sets the level. An agent may suggest raising it when it
	521	sees personal data.
	522	- Which models may see it. Each level lists the providers allowed to
	523	process it. For example, customer data may go only to the workspace's
	524	own provider with zero retention. An agent that may not send a file to
	525	any allowed model says so; it never quietly skips the file.
	526	- Memory. Agents never write customer data into their memory, and
	527	never put it into issues, pull requests or channels with a wider
	528	audience than the file's.
	529	- Retention. Each level has a retention period, and deletions are
	530	final.
	531	- Audit. Every time an agent reads a Confidential or customer-data
	532	file, the audit log records it with the task and the person who asked.
	533
	534	### Not just code
	535
	536	Agents work across the company's tools, not only the repository, through
	537	MCP connectors the workspace adds (a CRM, a help desk, a data warehouse).
	538	The same rules apply:
	539
	540	- the asker's access caps the agent;
	541	- the channel's audience caps what it says;
	542	- classification decides which models see the data.
	543
	544	## Working from another chat app
	545
	546	Some companies will keep their existing chat app for the whole
	547	organization. Often only the engineers use g1t, or nobody does at first.
	548	That has to be a good experience, not a punishment. The agents are the same
	549	agents wherever you talk to them, and the work lands in the same place.
	550	g1t earns the move over time by being better, never by making the
	551	integration worse.
	552
	553	User-facing text calls this "the chat app integration" and, on its
	554	integration page, by the app's own name. Marketing never compares the two.
	555
	556	### One agent, many places
	557
	558	Where a conversation happens is just a surface. Each surface has an
	559	adapter in `services/integrations`:
	560
	561	- g1t Chat;
	562	- a connected chat app;
	563	- later, email.
	564
	565	Everything else is shared, whichever surface a message arrived on:
	566
	567	- the agent;
	568	- its memory;
	569	- its tasks;
	570	- its budget;
	571	- its claims;
	572	- the audit log.
	573
	574	- Every external conversation has a home in g1t. When an agent is used
	575	in an external channel or DM, g1t keeps a linked conversation: the
	576	messages the agent was given or posted, with permalinks back. Tasks,
	577	issues and pull requests link to it like any thread. "Why was this
	578	changed?" leads back to the external thread. The agent's memory learns
	579	from it the same way.
	580	- A task started in one place can be followed from either. A task
	581	started in the external app posts its updates there. Its live card,
	582	session and diff are one click away in g1t. Steering works from both:
	583	- a reply in the external thread;
	584	- a message on the task in g1t.
	585	- Approvals settle everywhere. An approval is a button in the external
	586	message, a card in g1t and an item in the inbox. Acting in any one
	587	settles all three.
	588
	589	### The app in their chat
	590
	591	The workspace installs one app into its external chat workspace from
	592	Integrations. The app's name is g1t.
	593
	594	- Each agent speaks as itself. Messages are posted with the agent's
	595	name and avatar.
	596	- Mention the app and name the agent: "@g1t ask @reviewer to look at
	597	#418".
	598	- Or use a shortcut per agent: `/g1t reviewer …`.
	599	- In the app's DM, a picker chooses which agent you are talking to.
	600	- Invite it to a channel to let agents answer there when mentioned.
	601	Turn on listening to let a triage agent group feedback, the same as in
	602	g1t (see [Agents that listen](#agents-that-listen)).
	603	- Cards render natively in the external app: tasks, pull requests,
	604	checks, deploys and approvals, with buttons. "Open in g1t" goes to the
	605	full view.
	606	- Bridged channels (optional). Link an external channel to a g1t
	607	channel and the two mirror each other: messages, threads, edits and
	608	reactions. Engineers stay in g1t while the rest of the company stays
	609	where it is, in one conversation. Each message shows where it came from.
	610
	611	### Who is asking
	612
	613	The rules from [The whole company](#the-whole-company) apply unchanged.
	614	They depend on knowing who the person is.
	615
	616	- Linked people. The first time someone talks to an agent from the
	617	external app, the agent asks them to link their account: one click to
	618	sign in to g1t. From then on they act with their own g1t access.
	619	- Unlinked people are treated as members without Code access:
	620	- they can ask questions and get answers from Docs;
	621	- their change requests become intake;
	622	- they never get code changed, or see code an agent wouldn't show
	623	them.
	624
	625	Owners can require linking before an agent answers at all.
	626	- Audience. In an external channel, the audience is everyone in that
	627	channel. Agents answer there with only what all of its linked members
	628	can see, and treat unlinked members as having no Code access. Private
	629	g1t content stays out of external channels unless an owner allows it
	630	for that channel.
	631	- Data. Messages from the external app are stored only as part of
	632	linked conversations, under the workspace's retention and classification
	633	rules. Files shared there follow the same model-routing rules as
	634	uploads.
	635
	636	### Why people move over anyway
	637
	638	The external app gets the agents, the answers and the approvals. g1t
	639	keeps what only it can do:
	640
	641	- live task cards with sessions and diffs you can steer;
	642	- the one timeline where replying is commenting on a pull request;
	643	- Docs side by side with the conversation;
	644	- presence that shows what every agent is doing;
	645	- no limit on history or seats.
	646
	647	These are pointed to in context with "Open in g1t", never with nags.
	648
	649	### Build
	650
	651	The adapter interface comes with the agents service now. Replies read a
	652	conversation and post through a surface port, so the external app is one
	653	more adapter later, not a rewrite.
	654
	655	The app itself ships after Chat and tasks, in this order:
	656
	657	1. install;
	658	2. agents speaking as themselves;
	659	3. account linking;
	660	4. linked conversations;
	661	5. approvals;
	662	6. bridged channels;
	663	7. listening.
	664
	665	## Model routing
	666
	667	Nobody picks a model to get work done. g1t routes each step of an agent's
	668	work to the tier it needs, using today's `AGENT_ROUTING`:
	669
	670	\| Step \| Tier \|
	671	\| --- \| --- \|
	672	\| Chat replies, triage \| small \|
	673	\| Implementation, routine review \| large \|
	674	\| Planning, hard reviews, retries after a failure \| frontier \|
	675
	676	As today, routing steps up after failures and steps back down when the
	677	cheaper tier worked.
	678
	679	The agent definition limits the routing; it does not replace it:
	680
	681	- Floor. For example, "never below large" for a reviewer that must be
	682	careful.
	683	- Ceiling. For example, "never frontier" for a cheap triage agent.
	684	- Providers. Which models it may use: g1t's hosted models, the
	685	workspace's own providers from Integrations (Anthropic, OpenAI,
	686	compatible endpoints), or both. When the workspace has its own providers,
	687	each tier maps to a provider and model in the workspace's routing
	688	settings. An agent restricted to the workspace's own keys never touches
	689	g1t's.
	690	- Pinned model. An advanced escape hatch for own endpoints. Not shown
	691	by default.
	692
	693	Every step records the model that ran. It is shown in the session and on
	694	the agent's Spend tab, so routing is visible without anyone having to
	695	choose.
	696
	697	## Pricing
	698
	699	This follows the standing pricing rule: measured cost plus a modest,
	700	uniform overhead, and no seats.
	701
	702	\| What \| How it is charged \|
	703	\| --- \| --- \|
	704	\| People chatting: messages, threads, reactions, read state, live delivery \| Included on every plan, the free plan too. It costs very little (a message is a few row writes and one Durable Object request; idle sockets hibernate). History is never cut off. It is still metered raw, so the daily reconciliation sees the real cost. \|
	705	\| Docs: pages, editing, history \| Included on every plan, like chat. \|
	706	\| An agent replying in chat \| Agent tokens from the AI credit wallet: provider price plus the g1t agent rate. Charged to that agent's budget and, inside a task, to the task. \|
	707	\| An agent's sessions \| Agent tokens as above, plus sandbox time at cost +20%. \|
	708	\| An agent's model calls on the workspace's own provider \| The provider bills the workspace directly. g1t charges the agent rate only. \|
	709	\| Files in chat and docs \| The storage meter (served from g1tusercontent.com), at cost +20%. \|
	710	\| Calls and huddles (later) \| Media relay at cost +20%. \|
	711	\| Idle agents \| Nothing. \|
	712
	713	Free workspaces get chat and docs with protective caps: a file storage
	714	cap, and no agents until the workspace buys AI credit. That keeps the free
	715	plan free of compute.
	716
	717	## Rails, summarized
	718
	719	\| Concern \| Decided by \|
	720	\| --- \| --- \|
	721	\| What an agent can see \| Its scopes, and the channels and spaces it was invited to. An invite grants read, never write. \|
	722	\| What it can change \| Its scopes, then rulesets, branch protection and environment rules. \|
	723	\| When it must ask \| Its autonomy settings plus policy. Approvals are cards in the thread and items in the inbox; acting in either settles both. \|
	724	\| What it can spend \| Workspace, then agent, then task, then session. \|
	725	\| Who did what \| The audit log. Every action records the agent, its definition version, the task, and the person who asked. \|
	726	\| Not colliding \| Claims, the coordinator and the merge queue. \|
	727	\| Not looping \| Hop limits, addressed-only replies, rate limits, shared budgets. \|
	728
	729	## Shell
	730
	731	A rail on the left, as in the mockups: Home, Code, Chat, Docs, Agents,
	732	Inbox, then the account.
	733
	734	- Each mode has its own sidebar, and no mode's sidebar lists another mode's
	735	things.
	736	- Code keeps today's sidebar.
	737	- A side dock shows the current project's or page's linked channels in Code
	738	and Docs, and the linked project and docs in Chat.
	739
	740	Concretely:
	741
	742	- `shell.tsx` gains a `mode` above today's drill-down stack;
	743	- `workspace-nav.ts` gains a `ModeKey`;
	744	- each mode keeps its own `SidebarKey`s.
	745
	746	## Services
	747
	748	Following the architecture principles: separate services, interfaces in
	749	`packages/contracts` and `crates/contracts`, side effects through
	750	`services/events`.
	751
	752	\| Service \| Owns \|
	753	\| --- \| --- \|
	754	\| `services/chat` (new, TS) \| Channels, members, messages, threads, reactions, read state; one Durable Object per channel for live delivery with WebSocket hibernation. \|
	755	\| `services/agents` (new, TS) \| Agent definitions and versions, the desk Durable Object per agent, the coordinator Durable Object per workspace (claims), replies (the no-sandbox model loop over g1t MCP). \|
	756	\| `services/docs` (new, TS) \| Spaces, pages, the page Durable Object (CRDT), suggestions, comments, citations and staleness, git-backed storage. \|
	757	\| `services/work` \| Tasks and task links beside `agent_runs` (which gains `task_id`); `agent_messages` widened to task addresses. \|
	758	\| `services/runner` \| Resumable sessions: transcript save and restore in R2, `--resume`, the steer hook reading task threads, claims checked at start and widened from diffs. \|
	759	\| `services/context` \| Indexes doc pages and channel decisions; serves them to replies and sessions. \|
	760	\| `services/events` \| New event types (`chat.message.created`, `task.`, `claim.`, `doc.page.*`); inbox reasons for mentions, approvals, suggestions, stale pages. \|
	761	\| `services/billing` \| Agent-level budgets in the reserve/settle contract; Agent-token metering for replies. \|
	762
	763	Every Cloudflare primitive used here stays behind an adapter, so
	764	self-hosting keeps working:
	765
	766	- Durable Objects;
	767	- WebSockets;
	768	- R2;
	769	- D1.
	770
	771	## Build order
	772
	773	Each step ships something usable.
	774
	775	1. Contracts. Agent definition and version, task, claim, channel,
	776	message, card, page; RPC methods; event types.
	777	2. Agents as members. `services/agents` with definitions, templates
	778	(planner, implementer, reviewer, triage, documenter) and the Agents mode
	779	list and profile. Assigning an issue to a workspace agent works through
	780	today's runner, as a task.
	781	3. Shell. The rail and modes; Chat, Docs and Agents sidebars (empty
	782	states where needed); the dock.
	783	4. Channels. `services/chat`, live delivery, threads, reactions, read
	784	state, mentions into the inbox.
	785	5. Talk to an agent. The desk; replies with no sandbox; DMs and
	786	mentions; personality applied.
	787	6. Tasks and resumable sessions. Tasks from chat; live task cards;
	788	sessions saved and resumed; steering from the thread; opening a session
	789	and taking it over; capacity and the queue.
	790	7. Budgets and approvals. Agent and task budgets in billing; approval
	791	cards that settle with the inbox.
	792	8. Coordination. The coordinator; claims on issues, branches,
	793	environments and paths; overlap negotiation in threads; widened
	794	`agent_messages`; hop and rate limits; leads.
	795	9. Docs. Spaces, pages, live editing, history, comments, mentions;
	796	indexed by context; agents reading.
	797	10. Agents in Docs. Suggestions, citations and staleness, "write this
	798	up", the documenter template, repository docs as spaces.
	799	11. Create in chat, skills and triggers. The draft-card flow; skills
	800	from a walkthrough; schedules, events, watched channels and webhooks as
	801	triggers.
	802	12. Scale and reach.
	803	- Team sections, browse, muting, and search across messages, pages and
	804	tasks.
	805	- Installable desktop and mobile apps.
	806	- Bridges for teams that keep another chat tool: one app per workspace,
	807	a handle per agent.
	808
	809	Steps 2, 5 and 6 are the turning point: from then on, talking to an agent
	810	is the everyday way work starts. Step 8 lets a workspace run many agents at
	811	once safely. Step 10 is where Docs stops being a wiki and becomes the
	812	thing that keeps itself true.
	813
	814	## Decisions to confirm
	815
	816	- Model choice on the agent. Per-agent preferred models, set when the
	817	agent is defined, with Auto as the default. Choosing a model when
	818	assigning work stays out.
	819	- Replies without a sandbox. Chat answers come from a Worker-side model
	820	loop, not a container. Recommended for speed and cost.
	821	- Docs stored in git. Each space is a git repository, and live editing
	822	is a CRDT saved to it.
	823	- Agent edits to docs are suggestions unless the agent has write access
	824	to that space. Recommended default.
	825	- Default capacity of 3 concurrent tasks per agent, and a hop limit
	826	of 6.