1 file+231−00/1 viewed
| 1 | + | # Channels and crew | |
| 2 | + | ||
| 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. | |
| 9 | + | ||
| 10 | + | Design canvas: the "g1t Channels" artifact (v2 row is the target). | |
| 11 | + | ||
| 12 | + | ## The point | |
| 13 | + | ||
| 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.** | |
| 72 | + | ||
| 73 | + | ## Product model | |
| 74 | + | ||
| 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. | |
| 88 | + | - **Thread.** Replies under a message. A card about an issue or pull | |
| 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. | |
| 134 | + | ||
| 135 | + | ## Scaling the sidebar | |
| 136 | + | ||
| 137 | + | Workspaces will have hundreds of channels and dozens of agents. | |
| 138 | + | ||
| 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. | |
| 147 | + | ||
| 148 | + | ## How it fits what exists | |
| 149 | + | ||
| 150 | + | | Need | Already in g1t | What changes | | |
| 151 | + | | --- | --- | --- | | |
| 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 | | |
| 162 | + | ||
| 163 | + | ## Data | |
| 164 | + | ||
| 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: | |
| 168 | + | ||
| 169 | + | - `channels`: id, workspace, name, kind (`channel` | `dm`), private, topic, | |
| 170 | + | team_id, created_by, archived_at. | |
| 171 | + | - `channel_links`: channel_id, project_id. | |
| 172 | + | - `channel_members`: channel_id, principal (person or agent), role, | |
| 173 | + | starred, section, muted, last_read_id, joined_at. | |
| 174 | + | - `messages`: id (time-sortable), channel_id, author, kind (`text` | | |
| 175 | + | `card`), body, card (JSON: subject key, state, actions), thread_root, | |
| 176 | + | reply_count, edited_at, deleted_at. | |
| 177 | + | - `reactions`: message_id, principal, emoji. | |
| 178 | + | ||
| 179 | + | In `services/work`, beside the runs: | |
| 180 | + | ||
| 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`. | |
| 187 | + | ||
| 188 | + | Agent profiles (handle, avatar, scopes, triggers, skills) extend the | |
| 189 | + | existing agent definition, not a new table elsewhere. | |
| 190 | + | ||
| 191 | + | ## Build order | |
| 192 | + | ||
| 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. | |
| 217 | + | ||
| 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. | |
| 220 | + | ||
| 221 | + | ## Open questions | |
| 222 | + | ||
| 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. |