| 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. |