From 2c7df0d80d451d15742baa696e488b93e7adec58 Mon Sep 17 00:00:00 2001
From: Phelipe Lorran <112786693+httpsphl@users.noreply.github.com>
Date: Fri, 9 Oct 2026 13:25:47 -0300
Subject: [PATCH 1/2] feat(app): state filters in the conversation list

Chips for all, needs you, working and unread, with counts; a crew with
nothing in the chosen state steps aside. Window-only, not remembered.
---
 app/src/features/crews/Sidebar.tsx          | 12 +++-
 app/src/features/crews/StateFilters.tsx     | 48 +++++++++++++
 app/src/features/crews/stateFilter.test.tsx | 42 +++++++++++
 app/src/features/crews/stateFilter.ts       | 77 +++++++++++++++++++++
 app/src/i18n/en/crews.ts                    |  7 ++
 app/src/i18n/es/crews.ts                    |  7 ++
 app/src/i18n/pt-BR/crews.ts                 |  7 ++
 7 files changed, 198 insertions(+), 2 deletions(-)
 create mode 100644 app/src/features/crews/StateFilters.tsx
 create mode 100644 app/src/features/crews/stateFilter.test.tsx
 create mode 100644 app/src/features/crews/stateFilter.ts

diff --git a/app/src/features/crews/Sidebar.tsx b/app/src/features/crews/Sidebar.tsx
index ec59085c..c3d0c8f8 100644
--- a/app/src/features/crews/Sidebar.tsx
+++ b/app/src/features/crews/Sidebar.tsx
@@ -6,7 +6,7 @@ import { type Messages, useT } from "../../i18n";
 import { when } from "../../lib/format";
 import { plainText } from "../../lib/plainText";
 import type { Activity, Bot, Crew } from "../../lib/protocol.gen";
-import { activityOf, botsOf, crewList } from "../../store/app";
+import { activityOf, crewList } from "../../store/app";
 import { useApp } from "../../store/context";
 import { isUnread, unreadIn } from "../../store/seen";
 import { CountBadge } from "../../ui/Badge";
@@ -22,6 +22,8 @@ import { CrewDialog } from "./CrewDialog";
 import { setAllCollapsed, setCollapsed, useCollapsed, useCollapsedSet } from "./collapsed";
 import { useCrewActions } from "./crewActions";
 import { row } from "./SidebarPages";
+import { StateFilters } from "./StateFilters";
+import { filteredBots, useStateFilter } from "./stateFilter";
 
 /** Crews as sections and their bots as conversations (spec 15.1). */
 export function Sidebar() {
@@ -63,6 +65,7 @@ export function Sidebar() {
             onClick={() => setCreating(true)}
           />
         </div>
+        {crews.length > 0 && <StateFilters />}
         <ul className="min-h-0 flex-1 overflow-y-auto px-2 pb-3">
           {crews.map((crew) => (
             <CrewEntry key={crew.id} crew={crew} />
@@ -76,7 +79,8 @@ export function Sidebar() {
 
 function CrewEntry({ crew }: { crew: Crew }) {
   const t = useT();
-  const bots = useApp(useShallow((state) => botsOf(state, crew.id)));
+  const filter = useStateFilter();
+  const bots = useApp(useShallow((state) => filteredBots(state, crew.id, filter)));
   const selected = useApp((state) => state.selectedCrewId === crew.id && !state.selectedBotId);
   const unread = useApp((state) => unreadIn(state, crew.id));
   const selectCrew = useApp((state) => state.selectCrew);
@@ -92,6 +96,10 @@ function CrewEntry({ crew }: { crew: Crew }) {
     collapsed && bots.some((bot) => bot.state === "needs_approval" || bot.state === "auth_error");
   const words = t.crews.sidebar;
 
+  // Filtering, a crew with nothing to show steps aside.
+  if (filter !== "all" && bots.length === 0) {
+    return null;
+  }
   return (
     <li className="mt-2">
       <div className="relative flex items-center">
diff --git a/app/src/features/crews/StateFilters.tsx b/app/src/features/crews/StateFilters.tsx
new file mode 100644
index 00000000..2809ee9d
--- /dev/null
+++ b/app/src/features/crews/StateFilters.tsx
@@ -0,0 +1,48 @@
+import { useShallow } from "zustand/react/shallow";
+import { useT } from "../../i18n";
+import { useApp } from "../../store/context";
+import {
+  filterCounts,
+  STATE_FILTERS,
+  type StateFilter,
+  setStateFilter,
+  useStateFilter,
+} from "./stateFilter";
+
+/** Chips above the conversation list: all, needs you, working, unread. */
+export function StateFilters() {
+  const t = useT();
+  const words = t.crews.sidebar.filters;
+  const active = useStateFilter();
+  const counts = useApp(useShallow(filterCounts));
+  const label: Record<StateFilter, string> = {
+    all: words.all,
+    needs: words.needs,
+    working: words.working,
+    unread: words.unread,
+  };
+  return (
+    <fieldset
+      aria-label={words.label}
+      className="m-0 flex min-w-0 flex-wrap gap-1 border-0 p-0 px-2 pb-1.5"
+    >
+      {STATE_FILTERS.map((filter) => {
+        const on = filter === active;
+        return (
+          <button
+            key={filter}
+            type="button"
+            aria-pressed={on}
+            onClick={() => setStateFilter(filter)}
+            className={`flex items-center gap-1 rounded-full px-2 py-0.5 font-medium text-xs transition-colors ${on ? "bg-ink text-canvas" : "bg-sunken text-muted hover:text-ink"}`}
+          >
+            {label[filter]}
+            {counts[filter] > 0 && (
+              <span className="tabular-nums opacity-70">{counts[filter]}</span>
+            )}
+          </button>
+        );
+      })}
+    </fieldset>
+  );
+}
diff --git a/app/src/features/crews/stateFilter.test.tsx b/app/src/features/crews/stateFilter.test.tsx
new file mode 100644
index 00000000..9bd2720a
--- /dev/null
+++ b/app/src/features/crews/stateFilter.test.tsx
@@ -0,0 +1,42 @@
+import { act, cleanup, fireEvent, within } from "@testing-library/react";
+import { afterEach, describe, expect, test } from "vitest";
+import { FakeBotloft } from "../../lib/fake";
+import { crewOpened, renderApp, sidebar } from "../../test/app";
+import { resetStateFilter } from "./stateFilter";
+
+afterEach(() => {
+  cleanup();
+  resetStateFilter();
+});
+
+describe("state filters in the conversation list", () => {
+  test("a chip narrows the list to the bots in that state, with counts", async () => {
+    const fake = new FakeBotloft();
+    const ops = fake.addCrew("Ops");
+    const calm = fake.addCrew("Calm");
+    const scout = fake.addBot(ops.id, "Scout");
+    const writer = fake.addBot(ops.id, "Writer");
+    const idle = fake.addBot(calm.id, "Idle one");
+    fake.setBotState(scout.id, "busy");
+    fake.setBotState(writer.id, "needs_approval");
+    fake.setBotState(idle.id, "idle");
+    renderApp(fake);
+    await crewOpened("Ops");
+
+    const list = within(sidebar());
+    expect(list.getByRole("button", { name: /^Working\s*1$/ })).toBeTruthy();
+    expect(list.getByRole("button", { name: /^All\s*3$/ })).toBeTruthy();
+
+    fireEvent.click(list.getByRole("button", { name: /^Needs you/ }));
+    expect(list.queryByRole("button", { name: /^Scout,/ })).toBeNull();
+    expect(list.getByRole("button", { name: /^Writer,/ })).toBeTruthy();
+    // A crew with nothing in that state steps aside.
+    expect(list.queryByText("Calm")).toBeNull();
+
+    act(() => fake.setBotState(scout.id, "needs_approval"));
+    expect(list.getByRole("button", { name: /^Scout,/ })).toBeTruthy();
+
+    fireEvent.click(list.getByRole("button", { name: /^All/ }));
+    expect(list.getByText("Calm")).toBeTruthy();
+  });
+});
diff --git a/app/src/features/crews/stateFilter.ts b/app/src/features/crews/stateFilter.ts
new file mode 100644
index 00000000..84b561fc
--- /dev/null
+++ b/app/src/features/crews/stateFilter.ts
@@ -0,0 +1,77 @@
+// The conversation list's state filter: all, needs you, working, unread. It
+// lasts for this window only; a filter left on across restarts would look
+// like missing bots.
+
+import { useSyncExternalStore } from "react";
+import type { Bot } from "../../lib/protocol.gen";
+import type { AppState } from "../../store/app";
+import { botsOf, crewList } from "../../store/app";
+import { isUnread } from "../../store/seen";
+
+export const STATE_FILTERS = ["all", "needs", "working", "unread"] as const;
+export type StateFilter = (typeof STATE_FILTERS)[number];
+
+let current: StateFilter = "all";
+const listeners = new Set<() => void>();
+
+export function setStateFilter(next: StateFilter): void {
+  if (next === current) {
+    return;
+  }
+  current = next;
+  for (const listener of listeners) {
+    listener();
+  }
+}
+
+const subscribe = (listener: () => void) => {
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+};
+
+export function useStateFilter(): StateFilter {
+  return useSyncExternalStore(subscribe, () => current);
+}
+
+/** Back to all bots, for tests. */
+export function resetStateFilter(): void {
+  setStateFilter("all");
+}
+
+/** Whether a bot belongs under `filter`. Unread is passed in: it lives in the store. */
+export function matchesFilter(filter: StateFilter, bot: Bot, unread: boolean): boolean {
+  switch (filter) {
+    case "needs":
+      return bot.state === "needs_approval" || bot.state === "auth_error";
+    case "working":
+      return bot.state === "busy" || bot.state === "launching";
+    case "unread":
+      return unread;
+    default:
+      return true;
+  }
+}
+
+/** The bots of a crew that pass `filter`. */
+export function filteredBots(state: AppState, crewId: string, filter: StateFilter): Bot[] {
+  const bots = botsOf(state, crewId);
+  return filter === "all"
+    ? bots
+    : bots.filter((bot) => matchesFilter(filter, bot, isUnread(state, bot.id)));
+}
+
+/** How many bots each filter would show, across every crew. */
+export function filterCounts(state: AppState): Record<StateFilter, number> {
+  const counts: Record<StateFilter, number> = { all: 0, needs: 0, working: 0, unread: 0 };
+  for (const crew of crewList(state)) {
+    for (const bot of botsOf(state, crew.id)) {
+      const unread = isUnread(state, bot.id);
+      for (const filter of STATE_FILTERS) {
+        if (matchesFilter(filter, bot, unread)) {
+          counts[filter] += 1;
+        }
+      }
+    }
+  }
+  return counts;
+}
diff --git a/app/src/i18n/en/crews.ts b/app/src/i18n/en/crews.ts
index d0a0e45e..1aca287e 100644
--- a/app/src/i18n/en/crews.ts
+++ b/app/src/i18n/en/crews.ts
@@ -26,6 +26,13 @@ export const crews = {
     expand: (crew: string) => `Unfold ${crew}`,
     /** Beside a folded crew's name, when one of its bots needs the owner. */
     waiting: "a bot needs you",
+    filters: {
+      label: "Filter conversations",
+      all: "All",
+      needs: "Needs you",
+      working: "Working",
+      unread: "Unread",
+    },
   },
   /** The page of all crews, opened from "Crews" on the left. */
   overview: {
diff --git a/app/src/i18n/es/crews.ts b/app/src/i18n/es/crews.ts
index cc3dd453..6930bbd7 100644
--- a/app/src/i18n/es/crews.ts
+++ b/app/src/i18n/es/crews.ts
@@ -19,6 +19,13 @@ export const crews: Messages["crews"] = {
     collapse: (crew: string) => `Contraer ${crew}`,
     expand: (crew: string) => `Expandir ${crew}`,
     waiting: "un bot te necesita",
+    filters: {
+      label: "Filtrar conversaciones",
+      all: "Todas",
+      needs: "Te necesitan",
+      working: "Trabajando",
+      unread: "Sin leer",
+    },
   },
   overview: {
     count: (count: number) => (count === 1 ? "1 equipo" : `${count} equipos`),
diff --git a/app/src/i18n/pt-BR/crews.ts b/app/src/i18n/pt-BR/crews.ts
index a3fb5c1c..d8ebecb1 100644
--- a/app/src/i18n/pt-BR/crews.ts
+++ b/app/src/i18n/pt-BR/crews.ts
@@ -19,6 +19,13 @@ export const crews: Messages["crews"] = {
     collapse: (crew: string) => `Recolher ${crew}`,
     expand: (crew: string) => `Expandir ${crew}`,
     waiting: "um bot precisa de você",
+    filters: {
+      label: "Filtrar conversas",
+      all: "Todas",
+      needs: "Precisam de você",
+      working: "Trabalhando",
+      unread: "Não lidas",
+    },
   },
   overview: {
     count: (count: number) => (count === 1 ? "1 equipe" : `${count} equipes`),

From 688149b92858a6a6fc5d5de523c044f4ae0f2938 Mon Sep 17 00:00:00 2001
From: Phelipe Lorran <112786693+httpsphl@users.noreply.github.com>
Date: Fri, 9 Oct 2026 13:42:12 -0300
Subject: [PATCH 2/2] feat(crews): a color for each crew

crews.setColor stores a #RRGGBB (migration 0025); the rename dialog has
swatches and the crew list shows a dot beside the name.
---
 app/src/features/crews/CrewColorField.tsx     | 46 +++++++++++++++++++
 app/src/features/crews/CrewDialog.tsx         |  8 +++-
 app/src/features/crews/Sidebar.tsx            |  8 ++++
 app/src/features/crews/crewColor.test.tsx     | 31 +++++++++++++
 app/src/i18n/en/crews.ts                      |  3 ++
 app/src/i18n/es/crews.ts                      |  3 ++
 app/src/i18n/pt-BR/crews.ts                   |  3 ++
 app/src/lib/fakeCrews.ts                      |  6 +++
 app/src/lib/protocol.gen.ts                   | 11 +++++
 crates/botloft-core/src/protocol/export.rs    |  6 +++
 crates/botloft-core/src/protocol/methods.rs   |  9 ++++
 crates/botloft-core/src/protocol/mod.rs       |  1 +
 crates/botloft-core/src/protocol/model.rs     |  2 +
 .../migrations/0025_crew_color.sql            |  2 +
 crates/botloft-store/src/bots/tests.rs        |  1 +
 crates/botloft-store/src/crews.rs             | 19 +++++---
 crates/botloft-store/src/lib.rs               |  1 +
 crates/botloft-store/src/migrate.rs           |  1 +
 crates/botloftd/src/rpc/dispatch.rs           |  1 +
 crates/botloftd/src/service/crews.rs          | 22 ++++++++-
 crates/botloftd/src/workspace/files.rs        |  1 +
 crates/botloftd/src/workspace/folder.rs       |  1 +
 crates/botloftd/src/workspace/mod.rs          |  2 +
 crates/botloftd/tests/rpc_crews_bots.rs       | 23 ++++++++++
 docs/spec.md                                  |  3 +-
 25 files changed, 204 insertions(+), 10 deletions(-)
 create mode 100644 app/src/features/crews/CrewColorField.tsx
 create mode 100644 app/src/features/crews/crewColor.test.tsx
 create mode 100644 crates/botloft-store/migrations/0025_crew_color.sql

diff --git a/app/src/features/crews/CrewColorField.tsx b/app/src/features/crews/CrewColorField.tsx
new file mode 100644
index 00000000..93b5ee70
--- /dev/null
+++ b/app/src/features/crews/CrewColorField.tsx
@@ -0,0 +1,46 @@
+import { Check } from "lucide-react";
+import { useT } from "../../i18n";
+import { AVATAR_PALETTE } from "../../lib/protocol.gen";
+
+/** Swatches for a crew's color, and a way to have none. */
+export function CrewColorField({
+  value,
+  onChange,
+}: {
+  value: string | null;
+  onChange(color: string | null): void;
+}) {
+  const words = useT().crews.dialog;
+  const same = (a: string | null, b: string | null) => a?.toLowerCase() === b?.toLowerCase();
+  return (
+    <fieldset className="m-0 flex flex-col gap-1.5 border-0 p-0">
+      <legend className="mb-1.5 font-medium text-ink-soft text-sm">{words.color}</legend>
+      <div className="flex flex-wrap items-center gap-1.5">
+        <button
+          type="button"
+          aria-pressed={value === null}
+          onClick={() => onChange(null)}
+          className={`rounded-lg px-2 py-1 font-medium text-xs ${value === null ? "bg-sunken text-ink ring-2 ring-accent" : "text-muted hover:text-ink"}`}
+        >
+          {words.noColor}
+        </button>
+        {AVATAR_PALETTE.map((swatch) => {
+          const on = same(value, swatch);
+          return (
+            <button
+              key={swatch}
+              type="button"
+              aria-label={words.swatch(swatch)}
+              aria-pressed={on}
+              onClick={() => onChange(swatch)}
+              className={`relative grid size-7 place-items-center rounded-full ${on ? "ring-2 ring-accent ring-offset-2 ring-offset-panel" : ""}`}
+              style={{ background: swatch }}
+            >
+              {on && <Check aria-hidden size={14} className="text-black/70" />}
+            </button>
+          );
+        })}
+      </div>
+    </fieldset>
+  );
+}
diff --git a/app/src/features/crews/CrewDialog.tsx b/app/src/features/crews/CrewDialog.tsx
index a6436cfa..e572e9e7 100644
--- a/app/src/features/crews/CrewDialog.tsx
+++ b/app/src/features/crews/CrewDialog.tsx
@@ -9,6 +9,7 @@ import { SelectField, TextArea, TextField } from "../../ui/Field";
 import { notifyError } from "../../ui/toast";
 import { useCatalog } from "../catalog/useCatalog";
 import { addTemplateBots } from "./addTemplateBots";
+import { CrewColorField } from "./CrewColorField";
 import type { CrewTemplate } from "./crewTemplates";
 import { PickedTemplate, TemplatePicker } from "./TemplatePicker";
 import { WorkFolderField } from "./WorkFolderField";
@@ -22,6 +23,7 @@ export function CrewDialog({ crew, onClose }: { crew?: Crew; onClose(): void })
   const putCrew = useApp((state) => state.putCrew);
   const selectCrew = useApp((state) => state.selectCrew);
   const [name, setName] = useState(crew?.name ?? "");
+  const [color, setColor] = useState<string | null>(crew?.color ?? null);
   const [folder, setFolder] = useState<string | null>(null);
   const [goal, setGoal] = useState("");
   const [chiefModel, setChiefModel] = useState<BotModel>("default");
@@ -49,7 +51,7 @@ export function CrewDialog({ crew, onClose }: { crew?: Crew; onClose(): void })
     setError(null);
     try {
       const d = t.crews.dialog;
-      const saved = crew
+      let saved = crew
         ? await api.call("crews.rename", { crewId: crew.id, name })
         : await api.call("crews.create", {
             name,
@@ -62,6 +64,9 @@ export function CrewDialog({ crew, onClose }: { crew?: Crew; onClose(): void })
               ...(chiefModel !== "default" && { model: chiefModel }),
             },
           });
+      if (crew && color !== crew.color) {
+        saved = await api.call("crews.setColor", { crewId: crew.id, color });
+      }
       putCrew(saved);
       if (!crew) {
         selectCrew(saved.id);
@@ -134,6 +139,7 @@ export function CrewDialog({ crew, onClose }: { crew?: Crew; onClose(): void })
           autoFocus
           required
         />
+        {crew && <CrewColorField value={color} onChange={setColor} />}
         {!crew && (
           <>
             <TextArea
diff --git a/app/src/features/crews/Sidebar.tsx b/app/src/features/crews/Sidebar.tsx
index c3d0c8f8..feeab6b3 100644
--- a/app/src/features/crews/Sidebar.tsx
+++ b/app/src/features/crews/Sidebar.tsx
@@ -127,6 +127,14 @@ function CrewEntry({ crew }: { crew: Crew }) {
           }}
           className={`${row} h-8 gap-2 pr-2.5 pl-8 font-semibold text-sm ${selected || menuAt ? "bg-sunken" : ""}`}
         >
+          {crew.color && (
+            <span
+              aria-hidden
+              data-testid="crew-color"
+              className="size-2.5 shrink-0 rounded-full"
+              style={{ background: crew.color }}
+            />
+          )}
           <span className="min-w-0 flex-1 truncate">{crew.name}</span>
           {waiting && (
             <span className="flex shrink-0">
diff --git a/app/src/features/crews/crewColor.test.tsx b/app/src/features/crews/crewColor.test.tsx
new file mode 100644
index 00000000..daf680c6
--- /dev/null
+++ b/app/src/features/crews/crewColor.test.tsx
@@ -0,0 +1,31 @@
+import { cleanup, fireEvent, screen, within } from "@testing-library/react";
+import { afterEach, describe, expect, test } from "vitest";
+import { FakeBotloft } from "../../lib/fake";
+import { crewOpened, renderApp, sidebar } from "../../test/app";
+
+afterEach(cleanup);
+
+describe("a crew's color", () => {
+  test("the owner picks one in the rename dialog and it shows beside the crew", async () => {
+    const fake = new FakeBotloft();
+    const crew = fake.addCrew("Ops");
+    fake.addBot(crew.id, "Scout");
+    renderApp(fake);
+    await crewOpened("Ops");
+    expect(within(sidebar()).queryByTestId("crew-color")).toBeNull();
+
+    fireEvent.contextMenu(within(sidebar()).getByRole("button", { name: /^Ops/ }), {
+      clientX: 100,
+      clientY: 100,
+    });
+    const menu = screen.getByRole("menu", { name: "Actions for Ops" });
+    fireEvent.click(within(menu).getByRole("menuitem", { name: "Rename" }));
+    const dialog = await screen.findByRole("dialog");
+    fireEvent.click(within(dialog).getByRole("button", { name: "Color #5EC8FF" }));
+    fireEvent.click(within(dialog).getByRole("button", { name: "Rename" }));
+
+    const dot = await within(sidebar()).findByTestId("crew-color");
+    expect(dot.style.background).toMatch(/#5ec8ff|rgb\(94, 200, 255\)/i);
+    expect(fake.crew(crew.id).color).toBe("#5EC8FF");
+  });
+});
diff --git a/app/src/i18n/en/crews.ts b/app/src/i18n/en/crews.ts
index 1aca287e..65b2bb33 100644
--- a/app/src/i18n/en/crews.ts
+++ b/app/src/i18n/en/crews.ts
@@ -43,6 +43,9 @@ export const crews = {
     noBots: "No bots yet",
   },
   dialog: {
+    color: "Color",
+    noColor: "No color",
+    swatch: (color: string) => `Color ${color}`,
     folder: "Work folder",
     folderHint: "Where the bots put what they make. It can be a folder you already use.",
     folderDefault: "A new folder inside Botloft",
diff --git a/app/src/i18n/es/crews.ts b/app/src/i18n/es/crews.ts
index 6930bbd7..985d26c2 100644
--- a/app/src/i18n/es/crews.ts
+++ b/app/src/i18n/es/crews.ts
@@ -35,6 +35,9 @@ export const crews: Messages["crews"] = {
     noBots: "Ningún bot todavía",
   },
   dialog: {
+    color: "Color",
+    noColor: "Sin color",
+    swatch: (color: string) => `Color ${color}`,
     folder: "Carpeta de trabajo",
     folderHint: "Donde los bots guardan lo que hacen. Puede ser una carpeta que ya usas.",
     folderDefault: "Una carpeta nueva dentro de Botloft",
diff --git a/app/src/i18n/pt-BR/crews.ts b/app/src/i18n/pt-BR/crews.ts
index d8ebecb1..a40739c4 100644
--- a/app/src/i18n/pt-BR/crews.ts
+++ b/app/src/i18n/pt-BR/crews.ts
@@ -35,6 +35,9 @@ export const crews: Messages["crews"] = {
     noBots: "Nenhum bot ainda",
   },
   dialog: {
+    color: "Cor",
+    noColor: "Sem cor",
+    swatch: (color: string) => `Cor ${color}`,
     folder: "Pasta de trabalho",
     folderHint: "Onde os bots guardam o que fazem. Pode ser uma pasta que você já usa.",
     folderDefault: "Uma pasta nova dentro do Botloft",
diff --git a/app/src/lib/fakeCrews.ts b/app/src/lib/fakeCrews.ts
index d71539f4..dafb5877 100644
--- a/app/src/lib/fakeCrews.ts
+++ b/app/src/lib/fakeCrews.ts
@@ -32,6 +32,7 @@ export function crewHandlers(fake: FakeBotloft): Pick<Handlers, CrewMethods> {
         workFolder: workFolder === undefined ? sharedFolder(slug) : checkFolder(workFolder),
         workFolderChosen: workFolder !== undefined,
         leadBotId: null,
+        color: null,
         paused: false,
         createdAt: fake.now,
         archivedAt: null,
@@ -53,6 +54,11 @@ export function crewHandlers(fake: FakeBotloft): Pick<Handlers, CrewMethods> {
       crew.leadBotId = botId;
       return fake.changedCrew(crew);
     },
+    "crews.setColor": ({ crewId, color }) => {
+      const crew = fake.crew(crewId);
+      crew.color = color === null ? null : color.toUpperCase();
+      return fake.changedCrew(crew);
+    },
     "crews.rename": ({ crewId, name }) => {
       const crew = fake.crew(crewId);
       crew.name = checkName(name);
diff --git a/app/src/lib/protocol.gen.ts b/app/src/lib/protocol.gen.ts
index 5d38e1d4..dab73383 100644
--- a/app/src/lib/protocol.gen.ts
+++ b/app/src/lib/protocol.gen.ts
@@ -113,6 +113,10 @@ workFolderChosen: boolean,
  * `null` when the crew has no chief.
  */
 leadBotId: BotId | null, paused: boolean, 
+/**
+ * Color `#RRGGBB` the owner gave the crew; `null` for none.
+ */
+color: string | null, 
 /**
  * Unix time in milliseconds.
  */
@@ -400,6 +404,12 @@ lead?: NewLead, };
 
 export type CrewsRenameParams = { crewId: CrewId, name: string, };
 
+export type CrewsSetColorParams = { crewId: CrewId, 
+/**
+ * `#RRGGBB`; `null` clears the color.
+ */
+color: string | null, };
+
 export type CrewsSetPausedParams = { crewId: CrewId, paused: boolean, };
 
 export type CrewsSetWorkFolderParams = { crewId: CrewId, 
@@ -2144,6 +2154,7 @@ export interface RpcMethods {
   "crews.list": { params: undefined; result: Array<Crew> };
   "crews.create": { params: CrewsCreateParams; result: Crew };
   "crews.rename": { params: CrewsRenameParams; result: Crew };
+  "crews.setColor": { params: CrewsSetColorParams; result: Crew };
   "crews.setPaused": { params: CrewsSetPausedParams; result: Crew };
   "crews.setWorkFolder": { params: CrewsSetWorkFolderParams; result: Crew };
   "crews.setLead": { params: CrewsSetLeadParams; result: Crew };
diff --git a/crates/botloft-core/src/protocol/export.rs b/crates/botloft-core/src/protocol/export.rs
index f32d55c6..46b6505e 100644
--- a/crates/botloft-core/src/protocol/export.rs
+++ b/crates/botloft-core/src/protocol/export.rs
@@ -144,6 +144,7 @@ fn export_bindings() {
     out.decl::<SystemStatus>();
     out.decl::<CrewsCreateParams>();
     out.decl::<CrewsRenameParams>();
+    out.decl::<CrewsSetColorParams>();
     out.decl::<CrewsSetPausedParams>();
     out.decl::<CrewsSetWorkFolderParams>();
     out.decl::<NewLead>();
@@ -264,6 +265,11 @@ fn export_bindings() {
         &out.name::<CrewsRenameParams>(),
         &crew,
     );
+    out.method(
+        method::CREWS_SET_COLOR,
+        &out.name::<CrewsSetColorParams>(),
+        &crew,
+    );
     out.method(
         method::CREWS_SET_PAUSED,
         &out.name::<CrewsSetPausedParams>(),
diff --git a/crates/botloft-core/src/protocol/methods.rs b/crates/botloft-core/src/protocol/methods.rs
index b39cd1bd..f7434437 100644
--- a/crates/botloft-core/src/protocol/methods.rs
+++ b/crates/botloft-core/src/protocol/methods.rs
@@ -185,6 +185,15 @@ pub struct CrewsRenameParams {
     pub name: String,
 }
 
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+#[cfg_attr(test, derive(ts_rs::TS))]
+pub struct CrewsSetColorParams {
+    pub crew_id: CrewId,
+    /// `#RRGGBB`; `null` clears the color.
+    pub color: Option<String>,
+}
+
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase")]
 #[cfg_attr(test, derive(ts_rs::TS))]
diff --git a/crates/botloft-core/src/protocol/mod.rs b/crates/botloft-core/src/protocol/mod.rs
index ce86bddd..d0daf516 100644
--- a/crates/botloft-core/src/protocol/mod.rs
+++ b/crates/botloft-core/src/protocol/mod.rs
@@ -114,6 +114,7 @@ pub mod method {
     pub const CREWS_LIST: &str = "crews.list";
     pub const CREWS_CREATE: &str = "crews.create";
     pub const CREWS_RENAME: &str = "crews.rename";
+    pub const CREWS_SET_COLOR: &str = "crews.setColor";
     pub const CREWS_SET_PAUSED: &str = "crews.setPaused";
     pub const CREWS_SET_WORK_FOLDER: &str = "crews.setWorkFolder";
     pub const CREWS_SET_LEAD: &str = "crews.setLead";
diff --git a/crates/botloft-core/src/protocol/model.rs b/crates/botloft-core/src/protocol/model.rs
index ab71c457..2b55a37b 100644
--- a/crates/botloft-core/src/protocol/model.rs
+++ b/crates/botloft-core/src/protocol/model.rs
@@ -23,6 +23,8 @@ pub struct Crew {
     /// `null` when the crew has no chief.
     pub lead_bot_id: Option<BotId>,
     pub paused: bool,
+    /// Color `#RRGGBB` the owner gave the crew; `null` for none.
+    pub color: Option<String>,
     /// Unix time in milliseconds.
     pub created_at: i64,
     /// Unix time in milliseconds; `null` while the crew is active.
diff --git a/crates/botloft-store/migrations/0025_crew_color.sql b/crates/botloft-store/migrations/0025_crew_color.sql
new file mode 100644
index 00000000..2dc5fc56
--- /dev/null
+++ b/crates/botloft-store/migrations/0025_crew_color.sql
@@ -0,0 +1,2 @@
+-- A crew's color (spec 15.1): `#RRGGBB` the owner picked, NULL for none.
+ALTER TABLE crews ADD COLUMN color TEXT;
diff --git a/crates/botloft-store/src/bots/tests.rs b/crates/botloft-store/src/bots/tests.rs
index b3da9fc7..61e1e64e 100644
--- a/crates/botloft-store/src/bots/tests.rs
+++ b/crates/botloft-store/src/bots/tests.rs
@@ -13,6 +13,7 @@ fn setup() -> (Store, CrewId) {
         work_folder_chosen: false,
         lead_bot_id: None,
         paused: false,
+        color: None,
         created_at: 1,
         archived_at: None,
     };
diff --git a/crates/botloft-store/src/crews.rs b/crates/botloft-store/src/crews.rs
index 10954d04..7a1dab04 100644
--- a/crates/botloft-store/src/crews.rs
+++ b/crates/botloft-store/src/crews.rs
@@ -6,7 +6,8 @@ use rusqlite::{OptionalExtension, Row, params};
 
 use crate::{Result, Store, parse_column, unique_as_duplicate};
 
-const COLUMNS: &str = "id, name, slug, paused, created_at, archived_at, work_dir, lead_bot_id";
+const COLUMNS: &str =
+    "id, name, slug, paused, created_at, archived_at, work_dir, lead_bot_id, color";
 
 /// A crew without a chosen folder comes back with an empty `work_folder`;
 /// the daemon fills in the `shared` folder, which depends on its paths.
@@ -22,6 +23,7 @@ fn from_row(row: &Row<'_>) -> rusqlite::Result<Crew> {
             .get::<_, Option<String>>(7)?
             .and_then(|id| id.parse().ok()),
         paused: row.get(3)?,
+        color: row.get(8)?,
         created_at: row.get(4)?,
         archived_at: row.get(5)?,
     })
@@ -35,7 +37,9 @@ impl Store {
     pub fn insert_crew(&self, crew: &Crew) -> Result<()> {
         self.conn
             .execute(
-                &format!("INSERT INTO crews ({COLUMNS}) VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8)"),
+                &format!(
+                    "INSERT INTO crews ({COLUMNS}) VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9)"
+                ),
                 params![
                     crew.id.as_str(),
                     crew.name,
@@ -44,7 +48,8 @@ impl Store {
                     crew.created_at,
                     crew.archived_at,
                     work_dir(crew),
-                    crew.lead_bot_id.as_ref().map(|id| id.as_str())
+                    crew.lead_bot_id.as_ref().map(|id| id.as_str()),
+                    crew.color
                 ],
             )
             .map_err(|err| unique_as_duplicate(err, "crew slug"))?;
@@ -81,18 +86,19 @@ impl Store {
     }
 
     /// Saves the mutable fields: name, paused, archived_at, the chosen work
-    /// folder and the chief.
+    /// folder, the chief and the color.
     pub fn update_crew(&self, crew: &Crew) -> Result<()> {
         self.conn.execute(
             "UPDATE crews SET name = ?2, paused = ?3, archived_at = ?4, work_dir = ?5, \
-             lead_bot_id = ?6 WHERE id = ?1",
+             lead_bot_id = ?6, color = ?7 WHERE id = ?1",
             params![
                 crew.id.as_str(),
                 crew.name,
                 crew.paused,
                 crew.archived_at,
                 work_dir(crew),
-                crew.lead_bot_id.as_ref().map(|id| id.as_str())
+                crew.lead_bot_id.as_ref().map(|id| id.as_str()),
+                crew.color
             ],
         )?;
         Ok(())
@@ -128,6 +134,7 @@ mod tests {
             work_folder_chosen: false,
             lead_bot_id: None,
             paused: false,
+            color: None,
             created_at,
             archived_at: None,
         }
diff --git a/crates/botloft-store/src/lib.rs b/crates/botloft-store/src/lib.rs
index 6634d699..333e54db 100644
--- a/crates/botloft-store/src/lib.rs
+++ b/crates/botloft-store/src/lib.rs
@@ -176,6 +176,7 @@ pub(crate) mod tests {
                 work_folder_chosen: false,
                 lead_bot_id: None,
                 paused: false,
+                color: None,
                 created_at: 0,
                 archived_at: None,
             };
diff --git a/crates/botloft-store/src/migrate.rs b/crates/botloft-store/src/migrate.rs
index e88e0fde..e76e64de 100644
--- a/crates/botloft-store/src/migrate.rs
+++ b/crates/botloft-store/src/migrate.rs
@@ -31,6 +31,7 @@ const MIGRATIONS: &[(u32, &str)] = &[
     (22, include_str!("../migrations/0022_crew_access_files.sql")),
     (23, include_str!("../migrations/0023_plan_share.sql")),
     (24, include_str!("../migrations/0024_mcp_servers.sql")),
+    (25, include_str!("../migrations/0025_crew_color.sql")),
 ];
 
 /// Schema version after every migration has run.
diff --git a/crates/botloftd/src/rpc/dispatch.rs b/crates/botloftd/src/rpc/dispatch.rs
index 78af886d..9cb6da7b 100644
--- a/crates/botloftd/src/rpc/dispatch.rs
+++ b/crates/botloftd/src/rpc/dispatch.rs
@@ -30,6 +30,7 @@ pub fn dispatch(daemon: &Daemon, name: &str, params: Option<Value>) -> Result<Va
         method::CREWS_LIST => reply(crews::list(daemon)),
         method::CREWS_CREATE => reply(crews::create(daemon, parse(params)?)),
         method::CREWS_RENAME => reply(crews::rename(daemon, parse(params)?)),
+        method::CREWS_SET_COLOR => reply(crews::set_color(daemon, parse(params)?)),
         method::CREWS_SET_PAUSED => reply(crews::set_paused(daemon, parse(params)?)),
         method::CREWS_SET_WORK_FOLDER => reply(crews::set_work_folder(daemon, parse(params)?)),
         method::CREWS_SET_LEAD => reply(lead::set_lead(daemon, parse(params)?)),
diff --git a/crates/botloftd/src/service/crews.rs b/crates/botloftd/src/service/crews.rs
index 5f7aa56e..79d106d3 100644
--- a/crates/botloftd/src/service/crews.rs
+++ b/crates/botloftd/src/service/crews.rs
@@ -1,9 +1,10 @@
 //! `crews.*` operations.
 
+use botloft_core::avatar::normalize_color;
 use botloft_core::ids::CrewId;
 use botloft_core::protocol::{
-    Crew, CrewIdParams, CrewsCreateParams, CrewsRenameParams, CrewsSetPausedParams,
-    CrewsSetWorkFolderParams,
+    Crew, CrewIdParams, CrewsCreateParams, CrewsRenameParams, CrewsSetColorParams,
+    CrewsSetPausedParams, CrewsSetWorkFolderParams,
 };
 use botloft_core::{now_ms, slug, validate};
 use botloft_store::Store;
@@ -48,6 +49,7 @@ pub fn create(daemon: &Daemon, params: CrewsCreateParams) -> ApiResult<Crew> {
         work_folder: chosen.unwrap_or_default(),
         lead_bot_id: None,
         paused: false,
+        color: None,
         created_at: now_ms(),
         archived_at: None,
     };
@@ -82,6 +84,22 @@ pub fn rename(daemon: &Daemon, params: CrewsRenameParams) -> ApiResult<Crew> {
     Ok(changed(daemon, crew))
 }
 
+/// Gives the crew a color, or clears it.
+pub fn set_color(daemon: &Daemon, params: CrewsSetColorParams) -> ApiResult<Crew> {
+    let color = match params.color.as_deref() {
+        None => None,
+        Some(input) => Some(
+            normalize_color(input)
+                .ok_or_else(|| ApiError::validation("color must look like #RRGGBB"))?,
+        ),
+    };
+    let store = daemon.store();
+    let mut crew = active(&store, &params.crew_id)?;
+    crew.color = color;
+    store.update_crew(&crew)?;
+    Ok(changed(daemon, crew))
+}
+
 /// Moves the crew to another work folder, or back to `shared`. Each bot
 /// restarts to reach it once nothing is in progress (spec 7.4).
 pub fn set_work_folder(daemon: &Daemon, params: CrewsSetWorkFolderParams) -> ApiResult<Crew> {
diff --git a/crates/botloftd/src/workspace/files.rs b/crates/botloftd/src/workspace/files.rs
index ce3a01b3..9d51c361 100644
--- a/crates/botloftd/src/workspace/files.rs
+++ b/crates/botloftd/src/workspace/files.rs
@@ -295,6 +295,7 @@ mod tests {
             work_folder_chosen: false,
             lead_bot_id: None,
             paused: false,
+            color: None,
             created_at: 0,
             archived_at: None,
         };
diff --git a/crates/botloftd/src/workspace/folder.rs b/crates/botloftd/src/workspace/folder.rs
index 57f2e453..a6dd6355 100644
--- a/crates/botloftd/src/workspace/folder.rs
+++ b/crates/botloftd/src/workspace/folder.rs
@@ -146,6 +146,7 @@ mod tests {
             work_folder_chosen: work_folder.is_some(),
             lead_bot_id: None,
             paused: false,
+            color: None,
             created_at: 0,
             archived_at: None,
         }
diff --git a/crates/botloftd/src/workspace/mod.rs b/crates/botloftd/src/workspace/mod.rs
index ef4521e9..b609a63d 100644
--- a/crates/botloftd/src/workspace/mod.rs
+++ b/crates/botloftd/src/workspace/mod.rs
@@ -145,6 +145,7 @@ mod tests {
             work_folder_chosen: false,
             lead_bot_id: None,
             paused: false,
+            color: None,
             created_at: 0,
             archived_at: None,
         };
@@ -243,6 +244,7 @@ mod tests {
             work_folder_chosen: folder.is_some(),
             lead_bot_id: None,
             paused: false,
+            color: None,
             created_at: 0,
             archived_at: None,
         };
diff --git a/crates/botloftd/tests/rpc_crews_bots.rs b/crates/botloftd/tests/rpc_crews_bots.rs
index 8c17bf40..4f363ff2 100644
--- a/crates/botloftd/tests/rpc_crews_bots.rs
+++ b/crates/botloftd/tests/rpc_crews_bots.rs
@@ -127,6 +127,29 @@ async fn updates_refresh_the_rules_and_keep_the_bot_memory() {
     .expect("rename");
     assert!(read(ws.join(".claude/rules/botloft.md")).contains("crew **Docs Team**"));
 
+    let colored = app
+        .call(
+            "crews.setColor",
+            json!({ "crewId": crew["id"], "color": "#5ec8ff" }),
+        )
+        .await
+        .expect("color");
+    assert_eq!(colored["color"], "#5EC8FF");
+    app.call(
+        "crews.setColor",
+        json!({ "crewId": crew["id"], "color": "blue" }),
+    )
+    .await
+    .expect_err("not a hex color");
+    let cleared = app
+        .call(
+            "crews.setColor",
+            json!({ "crewId": crew["id"], "color": null }),
+        )
+        .await
+        .expect("clear");
+    assert_eq!(cleared["color"], serde_json::Value::Null);
+
     let paused = app
         .call(
             "bots.setPaused",
diff --git a/docs/spec.md b/docs/spec.md
index a0125a69..cb20ab62 100644
--- a/docs/spec.md
+++ b/docs/spec.md
@@ -682,6 +682,7 @@ Endpoint: `ws://127.0.0.1:45710/rpc`. Mensagens seguem JSON-RPC 2.0: requests co
 | `crews.list` | | `Crew[]` |
 | `crews.create` | `name, workFolder?, lead?` (`{name, role, instructions, model?}`: o chefe, 10.2) | `Crew` |
 | `crews.rename` | `crewId, name` | `Crew` |
+| `crews.setColor` | `crewId, color` (`#RRGGBB`, ou `null` para tirar) | `Crew`; a cor aparece como um ponto ao lado do nome na lista de equipes |
 | `crews.setPaused` | `crewId, paused` | `Crew` |
 | `crews.setLead` | `crewId, botId` (ou `null`, sem chefe) | `Crew`; o chefe antigo e o novo reiniciam quando nada estiver em andamento (10.2) |
 | `crews.setWorkFolder` | `crewId, workFolder` (caminho, ou `null` para voltar à `shared\`) | `Crew`; os bots reiniciam na pasta nova quando nada estiver em andamento (5) |
@@ -752,7 +753,7 @@ Pragmas: `journal_mode=WAL`, `synchronous=NORMAL`, `foreign_keys=ON`, `busy_time
 
 | Tabela | Colunas principais |
 |---|---|
-| `crews` | `id, name, slug, paused, work_dir, lead_bot_id, created_at, archived_at` (`work_dir` é a pasta escolhida; `NULL` usa a `shared`. `lead_bot_id` é o chefe, sem chave estrangeira: ele é gravado junto com a crew) |
+| `crews` | `id, name, slug, paused, work_dir, lead_bot_id, color, created_at, archived_at` (`work_dir` é a pasta escolhida; `NULL` usa a `shared`. `lead_bot_id` é o chefe, sem chave estrangeira: ele é gravado junto com a crew. `color` é o `#RRGGBB` que o dono escolheu, `NULL` sem cor) |
 | `bots` | `id, crew_id, name, handle, slug, role, instructions, color, paused, permission_mode, model, model_in_use, effort, effort_default, token_hash, session_id, created_at, archived_at` (`effort_default` é o nível do próprio modelo, como o Claude Code disse: `low` a `max`, `none` ou `NULL`, 7.4) |
 | `messages` | `id, crew_id, from_kind (owner/bot/system), from_bot_id, to_bot_id, kind (note/task/result/system), body, task_id, created_at`; `reply_item_id` e `reply_text` quando o dono respondeu a algo do chat (9.3; sem chave estrangeira, porque os itens saem antes das messages na exclusão, 7.6) |
 | `attachments` | `id, message_id, name, media_type, size, path, created_at` |