BiBrain User Guide
BiBrain narrows team collaboration down to a single spine: team → goal → tasks. AI steps in at exactly three points — it decomposes a goal for you, it does one task for you, and it builds team boards for you; the rest of the UI only exists to let you "see" and "confirm". Every team asset lives in the team's own git repository, so you can clone it down and look any time.
Reading order
The guide goes from shallow to deep in four tiers: Tier 1 takes five minutes, Tiers 2 and 3 are looked up as needed, and Tier 4 is for troubleshooting and customization.
- Tier 1 · Get it running (this page): what it is, up and running in five minutes, UI map
- Tier 2 · Day-to-day use: team home, goals & tasks, sessions, shared space, source control, team review, team settings
- Tier 3 · Once you know it: layouts and the command palette, keyboard shortcuts, sync and conflicts, decomposition, the state machine, advanced sessions, prompts and profiles, sub-repositories, across teams
- Tier 4 · Under the hood: where the truth lives, repository directory conventions, task-graph.json, which machine holds what
- Appendix: troubleshooting quick reference, what this version cannot do, glossary
What it is
Three minutes to build the mental model. The four facts in this section will save you 80% of the confusion later on.
One spine
A team → sets a goal → AI decomposes the goal into tasks → a person or AI executes the tasks → output lands in the shared space → you step back and look at team review
Every link in that chain maps to one icon in the activity bar on the left. When you cannot find a feature, first ask yourself "which link of this spine does it belong to".
Four things to know
1 · Everything about a team lives in one git repository
Task structure, task status, documents, artifacts, conversation archives, boards — they are all files in this repository. There is no black-box database: you can git clone it and open it with any editor. The client keeps one working copy on your machine (default ~/.sdw/shared-team/<team id>).
2 · AI only writes files; you decide whether it gets committed
When the Agent decomposes a goal, executes a task or generates a board, the output is always an uncommitted change in the working copy. You review it, then commit and push it yourself. AI never commits on your behalf — that is a hard constraint, not a setting.
3 · BiBrain is a separate window
It and the main AIKO window are two windows with two different UIs. Login state and model configuration come from the main window, but everything about team collaboration happens in the BiBrain window. The old "Team" UI in the main window has nothing to do with it.
4 · The UI is shaped like VS Code
Far left is the activity bar (switches which view you are in), next to it the sidebar (the navigation tree of that view), and on the right the editor area (draggable, splittable, closable tabs). If you can use VS Code you can use this; if you cannot, no problem — the UI map section below has the full map.
Entry point
Click the B icon in the top bar of the main AIKO window to open the BiBrain window. If you do not see that icon, go to Settings → Labs and turn on "New BiBrain". A green dot on the B icon means the BiBrain window is running.
Up and running in five minutes
From zero to "AI just finished my first task". Every step says where it lives in the UI.
Get into BiBrain
Top bar of the main AIKO window → the B icon. The first time it opens a new window; after that, clicking it just switches over.
Pick a team or create one
At the very top of the sidebar is the team switcher. If you have already been added to a team, just pick one; otherwise there are two paths:
- Build it with AI (recommended) — say what you want to do in one sentence, and it looks through the organization directory and recommends people by role and current load, filling the form on the right in real time. You can change anything at any moment.
- Fill in the form yourself — team name, visibility, collaboration mode, members and roles.
If you get someone else's invite link, paste it on the team management page to join (links come in two flavours: "join directly" and "approval required").
Once the team is created, the server automatically opens a git repository for it and puts in the working procedures (skills) the AI will use.
Wait for the working copy to connect
After you enter a team, the client automatically clones the team repository onto your machine. The sync button on the right of the top bar shows progress. The first clone can take a while; until it is connected the file tree in the shared space is empty, and that is normal.
To change the directory: Team settings → Baseline capabilities → Git repository.
Set a goal
Activity bar Goals & tasks → the "Goal browser" tab at the top → new goal. Write clearly what you want to achieve and by when.
Let AI decompose the goal into tasks
Click "Decompose" on the goal to enter the goal decomposition session: chat with AI on the left, watch the task graph it produces appear on the right in real time (DAG / Raw JSON views plus evolution history).
- Too fine or too coarse → adjust the decomposition granularity slider and run another round
- Too many or too few links between tasks → adjust dependency density
- Want to change a task's title, deliverable or estimate → edit the form on the right directly; AI reads it in the next round
The decomposition result is an uncommitted file in your working copy. Once you are happy with it, click "Confirm and commit" to commit + push it to the whole team.
Assign and move things along
Switch to the "Task browser" tab: the board lets you drag cards to change status, the list is for scanning in bulk, and the relationship graph shows how far along the dependency chain has got.
Only the assignee can move their own tasks; a task with no assignee has to be assigned first. You can still drag while offline — changes are recorded locally first and synced automatically once the network is back.
Let AI do one task
Click "Execute" on a task card to enter the task execution session: conversation on the left, and on the right a live list of the files it produced and what the upstream dependencies delivered.
The Agent can look through the material already in the team shared space on its own, so you do not have to paste the context again. When it reports the work as done, the task moves to "In review" and is handed over to the goal owner — it does not go straight to "Done". Signing off is always a human action.
Commit to the team
Activity bar Source control: all changes are listed on the left, review the diffs one by one, tick the ones you want to commit, write a commit message, then ⌘/Ctrl+Enter to commit and push.
Or use the Sync button in the top bar to run "Sync changes" in one click (preview → pull and merge → push).
See how the team is running
Team home: period overview, goal progress, status distribution, member load, team activity, historical archive.
Team review: tell the AI what you want to see and it generates a self-contained HTML board, stores it in the team repository, and once published the whole team can open it.
UI map
One table covers every entry point. The activity bar is the only first-level navigation — click an icon and the content type of the sidebar changes entirely.
The four parts of the window
| Area | What it holds | Key behaviour |
|---|---|---|
| Top bar | Search box · sync button · + New · notifications · avatar | Pressing Enter in search jumps to the goal centre; the sync button is a split button (left half executes, right half ▾ switches mode); the avatar menu has "My workbench / My profile / Team management / Back to AIKO" |
| Activity bar (narrow strip, far left) | 7 view icons | Clicking an already active icon = collapse the sidebar; icons can be reordered by dragging and hidden by right-clicking (team settings is pinned to the bottom and can be neither dragged nor hidden) |
| Sidebar | Team switcher → + New conversation → navigation tree of the current view → user card | Resizable by dragging; each group can be collapsed, and collapsed state survives a restart |
| Editor area | Draggable tabs (files, diffs, sessions, terminal…) | Drag to dock, split, close; the layout is preserved across restarts |
The seven views
| Icon | View | What the sidebar gives you / what the main area gives you |
|---|---|---|
| ⌂ | Team home dashboard | Sidebar: my work (assigned to me / created by me / delivered by me / all teams), quick access Main area: period overview, goal list, status distribution, member load, delivery cadence, team activity, historical archive |
| ◎ | Goals & tasks work | Sidebar: goal tree (expand to see tasks) Main area, 4 tabs: Goal browser / Task browser / My tasks / Member distribution |
| 💬 | Sessions chat | Sidebar: session history tree (type → object → member → session) Main area: session tabs, several can be open at once |
| 🗂 | Shared space space | Sidebar: file tree (with ⌘/Ctrl+P quick search) Main area, 9 tabs: Overview / Requirements / Docs / Goals & tasks / Session records / Artifacts / AI assets / Sync records / Changes |
| ⑂ | Source control git | Sidebar, three groups: source control (commit box + grouped change list), sub-repositories, commit graph Main area: repository overview (branches, ahead/behind, conflicts, recent commits, sync mode) |
| ▤ | Team review review | Sidebar: board library (mine / by member) Main area: board card wall plus the built-in "Team operations overview"; the board preview panel sits on the right |
| ⚙ | Team settings settings | Sidebar: settings section tree Main area, 5 tabs: Baseline capabilities / Scenario plugins / Profile / Member profiles / Prompts |
Remember this
Shared space is "look at files"; Source control is "changes and commits". Both views read the same working copy, but the change list can only be acted on in source control — deliberately not duplicated in two places.