What Is a Dench App? Building Custom Tools Inside DenchClaw

Most CRM platforms give you a fixed set of views. You get a table, maybe a kanban board, possibly some basic charts. If you want something different — a custom dashboard, a specialized workflow tool, an interactive calculator that queries your pipeline — you're out of luck unless the vendor has it on their roadmap.

DenchClaw takes a different approach. Instead of building every possible tool into the core product, it ships a platform: the Dench App system. Dench Apps are self-contained web applications that live inside the DenchClaw workspace, appear in your sidebar, and have full access to your CRM data, AI agent, and files. If you can build it as a webpage, you can build it as a Dench App.

This guide explains what Dench Apps are, how they work architecturally, what you can build with them, and when it makes sense to build one versus using a built-in DenchClaw view.

The Basics: What Is a Dench App?#

A Dench App is a folder ending in .dench.app/ that lives inside your DenchClaw workspace, typically in the apps/ directory. At minimum, a Dench App contains:

1. A .dench.yaml manifest file (name, icon, permissions)
2. An index.html entry point

That's it. No build step required. No npm install. No webpack config. The app is served directly from the filesystem by DenchClaw's built-in app server.

Here's the simplest possible Dench App directory structure:

apps/
  my-dashboard.dench.app/
    .dench.yaml
    index.html

And the corresponding manifest:

name: My Dashboard
icon: bar-chart
description: Pipeline metrics at a glance
permissions:
  - db.read
  - ui.toast

The index.html is a standard HTML file. You can use any JavaScript library you want — Chart.js, D3, React, Vue, vanilla JS — because the app runs in a browser context. The magic comes from window.dench, a JavaScript SDK that DenchClaw auto-injects into every app.

The Bridge API: window.dench#

Every Dench App automatically gets access to window.dench — a JavaScript object with namespaces for everything in the DenchClaw platform. This bridge API is what transforms a static HTML page into a live application connected to your CRM data.

The main namespaces are:

// Database queries
const leads = await dench.db.query(
  "SELECT * FROM v_people WHERE \"Status\" = 'Lead' ORDER BY \"Created At\" DESC"
);
 
// Object management
const objects = await dench.objects.list();
const people = await dench.objects.entries('people', { limit: 50 });
 
// AI chat
const session = await dench.chat.createSession();
const reply = await dench.chat.send(session.id, 'Summarize my top 5 deals');
 
// UI utilities
await dench.ui.toast({ message: 'Import complete!', type: 'success' });
await dench.ui.confirm('Delete all test data?');
 
// Persistent app storage
await dench.store.set('lastFilter', 'active');
const filter = await dench.store.get('lastFilter');
 
// External HTTP (proxied, no CORS issues)
const data = await dench.http.fetch('https://api.example.com/data');
 
// Real-time events
dench.events.on('entry:created', (event) => {
  console.log('New entry:', event.entry);
  refreshDashboard();
});
 
// File system access
const files = await dench.files.list('/workspace/docs/');
const content = await dench.files.read('/workspace/notes/meeting.md');
 
// Scheduled tasks
await dench.cron.schedule({ everyMs: 3600000 }, 'Refresh lead data');

The bridge API runs over a postMessage channel between the app iframe and the DenchClaw host. All calls are async and return Promises. The permissions field in .dench.yaml controls what API surface each app can access — a dashboard app that only reads data doesn't need files.write or db.write permissions.

How Apps Appear in DenchClaw#

Once you drop a .dench.app folder into your workspace, DenchClaw automatically detects it (via filesystem watcher) and adds it to the sidebar. The icon specified in .dench.yaml appears alongside your built-in CRM objects. Clicking it opens the app in a tab within the DenchClaw interface.

Apps run inside a sandboxed iframe in the main DenchClaw frontend. This means:

• Apps can't directly access DOM elements outside their iframe
• Cross-origin requests go through the dench.http.fetch proxy, not directly
• DuckDB queries run server-side and return JSON results — the app doesn't get raw database access
• Permissions are enforced at the bridge layer, not just the manifest

This design gives you the power of direct data access while keeping the host application secure. Apps can do a lot, but they can't break DenchClaw itself.

Widget Mode#

Not every app needs to be a full page. DenchClaw supports widget mode — apps that display as compact cards in a dashboard grid.

To enable widget mode, add display settings to your manifest:

name: Active Deals Counter
icon: trending-up
display:
  mode: widget
  width: 2  # grid columns (out of 12)
  height: 1 # grid rows
  refreshMs: 30000  # auto-refresh every 30 seconds
permissions:
  - db.read

Widgets are ideal for at-a-glance metrics: active deal count, overdue tasks, leads added this week, emails unopened. They auto-refresh on a configurable interval and can be arranged in a dashboard grid from the DenchClaw settings panel.

What Can You Build?#

The scope of what's possible is genuinely wide. Here are representative categories:

Live Analytics Dashboards#

Pull real-time data from DuckDB and render it with Chart.js or D3. Pipeline velocity by stage. Revenue forecast by month. Lead source attribution. Anything you can express as a SQL query, you can visualize.

const data = await dench.db.query(`
  SELECT 
    "Stage" as stage,
    COUNT(*) as deal_count,
    SUM(CAST("Deal Value" AS FLOAT)) as total_value
  FROM v_deals
  WHERE "Status" != 'Closed Lost'
  GROUP BY "Stage"
  ORDER BY total_value DESC
`);
// Render with Chart.js...

AI Chat Interfaces#

Build workflow-specific chat UIs that pre-load relevant context. A deal coach that knows your current pipeline. A meeting prep assistant that pulls up the relevant contact history. A prospecting tool that searches your CRM and the web simultaneously.

const context = await dench.db.query(
  `SELECT * FROM v_companies WHERE id = ${companyId}`
);
const session = await dench.chat.createSession({
  systemPrompt: `You are analyzing this company: ${JSON.stringify(context)}`
});

CSV/Data Importers#

Drag-and-drop CSV upload interfaces that parse, preview, and push data into DuckDB. Field mapping UI, validation, duplicate detection — all in a custom app that's designed specifically for your data format.

Proposal and Document Generators#

Forms that pull CRM data, let you fill in additional details, and generate formatted documents. A quote builder that reads product pricing from a DuckDB table and generates a PDF proposal. A board update generator that queries deal status and writes a narrative.

Interactive Calculators and Tools#

Any specialized calculator that works on your data. A renewal probability tool that queries account health metrics. A hiring plan modeler that reads headcount data from your CRM. A commission calculator that queries closed deals by rep.

Games and Creative Tools#

Because why not. DenchClaw ships with a few example apps including a 2D game built with p5.js and a generative art tool. These aren't business applications, but they demonstrate that the platform is truly general-purpose.

Dench App vs Built-in CRM View: When to Use Which#

Built-in views are great for day-to-day CRM operations. Dench Apps are for when you need something the built-in views don't offer — custom visualizations, specialized workflows, or tools that combine CRM data with external sources.

Getting Started#

The easiest way to start is with the app builder skill. Ask your DenchClaw agent:

"Build me a Dench App that shows a bar chart of my deals grouped by stage."

The agent will create the .dench.app folder, write the .dench.yaml manifest, and generate the index.html with the right bridge API calls and Chart.js rendering code. The app will appear in your sidebar immediately.

If you prefer to build manually, here's a minimal starting template:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>My App</title>
  <script src="https://cdn.jsdelivr.net/npm/chart.js"></script>
  <style>
    body { font-family: sans-serif; padding: 24px; }
    canvas { max-width: 600px; }
  </style>
</head>
<body>
  <h1>Pipeline by Stage</h1>
  <canvas id="chart"></canvas>
  <script>
    async function init() {
      const rows = await dench.db.query(
        `SELECT "Stage", COUNT(*) as n FROM v_deals GROUP BY "Stage"`
      );
      new Chart(document.getElementById('chart'), {
        type: 'bar',
        data: {
          labels: rows.map(r => r.Stage),
          datasets: [{ data: rows.map(r => r.n), label: 'Deals' }]
        }
      });
    }
    init();
  </script>
</body>
</html>

Drop this in a .dench.app folder with a valid .dench.yaml and you have a live pipeline chart.

Security Model#

Apps are sandboxed and permission-controlled. A few things to know:

• Permissions are explicit: Apps only get bridge API access to what they declare in .dench.yaml
• DuckDB writes are destructive: If your app has db.write permission, queries can modify your data. Double-check your SQL.
• External HTTP is proxied: dench.http.fetch proxies external requests through the DenchClaw server, so your API keys stay server-side
• No eval or dynamic imports from remote: Apps can't load scripts from remote origins (Content Security Policy blocks this)

For most read-only dashboard apps, db.read and ui.toast are the only permissions you need.

Frequently Asked Questions#

Do I need to know React or a modern framework to build Dench Apps?#

No. Dench Apps are plain HTML/CSS/JavaScript. You can use any framework if you want, but the simplest apps — dashboards, calculators, importers — work great with vanilla JS and a chart library.

Can I share my Dench Apps with other DenchClaw users?#

Yes. A .dench.app folder is just a directory of files. You can zip it, post it to GitHub, or publish it to clawhub.ai. Anyone with DenchClaw can drop it into their apps/ folder and use it immediately.

Can Dench Apps talk to external APIs?#

Yes, via dench.http.fetch. This proxies requests through DenchClaw's server, which means you can make authenticated API calls with keys stored server-side rather than embedded in your HTML.

What happens to my app when DenchClaw updates?#

Apps are isolated in their own folders and don't depend on DenchClaw's internal implementation — only the bridge API. The bridge API is versioned and backward-compatible, so apps built today will continue to work as DenchClaw evolves.

Is there a limit on what apps can do?#

The main limit is the permissions system. Apps can only access what they've declared in their manifest. Beyond that, the sky is the limit — anything you can build as a webpage, you can build as a Dench App.

Related: Build your own apps without a developer → | The Bridge API explained → | Dench App examples →

Ready to try DenchClaw? Install in one command: npx denchclaw. Full setup guide →