ResearchOS/Wiki

PI (Principal Investigator)

A PI is a per-user role. It is an account flagged with account_type === 'lab_head' that gains a small superset of affordances over a regular member. PI is not a separate user pool, it is a property on a normal account. One or more lab members fill this role. The role unlocks the Lab Overview surface, the Approvals queue, the People page, the audit trail, the announcement composer, and the user-archiving controls.

The PI is pinned to the top of the user picker and carries a small role badge.

What a PI actually is

The role is a single flag on a user's metadata. That flag is account_type, with values "member" (the default) or "lab_head". A lab folder can have one or more accounts flagged as PI, and co-PI labs set the flag on every PI. A PI is otherwise a normal account, with their own projects, tasks, and notes. The role does not replace any of that. It adds a layer of cross-lab affordances on top.

PI-only surfaces

A lab head has access to several surfaces that are not visible to members.

  • Lab Overview at /lab-overview. The PI's landing page. Includes the What needs you hero (amber count tiles for pending approvals, flagged records, overdue tasks, and @-mentions), the lab stat strip, the announcement composer, the lab activity feed, and the People snapshot. See Lab Overview.
  • Approvals at /approvals. A unified queue of pending purchase approvals and flagged records. Accessible from the Lab Overview hero tiles or directly by URL. PI-only; a non-PI loading this URL is redirected home.
  • People at /people. The full lab roster with workload, IDP, and member management. The People snapshot on the Lab Overview links here.
  • Browse lab experiments and Browse lab notes. Cross-lab views of every member's experiments and notes. See Browse lab experiments and Browse lab notes.
  • Audit trail. Opened from the Audit trail button on the Lab Overview header. Shows per-field edit history across member records. See Audit log.

The six phases of the PI feature

The PI role shipped in six tracked phases, with a capability revamp that landed in June 2026.

  1. Account type and comment attribution. Introduced account_type, the picker badge, and the "posted by PI" styling on comment rows.
  2. Comment threading and @-mentions. Built out the comment surface across tasks, notes, and purchases, with one-level threading and the denormalized mentions index. See Comments.
  3. Soft-write actions. Purchase approval, task assignment, and flag-for-review affordances. See Soft-write actions.
  4. Cross-lab metrics. Member workload, recent activity, burn rate. The data feeds the Lab Overview page.
  5. Audit log. Every soft-write field change appends to _pi_audit.json. The per-record confirm dialog (no password, no timer) replaced an older password gate in June 2026. See Edit as lab head and Audit log.
  6. User archiving. Remove a former member from active views while preserving their data. See User archiving.

Picker badge and sort-to-top

On the user picker, the PI shows up with a small badge and is pinned to the top of the list regardless of which account is set as the main user. This makes it easy to find the PI account on a shared lab laptop. The badge is also visible on comment rows so members can tell when feedback is coming from the PI versus another member.

When to use it

Set one account as the PI in these cases.

  • Your lab has more than two or three people and you want a single person triaging purchases instead of everyone approving their own.
  • You need a forensic trail of who approved what and who changed which field on which record.
  • You want the curated Lab Overview with the What needs you hero, the stat strip, and the People snapshot instead of only your own home page.

Skip the PI (every account stays "member") in these cases.

  • The lab is a single person, or two people who trust each other to manage their own purchases.
  • You do not need the audit log or the approval queue.

Where to go next