Skip to content
Guida

Workspaces

A workspace is Guida’s file-backed project and configuration boundary. Opening one unlocks persistent storage (g.store), work queues (g.queue), full-text search (g.search), event triggers, custom MCP tools, extractor catalogs, semantic pipelines, and operational configuration.

Opening a Workspace

Section titled “Opening a Workspace”

Use File > Open Workspace or the toolbar button to select a folder. Guida will create the default structure if it doesn’t exist.

Folder Structure

Section titled “Folder Structure”
my-workspace/
├── scripts/          # Your automation scripts (*.js, *.lua, *.janet)
├── lib/              # Shared libraries for JS, Lua, and Janet
├── views/            # Queue view configurations
├── events.json       # Event trigger config
├── tools.json        # Custom MCP tool definitions
├── queues.json       # Worker pool definitions
├── domains.json      # Domain whitelist for MCP
├── workflows/        # Named operational scopes (optional)
├── extractors.json   # Extractor catalog root (optional)
├── extractors/       # Included extractor descriptors (optional)
├── pipelines.json    # Semantic pipeline catalog root (optional)
├── pipelines/        # Pipeline templates and authored/generated rules (optional)
├── store.db          # Persistent storage (auto-created)
├── queue.db          # Work queue data (auto-created)
├── workflow-ledger.db # Workflow run/item history (auto-created)
└── search-index/     # Full-text search index (auto-created)

The Workspace pane in Guida automatically lists all .js, .lua, and .janet files found in the scripts/, lib/, and workflow folders. When creating a new file, use the extension for the engine you want.

Database Files

Section titled “Database Files”

These are created automatically when you first use the corresponding API:

  • store.db — LiteDB database for g.store.* operations. Documents organized in named collections.
  • queue.db — SQLite database for StratQueue-backed g.queue.* operations. Supports priority queues, custom dequeue strategies, checked-out work, and dead-letter queues.
  • workflow-ledger.db — SQLite database for workflow runs, items, events, artifacts, leases, retries, and recovery history.
  • search-index/ — Lucene.NET index directory for g.search.* operations.

All data is workspace-local and travels with the folder.

These concepts have different jobs:

  • A workflow folder activates a named set of triggers, workers, tools, and views.
  • An extractor declares one reusable data acquisition contract.
  • A semantic pipeline connects contracted stages, validation, mapping, and destinations.
  • workflow-operations.json describes the operator map used by the Workflow Control Console; workflow-map.json links systems, pipelines, and modules.

They share the workspace boundary, but one is not an alias for another.

Use File > Backup Workspace… to create a timestamped archive of the whole workspace, or File > Backup Managed Workspace Files… to archive only Guida-managed state such as store.db, queue/ledger snapshots, and search-index/. See Workspace Backups.

Configuration Files

Section titled “Configuration Files”

events.json — Event Triggers

Section titled “events.json — Event Triggers”

Auto-run scripts when browser events occur:

{
  "triggers": [
    {
      "event": "url-match",
      "pattern": "https://example.com/products/*",
      "script": "scripts/extract-product.js"
    },
    {
      "event": "page-loaded",
      "script": "scripts/inject-styles.js"
    },
    {
      "event": "tab-created",
      "script": "scripts/setup-tab.js"
    }
  ]
}

Trigger types:

EventPatternFires when
url-matchGlob pattern (* = any chars)Navigation completes to a matching URL
page-loaded—Any page finishes loading
tab-created—A new tab is created
tab-closed—A tab is closed
tab-activated—A tab becomes active
dom-mutationCSS selector(s)A watched DOM element changes (text, attributes, or children)
external-queue—A poll script returns data (configurable interval)

If the same script is already running, it won’t be triggered again.

dom-mutation — reactive DOM observation using MutationObserver. Ideal for live data like stock prices, betting odds, or dashboard metrics:

{
  "event": "dom-mutation",
  "selector": ".price-display",
  "script": "scripts/on-price-change.js",
  "debounce": 1000,
  "strategy": "exhaust"
}
  • selector — CSS selector to observe (or selectors for an array of selectors)
  • attributes — optional list of specific attribute names to watch
  • debounce — milliseconds to debounce per element (default: 0)
  • strategy — backpressure strategy: "exhaust" (default — skip if script running), "buffer" (collect changes into an array), "sample" (keep only the latest change)

external-queue — poll an external data source at a configurable interval:

{
  "event": "external-queue",
  "source": "scripts/poll-api.js",
  "script": "scripts/handle-item.js",
  "interval": 30
}

The source script runs on each poll — return data if work is available, or null if empty. When data is returned, the script handler runs and can access it via g.trigger.getContext().

Trigger context — all trigger scripts can call g.trigger.getContext() to access event metadata (event type, tab ID, URL, timestamp, and trigger-specific fields like mutation details).

tools.json — Custom MCP Tools

Section titled “tools.json — Custom MCP Tools”

Define tools that external AI agents can invoke. See Custom Tools.

queues.json — Worker Pools

Section titled “queues.json — Worker Pools”

Define declarative worker pools for batch processing. See Queue Workers.

domains.json — Domain Whitelist

Section titled “domains.json — Domain Whitelist”

Control which domains the MCP server can navigate to. See MCP Integration.

{
  "allowedDomains": [
    "example.com",
    "*.example.com",
    "trusted-site.org"
  ]
}

Workspace-Scoped Services

Section titled “Workspace-Scoped Services”

These APIs require an open workspace and will return an error otherwise:

APIDescription
g.store.*Persistent document storage
g.queue.*Transactional work queues
g.search.*Full-text search index
g.workers.*Queue worker pools
g.workflows.*Workflow inspection and switching

Core APIs like g.dom.click, g.nav.navigateToUrl, and g.tabs.getTabs work without a workspace.

Next Steps

Section titled “Next Steps”