TeamBrain and work-view collaboration
TeamBrain and My Work turn local agent records into shared team context and a reviewable work surface. TeamBrain helps agents and teammates use consented project knowledge. My Work helps a person see requests, progress, evidence, products, focus, and decisions without treating recorded activity as proof that work is live or correct.
Collaboration model
The system keeps local records, optional shared My Work state, and optional TeamBrain knowledge as separate concerns. Local records supply the work view. Shared My Work carries selected review and planning facts across devices. TeamBrain shares selected project knowledge with a team.
flowchart LR
A[Agent sessions and work-state updates] --> B[Local work record]
B --> C[My Work review view]
C --> D[Owner decisions and handoff]
B --> E{Owner sharing choice}
E -->|selected projects| F[TeamBrain knowledge]
F --> G[Agent brief and team search]
F --> H[Team board]
C --> I{Shared My Work enabled}
I --> J[Portable review and focus state]
J --> C
Local work view
The local work view is a projection of recorded activity on the current computer. It groups activity below confirmed human requests and keeps uncertain or unattributed work visible without turning it into a guessed request. A person can inspect the request, its source records, its products, its progress, and its next step before making a review decision.
My Work presents the same model through several views:
- The home view puts requests that need the owner first and supports cards, a list, and grouped work.
- The agent view shows recorded agents, their requests, and linked subagents. Unrecorded agents and idle agents remain visible.
- The team view groups requests by person so overlapping work is easier to spot.
- Focus views group requests under owner-controlled areas,
Other, orNot sorted yet. - My Rules shows learned preferences and owner decisions separately from request records.
- Past focus shows finished areas and earlier goal periods without claiming that a closed period was completed.
The view reads compact request summaries first and loads full request detail when a person opens a request. It also reports source health and live-feed freshness separately, so an old but valid snapshot is not mistaken for a current update. Local pages can continue an eligible Claude Code or Codex conversation; cloud and sample sources cannot run a local agent command.
Recorded lifecycle status, review status, and live activity remain different signals. done and dropped close a work item. A quiet agent is not finished, and a stop record does not prove that its result is correct.
References: src/…/App.tsx• L144-159 src/…/my-work.tsx• L51-73 src/…/work-data-source.ts• L13-60 src/…/to-work-model.ts• L348-484 src/…/work-state-status.mjs• L1-8
Shared TeamBrain
TeamBrain is an optional shared intelligence layer for project work. A member joins through an invitation and chooses whether to share no projects, selected projects, or all projects including future projects. That choice limits what teammates and TeamBrain-assisted agents can use.
Agents can receive a short project brief at session start and can use read-only team search for shared observations, plans, and decisions. My Work can show a team board that helps people find overlap, missing context, and handoffs. TeamBrain does not assign work, send replies, or publish private local review notes.
See TeamBrain workflows for the command and API paths.
References: src/…/teambrain.ts• L90-98 src/…/teambrain.ts• L358-399 src/…/context.ts• L49-89 src/…/TeamBrainRoutes.ts• L27-70 src/…/my-work.tsx• L51-57
Shared My Work state
Shared My Work is an optional cross-device record for portable work-view facts. It can carry request grouping, focus placement, progress review, products, generated display copy, and owner decisions. It does not make local paths, raw tool bodies, or private machine details into shared data.
Stable source identities let another device connect shared facts to its own evidence when that evidence exists. Complete updates replace logical records as one unit. Incomplete or invalid updates keep the last complete state. Conflicting owner decisions stay visible until a person resolves them. Local JSON files are compatibility views of the durable shared record, not the authority for a new decision.
Shared My Work is not TeamBrain. TeamBrain is team project knowledge controlled by membership scope. Shared My Work is personal review and planning state used across devices.
References: src/…/shared-records.mjs• L1-18 src/…/shared-ledger-adapter.mjs• L51-106 src/…/shared-ledger-adapter.mjs• L354-464 src/…/shared-projection.mjs• L417-497 src/…/SharedWorkSync.ts• L16-67
TeamBrain assistance
TeamBrain connects the installation's cloud-sync identity to a team service. The local command and worker proxy provide the agent-facing boundary while the account that owns sync remains the identity for membership and sharing.
Membership and sharing
Joining pairs the device in a browser and saves the team connection only after the account and team are confirmed. The join flow refuses to replace an existing sync account. After joining, the member can change the project scope or leave. Leaving removes the work shared with that team while local records remain on the computer.
References: src/…/teambrain.ts• L160-179 src/…/teambrain.ts• L544-641 src/…/teambrain.ts• L697-753
Agent assistance
At session start, the TeamBrain brief runs beside normal memory context. The result is marked as shared information and has a bounded place in the context budget. If TeamBrain is not configured or cannot answer, normal local context still works.
During a session, team_brief gives a focused project view and team_search finds shared knowledge. Both are read-only. The local worker signs the requests with the approved connection and returns bounded text to the agent.
References: src/…/context.ts• L49-89 src/…/context.ts• L160-168 src/…/TeamBrainRoutes.ts• L27-47 src/…/mcp-server.ts• L766-797
Shared board
The TeamBrain board shows consent-filtered shared lists, tasks, and findings for a selected team. It helps a person see possible overlap and handoffs without presenting old records as live presence or creating automatic assignments.
The local panel checks membership and board data through the worker. While visible, it refreshes the board and keeps the last valid result while a new read is pending. It shows connection age or errors so stale shared data is clear. The My Work team view adds a person-centered view of shared requests.
References: src/…/teambrain.ts• L154-185 src/…/TeamBrainRoutes.ts• L42-70 src/…/team-view.js• L27-181 src/…/my-work.tsx• L51-57
Human work review
Human review separates an agent's recorded result from the owner's decision to inspect it. The request drawer brings together the request, progress, source records, products, conversations, focus placement, and review action. The owner can copy a handoff or continue an eligible local conversation, but the system does not send a handoff automatically.
Request projection
The request projection uses a substantive human request as the top-level unit. It groups linked conversations, work, products, and evidence below that request. Clear links can be made from conversation and project information. Uncertain links remain visible as suggestions or unlinked work instead of being assigned by guesswork.
New conversations can first pass through code-proven links and an optional decision service. A strong match joins an existing request. A middle-confidence match becomes an owner suggestion. A weak match starts its own request, while an unavailable or refused decision falls back to the normal grouping review.
The projection keeps lifecycle state, progress review, source records, and later request updates together. Generated titles and summaries make cards easier to read, but they do not establish identity, completion, or approval. Human copy uses bounded source records and validated output. It cannot add a blocker, deadline, approval, presence claim, or completion claim that the evidence does not support. If generated copy is missing or old, the recorded request remains visible.
References: src/…/request-groups.mjs• L148-179 src/…/request-groups.mjs• L1023-1063 src/…/request-judge.mjs• L92-103 src/…/request-judge.mjs• L199-220 src/…/human-copy.mjs• L46-128 src/…/session-project.mjs• L14-29 src/…/to-work-model.ts• L348-484
Request detail
Request detail is an inspectable view of the work behind a card. It exposes recent activity, evidence, conversations, workstreams, products, images, progress history, and the focus area. Detail reads use a revision that covers the displayed detail fields, so a newer model causes the drawer to read again rather than silently showing an older view.
The view treats missing values as missing. It does not invent a title, next step, date, agent, or source record. It also keeps owner words and private evidence out of a hosted focus page while retaining them for local review.
References: src/…/overview.ts• L18-35 src/…/overview.ts• L48-104 src/…/request-detail.tsx• L1-40 src/…/request-detail-state.ts• L28-58
Review state
Checking a result records that a local user reviewed one exact version. The review is separate from agent completion, source work, and shared memory. It does not ship the work or change the recorded result.
Before saving, the worker compares the request fingerprint from the browser with the current request. A changed request or a request without explicit completion rejects the check. When Shared My Work is enabled, the review can sync only after the receiving view has complete evidence. Different decisions remain visible as a conflict until a person reads the current evidence and chooses one.
References: src/…/review-store.ts• L6-13 src/…/shared-reviews.mjs• L55-77 src/…/shared-review-value.mjs• L1-16 src/…/WorkViewRoutes.ts• L1191-1209 src/…/request-detail.tsx• L186-260
Work products
Work products are inspectable artifacts linked to the event that named them. The view can show pages, pull requests, deployments, commits, branches, supported files, and images. A product is evidence connected to a request, not a completion claim.
The work view removes duplicates and limits local-file access to the recorded file while it exists and has a supported type. On another device, a local product can remain origin-only metadata rather than pretending that the file is available there.
References: src/…/work-product.mjs• L1-4 src/…/work-product.mjs• L334-404 src/…/to-work-model.ts• L40-55 src/…/deliverable-list.tsx• L1-174
Agent activity
The agent view shows recorded activity and lifecycle evidence. It can show a main agent with its subagents when the recorded session link is unambiguous. A subagent is working, quiet, or finished from recorded status; silence does not mean finished. The owner can record a finish for an otherwise unconfirmed subagent.
The Team and By agent views keep requests with no known agent visible. They also keep idle agents visible, so the screen does not hide a lack of recorded work behind an incomplete grouping.
References: src/…/to-work-model.ts• L240-313 src/…/agent-board.ts• L7-53 src/…/my-work.tsx• L636-710 src/…/agent-lifecycle.mjs• L1-50
Owner rules
My Rules gives the owner a durable place to review preferences learned from work and rules written directly by the owner. A rule has scope, strength, source evidence, status, and change history. Suggested rules stay out of agent guidance until the owner approves them.
Approved or owner-written rules become agent guidance. The generated MY-RULES.md file is rebuilt from the saved rule record, so the record remains authoritative when sync changes the rule. If shared evidence is incomplete, the view keeps the known quote count and says that some quotes are omitted.
References: src/…/my-rules.d.mts• L1-17 src/…/my-rules.mjs• L69-187 src/…/my-rules.tsx• L112-160 src/…/my-rules.tsx• L500-560
Focus areas
Focus areas give the owner a durable way to group requests by the work they support. Area identity is separate from its name, so renaming an area does not move its requests. Requests are placed by the request's stable anchor conversation.
Owner choices have priority over system suggestions. The system may suggest an area or placement, and a high-confidence focus decision may place a request automatically, but it does not override a kept, renamed, merged, dismissed, or finished area. Requests with no suitable area remain in Other or Not sorted yet. Work-state rows replay in original write order so the same owner decision remains stable across devices.
The current work view puts owner attention first in focus overviews. Cards expose working and attention signals, next steps, and supporting evidence. Finished areas retain the day they entered the done state, which lets Past focus show when an area ended without claiming that its requests were all correct or shipped.
References: src/…/focus-done-date.mjs• L1-10 src/…/my-focus.mjs• L43-71 src/…/my-focus.mjs• L164-266 src/…/refresh-task.ts• L812-879 src/…/focus-overview.ts• L24-72 src/…/focus-overview.css• L1-33 src/…/to-focus-model.ts• L1-90
Focus history
Past focus shows finished areas and earlier goal periods as history. A finished area keeps its requests and its done date. Closing a goal period records what the owner asked for during that period; it does not mark those asks complete.
References: src/…/past-focus.tsx• L1-145 src/…/to-work-model.ts• L487-539
Shared focus pages
A shared focus page is a hosted view of one kept or done focus area. The worker builds the page from the current local work view and sends it with the cloud-sync identity. The browser never receives that credential, and the worker can update the page while My Work is closed.
The page contains the area's goal, progress, open requests, and next steps. It removes prompts, quotes, evidence links, products, conversations, private repeated titles, and machine names. Anyone with the link can read it. Signed-in people and hosted agents can comment. Moving a request out of the area removes it from later publishes. Stopping the share disables the link for everyone, and sharing again creates a new link.
The worker sends only changed page content. Per-area operations are serialized so a late publish cannot revive a stopped link. My Work refreshes comment counts and drops a count when it cannot verify that the value is current.
See Hosted viewer service for hosted page access and comment controls.
References: src/…/to-shared-focus.ts• L1-19 src/…/to-shared-focus.ts• L126-173 src/…/focus-share.ts• L50-127 src/…/focus-shares.ts• L117-195 src/…/focus-share-publisher.ts• L1-79
Request progress and refresh
Refresh turns recorded conversations into an updated work view. It can route new conversations, review progress, update the build story, link work to goals, name requests, and place requests in focus areas. Each step uses bounded input and validates its result before saving it.
The refresh runs only when work is due. It can use deterministic links and optional decision services before asking an agent to resolve uncertain work. A failed, interrupted, or agent-less step records a bounded state instead of false success. The owner can choose the refresh agent, model settings, and language. One refresh runs at a time. Scheduled checks back off after failure and repair an abandoned running state after restart, while an on-demand refresh stays distinct. During scheduled checks, optional work-state labeling runs in the background and does not block the refresh agent.
The build story gives My Work a short recap and dated chapters from the last progress run. It summarizes recorded work and learned rules; it does not replace request evidence or create a completion state.
flowchart LR
A[Recorded prompts and activity] --> B{Work due?}
B -->|no| C[Keep current work view]
B -->|yes| D[Route and review with bounded agent help]
D --> E[Validate groups goals progress and focus]
E --> F[Save work view and build story]
F --> G[Human inspection and decision]
References: src/…/auto-refresh-worker.mjs• L1-9 src/…/auto-refresh-worker.mjs• L107-169 src/…/refresh-task.ts• L693-727 src/…/refresh-task.ts• L729-785 src/…/refresh-task.ts• L812-879 src/…/refresh-task.ts• L881-961 src/…/build-story.ts• L1-101 src/…/my-work.tsx• L185-230
Hosted setup extraction
Hosted setup can use one consented cloud extraction to create an initial owner map, goals, request groups, and learned preferences from imported owner prompts. Before the scan, setup lets the owner choose agents and integrations and select optional skills and memory preferences. The owner selects which histories to scan and whether prompt text may leave the computer. Skipping upload keeps those prompts local.
The result is shown before it is saved. An unavailable, oversized, or interrupted run explains what stayed local. A pending save can resume without repeating the same hosted run. The saved groups, goals, and rules still follow the same evidence and owner-review limits as later refreshes.
References: src/…/hosted-intent.ts• L18-75 src/…/hosted-intent.ts• L168-235 src/…/hosted-intent.ts• L318-400 src/…/install-screen.tsx• L21-55 src/…/install-screen.tsx• L57-149 src/…/setup.css• L194-251 src/…/setup.css• L256-319
Live update view
The local work view reads a saved overview and receives model changes through a local event stream. HTTP read success and live-feed freshness are separate signals. The page can therefore say whether its source is healthy, reconnecting, or stale.
The browser keeps the newest live model while detail reads and saves are in flight. A late response cannot roll the page back to an older request. When a newer event arrives during a save, the page reads again while keeping the save receipt. Reconnected conversation rows reread their full state because a notice may have been missed.
References: src/…/overview.ts• L81-104 src/…/WorkViewRoutes.ts• L541-553 src/…/WorkViewRoutes.ts• L1211-1273 src/…/local-source.ts• L508-656 src/…/work-slice.ts• L53-105
Related systems
Capture creates the observations and session records used by the work projection. Context delivery adds the TeamBrain brief beside normal memory context. Local worker routes define the browser and agent boundaries. Persistence and sync determine which facts can move between devices or leave the computer.
- TeamBrain workflows explains TeamBrain command and API workflows.
- Work-view experience explains request cards, detail review, focus, and live status.
- Hosted viewer service explains hosted pages and their access controls.
Change checklist
When these files or sections are changed, remember to consider these:
- Keep TeamBrain project scope consistent across join, membership, brief, search, and board paths.
- Keep the TeamBrain account boundary separate from the installation's sync identity.
- Keep the TeamBrain brief within the session-start context budget and keep service failure non-blocking.
- Keep TeamBrain, Shared My Work, local review, and hosted focus pages as separate privacy and audience contracts.
- Keep shared logical records keyed by stable source identity. Do not use local paths, row numbers, or machine URLs as cross-device identity.
- Keep shared batches atomic and preserve the last complete projection when a batch is invalid or incomplete.
- Keep generated copy, progress labels, and focus suggestions derived from source records. They must not create status, completion, identity, or owner decisions.
- Keep request grouping and focus placement tied to confirmed requests and stable anchor conversations. Keep uncertain results visible to the owner.
- Keep decision-service confidence bands and fallback behavior aligned with owner review. A failed or oversized decision must not silently drop a conversation.
- Keep owner focus choices stronger than system suggestions. Preserve
Other,Not sorted yet, dismissed areas, merged areas, and done dates as distinct states. - Keep overview revisions and detail revisions compatible. A detail read or save must not replace a newer live model.
- Keep review fingerprints tied to source content and require complete evidence for shared review.
- Keep agent activity, stop evidence, lifecycle status, and review status separate.
- Keep local products available only when their recorded file is still safe to serve. Mark origin-only products on other devices.
- Keep refresh results validated by the same contracts used by manual grouping, progress, goal, rule, title, and focus actions.
- Keep refresh scheduling, abandoned-run repair, failure backoff, and setup pause distinct from the refresh result.
- Keep hosted setup consent, upload limits, pending saves, and cooldown state separate from later local refreshes.
- Keep shared focus pages redacted and compatible across the publisher, local share controls, and hosted viewer.
- Keep share and comment requests behind the worker boundary. A stopped link must not return through a late publish.
- Keep live-feed freshness separate from HTTP source health and from recorded agent freshness.
- Keep conversation continuation local, limited to one running turn per conversation, and separate from hosted or sample sources.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| The member joins with a different sync account | TeamBrain could use the wrong local identity | Join refuses account switching before saving the connection. |
| A member shares the wrong project scope | Teammates or agents can see unintended project knowledge | Membership stores an explicit selected-project or all-projects scope. |
| TeamBrain cannot answer | The agent or board has no fresh shared context | Brief and search fail within bounds while local work remains available. |
| A decision service cannot place a conversation | New work could be lost or silently assigned | The conversation falls back to grouping or stays visible as an owner suggestion. |
| A shared My Work batch is incomplete | A device could show partial grouping, focus, or review state | The durable record keeps the last complete value. |
| A request changes after the owner reads it | The owner could check an older result | The review route compares the content fingerprint and rejects stale checks. |
| Shared evidence is missing on the receiving device | A review could claim that unseen work was checked | Shared review stays unavailable until evidence is complete. |
| A generated title or summary is stale | The card could describe an earlier request | Copy is bounded and fingerprinted, and the recorded request remains available. |
| Work has no confirmed human request | An observation could appear as a misleading request | The projection keeps it unlinked or presents a visible grouping suggestion. |
| A quiet agent is treated as finished | The view could claim that work ended without evidence | Finished requires a recorded stop, a returned foreground call, or an owner action. |
| A local product is missing or unsafe | The view could expose a bad link or unsupported file | Products are tied to source records and local files are served only while safe. |
| A refresh answer is invalid or interrupted | Partial focus, goal, progress, or story data could mislead the owner | Each step uses bounded input, structured output, and validation before save. |
| The refresh process stops while a run is marked active | My Work could show a run that never ends | Startup repairs an unowned running state and scheduled checks retry it. |
| Repeated scheduled refreshes fail | The same agent could be asked again too often | Failure backoff grows to a bounded wait and resets after success. |
| Work-state labeling fails | Labels could be incomplete or delayed | Labeling is independent, logged, and retried on a later check. |
| Work-state rows arrive in a different order on two devices | Owner focus choices could change after sync | The reducer replays rows in original write order and device order. |
| A focus area is dismissed, merged, or done | A later system pass could place work in an invalid area | Placement accepts only a live placeable area or Other. |
| A hosted focus share is stopped during publish | A late response could revive the link | Per-area publish and stop operations are serialized; re-sharing creates a new link. |
| A hosted page includes owner words or evidence | Private prompts or source links could leave the computer | The shared projection removes private fields and repeats. |
| The live stream is stale while HTTP still works | Old activity could look current | The UI reports stream freshness separately from source health. |
Key files
| File | Why to read it |
|---|---|
| src/…/teambrain.ts | Defines TeamBrain connection, brief, search, board, and failure contracts. |
| src/…/teambrain.ts | Shows the member flow for joining, sharing, checking, and leaving. |
| src/…/context.ts | Shows how the optional TeamBrain brief joins session context. |
| src/…/TeamBrainRoutes.ts | Shows the local proxy boundary for TeamBrain operations. |
| src/…/data-source.mjs | Defines the source used to build a current work snapshot. |
| src/…/request-groups.mjs | Shows how conversations become request groups, titles, reviews, and focus inputs. |
| src/…/request-judge.mjs | Shows how code links and optional decision checks route new conversations. |
| src/…/human-copy.mjs | Defines the evidence limits for generated request and workstream copy. |
| src/…/my-focus.mjs | Defines owner focus areas, placements, replay order, and owner precedence. |
| src/…/refresh-task.ts | Shows refresh scheduling, agent choice, validation, and saved outcomes. |
| src/…/auto-refresh-worker.mjs | Shows due checks, single-run control, failure backoff, and restart repair. |
| src/…/shared-projection.mjs | Shows which work-view facts can become portable across devices. |
| src/…/shared-ledger-adapter.mjs | Shows durable shared records, local compatibility files, recovery, and conflict handling. |
| src/…/review-store.ts | Defines exact-version local review decisions. |
| src/…/work-product.mjs | Shows how inspectable artifacts are linked and served safely. |
| src/…/focus-share.ts | Defines hosted focus-link lifecycle, comments, credentials, and stop behavior. |
| src/…/focus-share-publisher.ts | Shows background publication of current focus pages. |
| src/…/hosted-intent.ts | Defines consented hosted setup extraction and replayable saving. |
| src/…/overview.ts | Builds compact overview and full-detail responses with revisions. |
| src/…/App.tsx | Shows the My Work shell, source loading, navigation, and review surfaces. |
| src/…/my-work.tsx | Shows request, focus, agent, team, and build-story views. |
| src/…/request-detail.tsx | Shows evidence, products, review, grouping, focus, and continuation actions. |
| src/…/my-rules.tsx | Shows owner rule review and approval. |
| src/…/to-work-model.ts | Maps recorded snapshots into the shared work model without inventing values. |
| src/…/to-shared-focus.ts | Redacts and maps a focus area into a hosted page. |
| src/…/focus-shares.ts | Shows local share state, comment counts, and link freshness. |
| src/…/work-data-source.ts | Defines the common boundary for local, cloud, and sample work sources. |