Skip to content

Workspaces & chats

A workspace is a folder on disk Hive treats as the scope of all its work. It carries a name, a permission policy, a set of vaults and skills, a list of members and devices, and an event log.

A chat is a session inside a workspace — one conversation thread with one or more agents.

The model

Account ──── Device ──── Hive instance
                              │
                              └── Workspace (folder on disk)
                                     │
                                     ├── Chat (conversation thread)
                                     ├── Chat
                                     │
                                     ├── Members (humans + agents)
                                     ├── Vaults (knowledge bases)
                                     ├── Skills (auto-loaded prompts)
                                     ├── MCP servers (tool servers)
                                     └── Event log (.hive/...)
  • Account — a human (Alice). Stable identity, persists across devices.
  • Device — a single machine (Alice's MacBook). Has its own Ed25519 signing key that lives in Keychain.
  • Hive instance — the running app + its config.
  • Workspace — a folder; one workspace per hive.config.toml.
  • Chat — a conversation; many per workspace.

The event log

Inside every workspace folder lives a .hive/ subdirectory with:

.hive/
├── workspace.json              # workspace metadata
├── workspaces/<id>/
│   ├── events.ndjson           # signed envelope log
│   └── quarantine.ndjson       # rejected envelopes (sig failure)
└── sessions/
    └── <session-id>/
        ├── events.ndjson       # per-session event log (projector input)
        └── snapshot.json       # latest projected session state

Every meaningful state change — chat title rename, member add, tool call, approval — becomes an event. Events get wrapped in a signed envelope (Ed25519 from your device key) and appended to the workspace log. The session projector replays events to compute current state.

flowchart LR
    Mut[User or agent mutation] --> Delta[sessionDeltaEvents]
    Delta --> Sign[Sign envelope<br/>Ed25519]
    Sign --> Disk[.hive/.../events.ndjson]
    Sign --> P2P[Broadcast over peer-link]
    P2P --> Peer[Peer's ingestRemoteEnvelopes]
    Disk --> Proj[SessionProjector]
    Peer --> Proj
    Proj --> UI[Live UI state]

Why event-sourced?

Three reasons:

  1. Sync. Two peers can independently mutate state, then exchange envelopes, and the projector replays them to converge.
  2. Audit. The log is the source of truth. Anyone with the workspace can replay history.
  3. Verification. Signatures travel with envelopes; receiving peers verify against the writer's device public key.

Workspace identity

The workspace's identity is its UUID + name + members + device roster. The UUID is rolled at first launch and never changes. The name + member list are mutable state in the event log.

Membership has two layers:

  • The WorkspaceMember list (denormalized for UI, projected from events).
  • The DeviceIdentity list (which device key belongs to which member).

The two together let the authz layer answer: "did the device that signed this envelope have permission to do that?"

Multiple workspaces

You can have many workspaces. The sidebar shows the currently selected workspace's metadata at the top, with a chevron next to the name. Swap workspaces from File → Open Workspace (⌘O); an in-sidebar quick switcher is on the roadmap.

Permissions scope

Three values:

  • Always ask — default. Every tool call that writes prompts the user.
  • Chat — approve once per chat; future calls of the same kind run inline.
  • Workspace — approve once per workspace; spans every chat in that workspace.

The trust scope lives on the workspace; individual chats can tighten but not loosen it.

Vaults & skills

  • Vaults are local knowledge bases (folders or Obsidian libraries) the runtime can search and reference.
  • Skills are auto-loaded prompt fragments that frame a chat (e.g. "you're a Swift code reviewer, prefer terse explanations").

Both are configured via [[vaults]] and [[skills]] blocks in hive.config.toml. The Settings sheet has tabs for both — Vaults gets full CRUD plus per-source refresh; Skills exposes an autoload toggle. (A full Skills editor is on the roadmap; for now hand-edit the TOML to add new entries.)