Work Buddy

https://docs.work-buddy.ai
Admin
Work Buddy is a personal agent framework built on Claude Code and MCP that orchestrates tasks,...
Tokens:119,948
Snippets:1,694
Trust Score:2.1
Update:5 months ago
Show doc for...
Tokens:
Raw
### Setup Wizard: Guided Mode

Source: https://docs.work-buddy.ai/handbook/status_setup-wizard-directions

Initiate the 'guided' mode for first-time setup. This mode walks the user through bootstrap, feature selection, requirements, and health checks.

```python
mcp__work-buddy__wb_run("setup_wizard", {"mode": "guided"})
```

--------------------------------

### Run Setup Wizard

Source: https://docs.work-buddy.ai/handbook/status_setup-wizard-directions

Use this command to initiate the setup wizard. Specify the desired mode and any necessary arguments.

```python
mcp__work-buddy__wb_run("setup_wizard", {"mode": "<mode>", ...})
```

--------------------------------

### Setup Wizard: Status Mode

Source: https://docs.work-buddy.ai/handbook/status_setup-wizard-directions

Run the setup wizard in 'status' mode for a quick overview of bootstrap requirements and component health. This is the default mode if none is specified.

```python
mcp__work-buddy__wb_run("setup_wizard", {"mode": "status"})
```

--------------------------------

### Install LM Studio CLI on Windows

Source: https://docs.work-buddy.ai/handbook/features_lmstudio-offload-setup

Installs LM Studio using winget and instructs on how to enable the CLI for terminal use.

```powershell
winget install LMStudio.LMStudio
# Open LM Studio once → System tab → "Install CLI" so `lms` is on PATH.

```

--------------------------------

### Setup Wizard: Diagnose Mode

Source: https://docs.work-buddy.ai/handbook/status_setup-wizard-directions

Run the setup wizard in 'diagnose' mode for targeted troubleshooting of a specific component. This mode combines requirements, health checks, and diagnostic sequences.

```python
wb_run("setup_wizard", {"mode": "diagnose", "component": "hindsight"})
```

--------------------------------

### Start LM Studio Local Server

Source: https://docs.work-buddy.ai/handbook/features_lmstudio-offload-setup

Start the LM Studio local server. The default port is 1234. Use `curl` to verify that the server is running and listing models.

```bash
lms server start          # default port 1234
curl http://127.0.0.1:1234/v1/models
```

--------------------------------

### Setup Wizard: View Preferences

Source: https://docs.work-buddy.ai/handbook/status_setup-wizard-directions

View current feature preferences using the 'preferences' mode without any 'updates'. This displays the current configuration of components.

```python
wb_run("setup_wizard", {"mode": "preferences"})
```

--------------------------------

### Install LM Studio CLI on macOS

Source: https://docs.work-buddy.ai/handbook/features_lmstudio-offload-setup

Installs LM Studio using Homebrew and guides on enabling the CLI for terminal operations.

```bash
brew install --cask lm-studio
# Open LM Studio once → System tab → "Install CLI" so `lms` is on PATH.

```

--------------------------------

### Day Planner Entry Format Example

Source: https://docs.work-buddy.ai/handbook/obsidian_day-planner

Example of how to format entries in the Day Planner section of a note. Timestamps are in 24-hour HH:mm format, and tasks snap to 10-minute intervals.

```markdown
- [ ] 09:00 - 10:30 Deep work: ECG-FM paper writing
- [ ] 10:30 - 10:45 Break
- [ ] 10:45 - 11:30 [Cal] Lab meeting

```

--------------------------------

### Setup Wizard: Save Preferences

Source: https://docs.work-buddy.ai/handbook/status_setup-wizard-directions

Save user preferences for features using the 'preferences' mode with the 'updates' argument. This allows enabling or disabling specific components.

```python
wb_run("setup_wizard", {"mode": "preferences", "updates": {"hindsight": {"wanted": false}}})
```

--------------------------------

### Configure LLM Tiers in YAML

Source: https://docs.work-buddy.ai/handbook/architecture_llm-runner

Example configuration for binding LLM tiers to specific backends and models in `config.yaml`. This setup determines which concrete LLM endpoint the runner will use based on the requested tier.

```yaml
llm:
  tiers:
    frontier_balanced:
      backend: anthropic
      model: claude-sonnet-4-6
      defaults: {max_tokens: 4096}
    local_tool_calling:
      backend: lmstudio_native
      profile: local_agent
      defaults: {max_tokens: 4096}
```

--------------------------------

### Format Focused Tasks

Source: https://docs.work-buddy.ai/handbook/morning_morning-routine

Example structure for focused tasks, including optional duration and a specific start time. Tasks can use 'description' or 'text' for their label.

```json
[{"description": "MIT 1: Ship LLM-judge eval", "duration": 90},
 {"description": "MIT 2: Draft paper contract", "duration": 30, "time_start": "14:00"}]
```

--------------------------------

### Setup Wizard: Update Preferences

Source: https://docs.work-buddy.ai/handbook/status_setup-wizard-directions

Update feature preferences using the 'preferences' mode with the 'updates' argument. This allows modifying settings like 'wanted' status and 'reason' for components.

```python
wb_run("setup_wizard", {"mode": "preferences", "updates": {"telegram": {"wanted": false, "reason": "..."}, "hindsight": {"wanted": true}}})
```

--------------------------------

### Start Development Orientation Workflow

Source: https://docs.work-buddy.ai/handbook/dev_dev-mode

Initiates the development orientation process. This is a mandatory first step before making any code modifications to ensure proper understanding of the existing architecture and code.

```python
`mcp__work-buddy__wb_run("dev-orient")`

```

--------------------------------

### Running Python Commands in Work Buddy

Source: https://docs.work-buddy.ai/handbook/dev_plugin-integration

Example command to activate the 'work-buddy' conda environment and execute a command within the project directory.

```powershell
powershell.exe -Command "cd <vault-root>\repos\work-buddy; conda activate work-buddy; <command>"

```

--------------------------------

### Return Complete Routing Record

Source: https://docs.work-buddy.ai/handbook/routing_route-information

Example of the final JSON output summarizing all routing actions taken, categorized by 'routed', 'deleted', 'split', and 'skipped' items, including relevant details for each.

```json
{
  "routed": [{"id": "t_7b2e09", "action": "route", "destination": "tasks/master-task-list.md"}],
  "deleted": [{"id": "t_c44d1a", "reason": "Already completed"}],
  "split": [{"id": "t_d44f12", "splits": [...]}],
  "skipped": [{"id": "t_x9y8z7", "reason": "User wants to think about it"}]
}
```

--------------------------------

### Example User Interaction for Cluster Review

Source: https://docs.work-buddy.ai/handbook/routing_route-information

Illustrates how items are presented to the user for confirmation, correction, or skipping. Includes item ID, raw text, agent interpretation, proposed action, and confidence level.

```markdown
## Admin items (3 items)

**[t_d44f12]** "Admin - VPN/taxes/new laptop stuff"
â†’ Proposed: task (inbox) â€” "Set up VPN, handle tax prep, research laptops"
â†’ Confidence: low â€” this bundles 3 things, and taxes may be done
What is this? Confirm / correct / skip?

**[t_c44d1a]** "Taxes - Varsha"
â†’ Proposed: task (inbox) â€” "Tax-related task involving Varsha"
â†’ Confidence: low â€” don't know who Varsha is or what the task is
What is this? Confirm / correct / skip?

**[t_7b2e09]** "Varsha - T4 / T4A"
â†’ Proposed: linked to t_c44d1a? â€” "Tax form from Varsha"
â†’ Confidence: low
What is this? Confirm / correct / skip?

```

--------------------------------

### Download GGUF Model using Hugging Face CLI

Source: https://docs.work-buddy.ai/handbook/features_lmstudio-offload-setup

Downloads a GGUF model to a temporary cache directory using `huggingface-cli` as a fallback if `lms get` fails, requiring manual import afterward.

```bash
pip install huggingface_hub    # if not already installed
huggingface-cli download yixuan-chia/snowflake-arctic-embed-m-v1.5-Q8_0-GGUF \
    --local-dir /tmp/gguf-cache

```

--------------------------------

### Format Calendar Events (Flat)

Source: https://docs.work-buddy.ai/handbook/morning_morning-routine

Example of a flat structure for calendar events, suitable for manual construction. 'start' and 'end' can be 'HH:MM' or ISO datetime. 'summary', 'description', or 'text' can be used for the event label.

```json
[{"start": "13:00", "end": "13:30", "summary": "Team sync"}]
```

--------------------------------

### Verify LM Studio CLI Installation

Source: https://docs.work-buddy.ai/handbook/features_lmstudio-offload-setup

Checks if the LM Studio CLI (`lms`) is installed and accessible by verifying its version.

```bash
lms --version   # should print a version string, no errors

```

--------------------------------

### Spawn Help Session

Source: https://docs.work-buddy.ai/handbook/architecture_control-graph

Initiates a help session for a specific node in the control graph.

```APIDOC
## POST /api/control/help/<node_id>

### Description
Spawns a help session for the specified node ID. This typically involves creating a structured brief for a support agent.

### Method
POST

### Endpoint
`/api/control/help/<node_id>`

### Parameters
#### Path Parameters
- **node_id** (string) - Required - The ID of the node for which to spawn a help session.
```

--------------------------------

### Datacore Get Page

Source: https://docs.work-buddy.ai/handbook/context_datacore_get_page

Get a single vault page by path with Datacore metadata: frontmatter, sections, tags, links, timestamps.

```APIDOC
## GET /datacore/get_page

### Description
Retrieves a single vault page by its path, including Datacore metadata such as frontmatter, sections, tags, links, and timestamps.

### Method
GET

### Endpoint
/datacore/get_page

### Parameters
#### Query Parameters
- **path** (str) - Required - Vault-relative path (e.g. 'journal/2026-04-09.md')
- **fields** (str) - Optional - Comma-separated fields to retrieve. Defaults to all fields.

### Response
#### Success Response (200)
- **frontmatter** (object) - The frontmatter of the page.
- **sections** (array) - An array of sections within the page.
- **tags** (array) - An array of tags associated with the page.
- **links** (array) - An array of links found in the page.
- **timestamps** (object) - Timestamps related to the page (e.g., created, modified).

### Requirements
- obsidian
- datacore
```

--------------------------------

### Run Morning Routine

Source: https://docs.work-buddy.ai/handbook/morning_directions

Initiates the morning routine workflow. Load morning configuration before proceeding with individual steps.

```python
from work_buddy.morning import get_morning_config, is_phase_enabled, resolve_phases
cfg = get_morning_config()
# For each step, check is_phase_enabled(step_id, cfg). If disabled, advance immediately with {skipped: true}.
```

--------------------------------

### Task Creation Parameters

Source: https://docs.work-buddy.ai/handbook/tasks_task-new

Illustrates how to construct parameters for the task_create function using the final plan. It dynamically includes optional fields from the plan.

```python
final_plan = <confirm.final_plan>
params = {"task_text": final_plan["task_text"]}
for k in ("urgency", "project", "due_date", "contract", "summary", "tags"):
    if final_plan.get(k) is not None:
        params[k] = final_plan[k]
result = `mcp__work-buddy__wb_run("task_create", params)`

```

--------------------------------

### Create Task with Handoff Prompt

Source: https://docs.work-buddy.ai/handbook/tasks_handoff-directions

Use this command to create a task with a concise summary and a full handoff prompt. The summary parameter triggers the creation of a note file.

```shell
mcp__work-buddy__wb_run("task_create", {"task_text": "<concise summary>", "summary": "<full handoff prompt>"})
```

--------------------------------

### Python Start Messaging Bridge

Source: https://docs.work-buddy.ai/handbook/architecture_event-bus

Starts a daemon process that polls a messaging service for events and republishes them onto the in-process event bus. This bridges communication between different processes.

```python
dashboard.messaging_bridge.start_messaging_bridge(...)

```

--------------------------------

### Stage Precisely with Git

Source: https://docs.work-buddy.ai/handbook/dev_dev-commit

Avoid using `git add -A` or `git add .`. Use `git add <file1> <file2>` when you own the entire file's diff. For files with mixed hunks, use `git add -p <file>` and selectively accept your changes.

```bash
git add <file1> <file2>
```

```bash
git add -p <file>
```

--------------------------------

### Get Thread

Source: https://docs.work-buddy.ai/handbook/messaging_get_thread

Retrieves all messages in a specified conversation thread.

```APIDOC
## Get Thread

### Description
Get all messages in a conversation thread.

### Method
GET

### Endpoint
/messaging/threads/{thread_id}

### Parameters
#### Path Parameters
- **thread_id** (str) - Required - The unique identifier for the thread.
```

--------------------------------

### Background Registry Warm-Start

Source: https://docs.work-buddy.ai/handbook/architecture_mcp-import-discipline

The `main_http()` function initiates a daemon thread to pre-fetch the registry upon server bind. This improves initial request latency by ensuring the registry is ready.

```python
main_http()
```

--------------------------------

### Get Project

Source: https://docs.work-buddy.ai/handbook/projects_project_get

Retrieves a single project by its unique slug, along with its recent observations.

```APIDOC
## Project Get

### Description
Get a single project with its recent observations (identity + state + trajectory).

### Method
GET

### Endpoint
/projects/{slug}

### Parameters
#### Path Parameters
- **slug** (str) - Required - Project slug (e.g. 'my-project')

### Response
#### Success Response (200)
- **id** (str) - The unique identifier of the project.
- **name** (str) - The name of the project.
- **slug** (str) - The slug of the project.
- **observations** (list) - A list of recent observations for the project.
  - **id** (str) - The unique identifier of the observation.
  - **state** (str) - The state of the observation.
  - **trajectory** (str) - The trajectory of the observation.
```

--------------------------------

### Get Task Briefing

Source: https://docs.work-buddy.ai/handbook/morning_morning-routine

Retrieves the current task status. This is a direct call to the 'task_briefing' function.

```python
`mcp__work-buddy__wb_run("task_briefing")`
```

--------------------------------

### Define a SourceDescriptor

Source: https://docs.work-buddy.ai/handbook/triage_source-descriptors

Example of a SourceDescriptor for a journal thread, specifying its name, TTL, quarantine triggers, and configuration.

```python
SourceDescriptor(
    name="journal_thread",
    ttl_days=5,
    quarantine_triggers=[
        "source_removed",
        "source_edited_beyond_match",
    ],
    config={
        "edit_match_threshold": 0.85,
    },
)

```

--------------------------------

### Set Step Visibility to Summary with Included Keys

Source: https://docs.work-buddy.ai/handbook/architecture_workflows

Configure a step to return a summary of results inline, including only specified keys. Full results are still available on demand.

```json
"visibility": {"mode": "summary", "include_keys": ["total", "items"]}

```

--------------------------------

### Get Activity Timeline

Source: https://docs.work-buddy.ai/handbook/journal_activity_timeline

Retrieves a structured timeline of recent activity. You can specify a time range and optionally include deeper signals.

```APIDOC
## Get Activity Timeline

### Description
Infer recent activity from journal entries and optionally deeper signals. Returns a structured timeline with events, gaps, and relative timestamps. Use for understanding what happened during a time window.

### MCP Name
`activity_timeline`

### Category
`journal`

### Parameters
#### Query Parameters
- **deep** (bool) - Optional - Also collect git/chat/vault signals (default: false)
- **since** (str) - Required - ISO datetime or relative shorthand (e.g. '2h', '1d', '30m')
- **target_date** (str) - Optional - Journal date YYYY-MM-DD (default: inferred from since)
- **until** (str) - Optional - ISO datetime. Default: now.

### Requirements
- obsidian
```

--------------------------------

### Python EventBus Start Heartbeat

Source: https://docs.work-buddy.ai/handbook/architecture_event-bus

Initiates a background task to periodically publish heartbeat events. This is useful for monitoring the bus's liveness.

```python
events.start_heartbeat(interval, bus)

```

--------------------------------

### Run Full Blindspot Detection Workflow

Source: https://docs.work-buddy.ai/handbook/metacognition_blindspot-directions

Executes the complete workflow for detecting blindspots, encompassing context gathering and pattern analysis.

```shell
`mcp__work-buddy__wb_run("detect-blindspots")`
```

--------------------------------

### Execute Datacore Query with Raw Syntax

Source: https://docs.work-buddy.ai/handbook/obsidian_datacore-query-directions

Direct method for querying Datacore using raw Datacore syntax. Use this for simpler queries or when a structured plan is not necessary.

```python
mcp__work-buddy__wb_run("datacore_query", "@page/project-alpha-notes < childof tag/project/alpha")
```

--------------------------------

### Initialize MCP Gateway Session

Source: https://docs.work-buddy.ai/handbook/operations_mcp-gateway

This is the mandatory first call for every agent session. It registers your session with the MCP server for activity tracking. If `wb_init` is not in your tool list, use `wb_run` to call it.

```bash
`mcp__work-buddy__wb_init(session_id="<your WORK_BUDDY_SESSION_ID>")`
```

```bash
`mcp__work-buddy__wb_run(capability="wb_init", params={"session_id": "<your WORK_BUDDY_SESSION_ID>"})`
```

--------------------------------

### Get Rate Limit Observations

Source: https://docs.work-buddy.ai/handbook/services_dashboard_costs

Retrieves the most recent per-model rate-limit observations, including RPM, ITPM, and OTPM headroom, for display in the toolbar chip.

```APIDOC
## GET /api/costs/rate-limits

### Description
Fetches the most recent per-model rate-limit observations (RPM, ITPM, OTPM headroom) for the toolbar chip.

### Method
GET

### Endpoint
/api/costs/rate-limits
```

--------------------------------

### Direct Lookup in System Docs

Source: https://docs.work-buddy.ai/handbook/operations_mcp-gateway

Use `agent_docs` with a `path` and `depth` to retrieve full documentation for a specific item.

```javascript
`mcp__work-buddy__wb_run("agent_docs", {"path": "morning/directions", "depth": "full"})`
```

--------------------------------

### Run Python Command in Work Buddy

Source: https://docs.work-buddy.ai/handbook/dev_dev-mode

Execute Python commands within the Work Buddy environment. This example is specific to Windows with conda activation.

```powershell
powershell.exe -Command "cd <vault-root>\repos\work-buddy; conda activate work-buddy; <command>"
```

--------------------------------

### Declarative Open Action Configuration

Source: https://docs.work-buddy.ai/handbook/triage_card-actions

Defines a per-source 'open in app' affordance within the SourceDescriptor.config. This includes the button label, the MCP capability to dispatch, a mapping of item properties to capability arguments, and optional error kinds for auto-quarantine.

```json
{
    "open_action": {
        "label": "Open in Thunderbird",
        "capability": "email_display",
        "param_map": {
            "provider_message_id": "metadata.provider_message_id",
            "folder_path":         "metadata.folder_path",
        },
        "quarantine_on_error_kinds": ["email_message_not_found"],
    }

}
```
Tokens:
Raw