DenchClaw

The Bridge SDK is automatically injected into every app's HTML via the window.dench object. It provides various namespaces to interact with the platform, databases, agents, and UI. All methods return Promises and have a 30-second timeout. Accessing these namespaces requires specific permissions defined in your app manifest.

| Namespace         | Permission                    | Methods                                                                                              | Details In        |
| ----------------- | ----------------------------- | ---------------------------------------------------------------------------------------------------- | ----------------- |
| `dench.db`        | `database` / `database:write` | `query(sql)`, `execute(sql)`                                                                         | **data-builder**  |
| `dench.objects`   | `objects`                     | `list()`, `get()`, `create()`, `update()`, `delete()`, `bulkDelete()`, `getSchema()`, `getOptions()` | **data-builder**  |
| `dench.files`     | `files` / `files:write`       | `read()`, `list()`, `write()`, `delete()`, `mkdir()`                                                 | below             |
| `dench.app`       | _(none)_                      | `getManifest()`, `getTheme()`                                                                        | below             |
| `dench.chat`      | `agent`                       | `createSession()`, `send()`, `getHistory()`, `getSessions()`, `abort()`, `isActive()`                | **agent-builder** |
| `dench.agent`     | `agent`                       | `send(message)`                                                                                      | **agent-builder** |
| `dench.tool`      | `agent`                       | `register(name, handler)`                                                                            | **agent-builder** |
| `dench.memory`    | `agent`                       | `get()`                                                                                              | **agent-builder** |
| `dench.ui`        | `ui`                          | `toast()`, `navigate()`, `openEntry()`, `setTitle()`, `confirm()`, `prompt()`                        | **platform-api**  |
| `dench.store`      | `store`                       | `get()`, `set()`, `delete()`, `list()`, `clear()`                                                     | **platform-api**  |
| `dench.http`      | `http`                        | `fetch(url, opts)`                                                                                    | **platform-api**  |
| `dench.events`    | `events`                      | `on(channel, cb)`, `off(channel)`                                                                     | **platform-api**  |
| `dench.context`   | _(none)_                      | `getWorkspace()`, `getAppInfo()`                                                                      | **platform-api**  |
| `dench.apps`      | `apps`                        | `send()`, `on()`, `list()`                                                                           | **platform-api**  |
| `dench.cron`      | `cron`                        | `schedule()`, `list()`, `run()`, `cancel()`                                                           | **platform-api**  |
| `dench.webhooks`  | `webhooks`                    | `register()`, `on()`, `poll()`                                                                       | **platform-api**  |
| `dench.clipboard` | `clipboard`                   | `read()`, `write()`                                                                                  | **platform-api**  |

In DenchClaw, you must use the Dench Integrations tools to interact with connected applications (Gmail, Slack, GitHub, etc.). The standard workflow is to search for the appropriate tool first, inspect its schema and guidance, and then execute it.

Recommended Workflow

1. Search: Use composio_search_tools to find the tool. This is the source of truth for input_schema, connection status, recommended_plan_steps, and known_pitfalls.
2. Inspect: Review the returned input_schema to ensure arguments match the required types, enums, and structures.
3. Execute: Call the tool using composio_call_tool.

Note: composio_resolve_tool is available as a compatibility wrapper for single best-match results, but ranked search via composio_search_tools is the preferred path.

Prohibited Methods

Do not attempt to bypass the integration layer using:

• gog or shell CLIs for the specific app.
• curl or raw gateway HTTP calls.
• Direct provider REST calls.

When building CRM structures, follow these standard field and relationship patterns to ensure data integrity and connectivity across the system:

Contact/Customer

• Fields: Full Name (text, required), Email Address (email, required), Phone Number (phone), Notes (richtext).
• Relation: Company (relation → company, many_to_one).
• Rule: Always link to a company if one exists.

Lead/Prospect

• Fields: Full Name (text, required), Email Address (email, required), Phone Number (phone), Status (enum: New/Contacted/Qualified/Converted), Source (enum: Website/Referral/Cold Call/Social), Score (number), Assigned To (user), Notes (richtext).
• Relations: Company (relation → company, many_to_one), Deal (relation → deal, many_to_one).

Company/Organization

• Fields: Company Name (text, required), Industry (enum), Website (url), Type (enum: Client/Partner/Vendor), Relationship Status (enum), Notes (richtext).
• Note: Other objects (people, deals, invoices) typically link TO company.

Deal/Opportunity

• Fields: Deal Name (text, required), Amount (number), Stage (enum: Discovery/Proposal/Negotiation/Closed Won/Closed Lost), Close Date (date), Probability (number), Assigned To (user), Notes (richtext).
• Relations: Primary Contact (relation → people, many_to_one), Company (relation → company, many_to_one).
• Rule: Always link to BOTH contact and company.

Task/Activity (Kanban)

• Fields: Title (text, required), Description (text), Assigned To (user), Due Date (date), Status (enum: In Queue/In Progress/Done), Priority (enum: Low/Medium/High), Notes (richtext).
• Relation: Related To (relation → contextual parent, many_to_one).
• Setup: Use default_view = 'kanban' to auto-create Status and Assigned To fields.

Invoice/Payment

• Fields: Invoice Number (text, required), Amount (number), Status (enum: Draft/Sent/Paid/Overdue), Due Date (date), Notes (richtext).
• Relations: Company (relation → company, many_to_one), Deal (relation → deal, many_to_one).

DenchClaw uses a shared identity model across all its components to ensure consistent tracking.

• Shared Identity: All layers (CLI, Web App, and Plugins) read the same anonymousId from ~/.openclaw-dench/telemetry.json. The first component to run (typically the CLI during denchclaw bootstrap) generates this UUID, which is then reused by all subsequent layers.
• CLI: Uses the posthog-node SDK. Events are batched and flushed asynchronously to ensure telemetry never blocks CLI operations.
• Web App (Server): API route handlers use trackServer() via the posthog-node SDK, utilizing the persisted install ID.
• Web App (Client): Uses the posthog-js SDK. The server bootstraps the client with the install ID so the browser shares the same PostHog identity. Note that no cookies are set; session data is stored in memory only.
• OpenClaw Plugin: The @denchclaw/posthog-analytics plugin runs in-process with the OpenClaw Gateway. It reads the persisted install ID and hooks into agent lifecycle events to emit PostHog AI events.
• Security: The PostHog project token (phc_...) is embedded in built artifacts as a write-only token. It can only send events and cannot be used to read dashboards or analytics data.

When writing the sql property for a report panel, follow these strict rules to ensure compatibility with the PIVOT views and DuckDB:

1. Use PIVOT views: Always query the auto-generated v_{object} views (e.g., v_deal) instead of raw EAV tables.
2. Read-only: SQL must be SELECT-only. No INSERT, UPDATE, or DELETE.
3. Numeric Casting: Explicitly cast numeric fields using "Field"::NUMERIC or CAST("Field" AS NUMERIC).
4. Time-series: Use DATE_TRUNC('month', column_name) for grouping time-based data.
5. Ordering: Always include an ORDER BY clause for consistent rendering.
6. Aggregates: Use standard functions like COUNT(*), SUM(...), AVG(...), MIN(...), or MAX(...).
7. Quoting: Double-quote field names that contain spaces (e.g., "Full Name", "Assigned To").
8. Verification: Before writing the report, verify the view exists by running SELECT COUNT(*) FROM v_{object}.