Configure Teambook Desktop

Local project and Workspace link

Initialize project-scoped configuration and link the current local project to a Workspace project whose shared resources should be available in desktop.

Important behavior

• Workspace authentication is managed separately in the desktop app.
• Linking resolves only projects visible to the connected user and rejects ambiguous names.
• Unlinking removes only the local association; it never deletes resources.

Models and credentials

Install self-contained model definitions, connect a local ChatGPT subscription, choose global or project defaults, and store provider credentials in the operating system credential service.

Portable model source

[provider]
name = "Acme AI"
api_base_url = "https://api.acme.example/v1"
client_type = "openai_responses"
api_key_env = "ACME_API_KEY"

[model]
name = "Acme Agent"
external_id = "agent-v1"
provider = "acme"

[[model.capabilities]]
name = "tools"
label = "Include tools"
type = "boolean"
default = { value = false }

Important behavior

• ChatGPT subscription login is available on macOS. Its credential remains in Keychain, and logout does not remove installed model definitions.
• The first model in a scope becomes its default. Later additions and updates require --default to change the default.
• Deleting the active default requires --replacement naming another model already installed in the same scope.
• client_type, when set, must be openai_responses, openai_codex_responses, openai_chat, anthropic, or gemini.
• Capabilities are optional. Each capability that is present requires name, label, and type; enum capabilities also require string options.
• Model deletion never deletes stored credentials, and secret values never enter TOML, JSON config, or notebook files.

Prompts

Create reusable system prompts that appear in the desktop prompt picker.

Prompt source

[prompt]
id = "brief"
name = "Brief"
content = "Summarize the request and recommend the next action."

Important behavior

• Prompt content is literal; environment-reference syntax is not expanded.
• Hosted share levels are intentionally not accepted because desktop prompt configuration stays local and is never synced to Workspace.
• Prompt ids and names share one case-insensitive namespace within a scope. Add and update reject collisions unless --force atomically replaces the conflicting local prompt.
• A project prompt shadows a global or Workspace prompt with the same identity.

Subagents

Define reusable worker roles with optional model overrides and execution options.

Subagent source

[subagent]
id = "reviewer"
name = "Reviewer"
description = "Reviews a proposed change"
model = "acme/agent-v1"
system_prompt = "Review carefully and report actionable findings."

[subagent.options]
temperature = 0.1

Important behavior

• The model override is optional; when omitted, the worker uses the notebook's selected model.
• Prompt templates and structured fields belong to smart cells, not subagent definitions.
• Subagent ids and names share one case-insensitive namespace within a scope. Add and update reject collisions unless --force atomically replaces the conflicting local subagent.
• Project definitions shadow global and Workspace definitions with the same id or name.

Agent Skills

Install complete Agent Skills directories containing SKILL.md plus optional scripts, references, and assets.

SKILL.md inside a matching directory

---
name: review-helper
description: Review a proposed change using the team checklist
license: MIT
---

Read `references/checklist.md`, inspect the proposed change, and report actionable findings.

Important behavior

• The directory name must match the lowercase hyphenated name in SKILL.md.
• Install and update copy the complete directory atomically and reject symlinks.
• Built-in skills are read-only; project skills shadow global and built-in skills by name.

Renderers

Install trusted web-component modules that render structured notebook responses.

Local renderer source

[renderer]
key = "orgchart"
label = "Org Chart"
content_type = "application/vnd.acme.orgchart+json"
custom_element_tag = "acme-orgchart"
custom_classes = "orgchart"

[renderer.script]
path = "./orgchart.js"

Important behavior

• Renderer modules execute code. Install only sources you trust.
• content_type is required. When accepts is omitted, the renderer accepts that content type exactly.
• A remote script requires an HTTPS url and SRI hash. Project renderers may instead use an HTTPS manifest with name, tag, and sha256.
• Local script paths resolve relative to the TOML source and are stored as absolute paths.
• Built-in renderer keys are immutable, and project renderers cannot replace global renderer keys.

MCP servers

Configure local or remote MCP servers, connect OAuth servers, inspect their tools, and explicitly choose which tools runs may use.

Important behavior

• Servers live in global config.json, connection state lives in mcp_state.json beside it, and tokens live only in the operating system credential service.
• Remote servers expose no tools until you explicitly allow them.
• Restart the desktop app after MCP configuration changes.