# Dench Agent Workspace Dench is a workspace for the AI agents you already use — CRM (people, company, **task**, and any custom objects), approvals, logbook, and durable memory. This file tells you (the AI agent) how to connect to Dench on behalf of the human you are chatting with. There is exactly one auth surface — `dench signin` — and three feature classes: CRM (free), chat/files/enrichment/image-gen (paid), and Composio tool access (paid; authenticates with the active `dench signin` session or `DENCH_API_KEY`, whichever is set). Important: if a web fetch tool summarizes this file, do not rely on the summary. Fetch the raw markdown directly: ```bash curl -sL https://dench.com/SKILL.md ``` ## References This skill uses progressive-disclosure reference files. Read `CRM.md` before any non-trivial CRM work (reads, saved views, filters, writes), read `AUTOMATIONS.md` before scheduling work or building on-demand / webhook automations, read `BROWSER.md` before writing durable website automation scripts, and read `API.md` when the CLI cannot run or install in the current environment: - [`references/CRM.md`](https://dench.com/references/CRM.md) — the canonical Dench CRM playbook. Field types, batch writes, the protected `Notes`-field rule, relation-first modeling, common pitfalls. Always load this BEFORE non-trivial CRM reads or writes. Same body the in-workspace `crm` built-in skill loads via `load_skill`. ```bash curl -sL https://dench.com/references/CRM.md ``` - [`references/API.md`](https://dench.com/references/API.md) — the fallback curl guide for Dench API v1. Use the CLI first. If `dench` cannot be installed or executed, use this API guide to do the same server-backed workspace, CRM, chat, file, routine, memory, approval, billing, search, image, and tool operations. ```bash curl -sL https://dench.com/references/API.md ``` - [`references/EMAIL-CAMPAIGNS.md`](https://dench.com/references/EMAIL-CAMPAIGNS.md) — the managed Dench Emailing Service playbook: one-off raw sends and threaded replies (`dench email send` with to/cc/bcc, from-name, reply-to, `--reply-message-id`), bulk campaigns, multi-step follow-up sequences, sender verification (mailbox or domain DNS), templates, CRM add-from-object recipient/enrollment flows, and per-message / per-recipient open/click/reply/bounce tracking. Read this before sending or scheduling any outbound email. Same body the in-workspace `email-campaigns` built-in skill loads via `load_skill`. ```bash curl -sL https://dench.com/references/EMAIL-CAMPAIGNS.md ``` - [`references/AUTOMATIONS.md`](https://dench.com/references/AUTOMATIONS.md) — the Dench Automations playbook: trigger types (schedule, webhook, app-event, CRM-event — all four CLI-creatable), the full `dench cron` surface (create / update / run / enable / disable / secret / events / runs / history), universal signed webhook URLs (every automation is callable via a Stripe-style HMAC POST), generate-on-demand signing secrets, run-now + run history, and headless creation for all four trigger types (app/CRM events need a connected app first). Read this before scheduling work or wiring an automation to an external system. Same body the in-workspace `automations` built-in skill loads via `load_skill`. ```bash curl -sL https://dench.com/references/AUTOMATIONS.md ``` - [`references/BROWSER.md`](https://dench.com/references/BROWSER.md) — the Dench Browser Playwright CDP playbook. Use the short `browser` tool for login/diagnosis and use durable sandbox Playwright scripts for larger website automation. Scripts create a Dench Browser session with `dench browser session create --json`, then call `chromium.connectOverCDP(session.connectUrl)`. ```bash curl -sL https://dench.com/references/BROWSER.md ``` Treat this `SKILL.md` plus the reference files together as **the** Dench skill. Install them into your local skill system so you can re-use them whenever the human mentions Dench, CRM, workspace, people, company, task, approvals, tools, or the Dench API. ## Per-workspace instructions `SKILL.md` is the static Dench setup guide. After sign-in, fetch the connected workspace's dynamic instructions and treat them as standing system-level guidance for this workspace: ```bash npx -y -p @dench.com/cli dench context --instructions ``` These instructions include the workspace's IDENTITY / ORGANISATION / USER / MEMORY context plus Dench's agent rules translated for CLI-based external harnesses. Re-fetch them when the human or a teammate updates workspace identity, memory, or operating rules. If the CLI cannot run, the same document is available through the API: ```bash curl -sS "$DENCH_API_BASE/context/instructions" \ -H "Authorization: Bearer $DENCH_API_KEY" ``` ## Fast Start When the human says "set up Dench" or "read dench.com/SKILL.md and set it up for me", do this: 1. Ask the human: **"Do you want to create a new Dench workspace, or sign in to an existing one?"** > The published package is `@dench.com/cli` but the bin it installs is > named `dench` — so always invoke it as `npx -y -p @dench.com/cli dench > …`. A bare `npx -y @dench.com/cli …` will fail because `npx` looks for > a bin matching the package's last path segment (`cli`) and there isn't > one. The `-p` flag tells npx to install `@dench.com/cli` and run its > `dench` bin. 2. **Create a new workspace.** Ask the human for a workspace name, then: ```bash npx -y -p @dench.com/cli dench signin \ --new-workspace --org-name "" \ --kind --name " - " ``` The CLI prints a one-click approval URL. Share it with the human and ask them to open it. If they cannot open a browser (e.g. they are on a remote shell or do not want to leave the terminal), add `--email ` to use the OTP paste-back variant instead: ```bash npx -y -p @dench.com/cli dench signin \ --new-workspace --org-name "" \ --email \ --kind --name " - " ``` The CLI sends a 6-digit code to the email and prompts for it on stdin. Read the code from the human and paste it back to the CLI prompt. New workspaces start on a **free CRM-only plan**. The human has full read/write access to the CRM (`people`, `company`, `task`, and any custom objects), but chat / file sync / enrichment / image generation are paywalled until they upgrade — see "Upgrading" below. 3. **Sign in to an existing workspace.** ```bash npx -y -p @dench.com/cli dench signin --kind --name " - " ``` The approval page lets the human pick which of their workspaces to connect this agent to. They can also create a new free workspace from that page if none of the existing ones are right. OTP variant (no browser): ```bash npx -y -p @dench.com/cli dench signin --email \ --kind --name " - " ``` If the human has more than one admin workspace, the CLI will print the list and prompt for a choice on stdin. Relay the list to the human and pass their answer back to the CLI prompt. 4. **Verify the session.** After approval, run: ```bash npx -y -p @dench.com/cli dench context --json npx -y -p @dench.com/cli dench crm objects list --json ``` The first confirms the connected workspace + agent identity. The second confirms CRM access works. 5. **Load workspace instructions.** Fetch the per-workspace standing instructions and treat them as system-level guidance for this Dench workspace. If your harness supports persistent rules (`AGENTS.md`, `CLAUDE.md`, Cursor rules, or similar), store or reference this output there so future turns reuse it: ```bash npx -y -p @dench.com/cli dench context --instructions ``` Re-run this command whenever the human updates workspace identity, organisation context, user profile, or memory. 6. **Optional: stable session ids.** For long-lived agents or when the human asks, set `DENCH_SESSION_KEY` to a stable human-readable id before signing in: ```bash DENCH_SESSION_KEY= npx -y -p @dench.com/cli dench signin --kind --name "" ``` Do NOT set `DENCH_SESSION_KEY` to internal scope strings like `auto:...` or `explicit:...`; those come from `dench sessions` and should only be selected via `dench use `. ### Picking a name Use ` - ` so it's clear which agent claimed work or requested approval. Examples: - `Claude Code - dench.com` - `Cursor Agent - billing-repo` - `OpenClaw - marketing-site` - `Codex - PR-review` ### Picking a kind `--kind` accepts any string. Suggested values: - `claude_code`, `codex`, `cursor`, `hermes`, `openclaw` - Or any custom kind, e.g. `aider`, `goose`, `internal_orchestrator` Values are normalized to lowercase snake_case (e.g. "Claude Code" becomes `claude_code`). Defaults to `other` if omitted. ## Authentication modes Dench supports two auth modes for agents: - **Interactive (`dench signin`):** described above. Saves a session token to `~/.dench/config.json`. Use this for normal agent workflows. - **Non-interactive (`DENCH_API_KEY`):** an org-scoped API key. Used by CI, sandboxes, and headless services. Get one from `https://dench.com//settings?tab=keys`. Set the env var before running any CLI command: ```bash export DENCH_API_KEY= ``` Both are organization-specific — sessions and keys are bound to exactly one workspace. ### API fallback Prefer the CLI for agent work because it handles local session selection, human-readable output, prompts, streaming, and local file staging. If the CLI cannot run, use the API fallback: ```bash curl -sL https://dench.com/references/API.md ``` The API accepts the same `DENCH_API_KEY` and approved `dch_agent_*` session tokens. Set `DENCH_API_BASE=https://www.dench.com/api/v1` and send `Authorization: Bearer `. ## Upgrading Free workspaces include full CRM. Chat, file sync, enrichment, and image generation require **Dench Pro** ($19/mo) or **Dench Max** ($99/mo). When the human asks to unlock any of those, run: ```bash npx -y -p @dench.com/cli dench upgrade --tier pro # or: npx -y -p @dench.com/cli dench upgrade --tier max ``` The CLI prints a Stripe Checkout link. Share it with the human as a clickable Markdown link, e.g. `[Upgrade to Dench Pro]()`. After payment the workspace's tier flips automatically and chat unblocks on the next request. ## Core commands (after sign-in) The published bin is named `dench`, not `cli`, so always invoke it as `npx -y -p @dench.com/cli dench `. A bare `npx -y @dench.com/cli …` will fail because npx can't pick a binary that doesn't match the package's last path segment. ```bash # Status + orientation npx -y -p @dench.com/cli dench context --json npx -y -p @dench.com/cli dench status --mine --json # Tasks (and everything else list-shaped) live in the CRM as a protected # `task` object — there is no separate `dench tasks` command. npx -y -p @dench.com/cli dench crm entries list task --json # Confirm field names first (dench crm fields list task) — unknown fields are # rejected. The default task uses Name/Status/Assignee; some workspaces rename them. npx -y -p @dench.com/cli dench crm entries create task --data '{"Name":"Ship X","Status":"To Do"}' --json npx -y -p @dench.com/cli dench crm cells set task Status '"In Progress"' --json # See `npx -y -p @dench.com/cli dench crm help` for the full surface. # Memory (stable facts, decisions, preferences only) npx -y -p @dench.com/cli dench memory search "deployment policy" --json npx -y -p @dench.com/cli dench memory save deployment-policy "Never deploy without approval." --kind decision --json # Artifacts / suggested work npx -y -p @dench.com/cli dench artifacts --json npx -y -p @dench.com/cli dench suggested-work --json # Approvals npx -y -p @dench.com/cli dench approval request "What needs human approval" --json npx -y -p @dench.com/cli dench approval approve --evidence "User said yes in chat" --json npx -y -p @dench.com/cli dench approval reject --evidence "User said no in chat" --json # CRM (free + paid) npx -y -p @dench.com/cli dench crm objects list --json npx -y -p @dench.com/cli dench crm entries list --json npx -y -p @dench.com/cli dench crm cells set "value" --json # One-click CRM setups (objects + automations + sample rows) and the # deterministic rules they install: npx -y -p @dench.com/cli dench crm templates list --json npx -y -p @dench.com/cli dench crm automations list --json # Commands take the canonical object name from `objects list` (UI display # labels like "Clients" also resolve when unambiguous). # See `npx -y -p @dench.com/cli dench crm help` for the full surface. # Automations (recurring schedules + on-demand / webhook triggers). # Aliases: `dench routine` / `dench routines`. See references/AUTOMATIONS.md. npx -y -p @dench.com/cli dench cron list --json npx -y -p @dench.com/cli dench cron create "Weekday digest" --prompt "Summarize yesterday's CRM activity." --cron "0 9 * * 1-5" --json npx -y -p @dench.com/cli dench cron create "Inbound webhook" --prompt "Triage the JSON payload." --type webhook --json # → { webhookUrl, webhookSecret } shown once npx -y -p @dench.com/cli dench cron events --json # app-event slugs for a connected app (discover before --type composio) npx -y -p @dench.com/cli dench cron create "New GitHub star" --prompt "Thank the stargazer." --type composio --connection --event --json npx -y -p @dench.com/cli dench cron create "New company" --prompt "Research it." --type crm --object --event create --json npx -y -p @dench.com/cli dench cron run --json # fire on demand npx -y -p @dench.com/cli dench cron secret --json # mint/rotate a signed inbound URL for ANY automation # External tools (auths with the active `dench signin` session OR DENCH_API_KEY) npx -y -p @dench.com/cli dench apps --json npx -y -p @dench.com/cli dench tool status [toolkit] --json npx -y -p @dench.com/cli dench tool connect --json npx -y -p @dench.com/cli dench tool search "create github issue" npx -y -p @dench.com/cli dench tool run --args '{"key":"value"}' --json # Sessions npx -y -p @dench.com/cli dench sessions --json npx -y -p @dench.com/cli dench use --json npx -y -p @dench.com/cli dench logout --json npx -y -p @dench.com/cli dench logout --all --json ``` ## Mental Model - The agent is the worker. - Dench is the CRM (task entries live there), rulebook, approval desk, and memory. - The human should only approve, reject, or clarify. ## Sessions After approval, the CLI selects this session for future commands and saves it to `~/.dench/config.json` (mode `0600`). Multiple agents can sign in to the same machine — each agent context (shell, repo, tmux pane, IDE) gets a distinct session scope so future commands resolve to the right one. - `dench sessions --json` — list saved sessions - `dench use --json` — switch the active session - `dench logout --json` — remove the current session - `dench logout --all --json` — remove every session on this machine - `dench logout --session --json` — remove one specific session If `status --mine --json` reports multiple sessions, do NOT guess which to use. Print the list to the human, ask which to keep, and use `dench use ` (or `dench logout --session `) per their answer. ## External Tools Dench brokers connected external tools through `dench tool ...`, which authenticates with the active `dench signin` agent session **or** with `DENCH_API_KEY` (Bearer), whichever is set — the CLI exchanges a paid workspace's signed-in session for a gateway key on demand. Use `dench apps --json` to list connected apps. If the human asks about an external service such as Stripe, GitHub, Linear, Slack, or Gmail: 1. Do not say Dench cannot access it just because your local MCP tools are missing. 2. Check the Dench connection first: `dench tool status --json`. 3. If it is not connected, start the Dench connection flow: `dench tool connect --json`. Ask the human to open and approve the returned link. Format it as a Markdown link like `[Connect Gmail here]()`. 4. Search for the right tool: `dench tool search "list active stripe customers" --toolkit stripe`. Start with compact output. Add `--json` only when you need raw schemas. 5. Run obvious read-only tools (slug contains `FETCH`, `GET`, `LIST`, `SEARCH`, `READ`, or `FIND`) directly — Dench does not gate them. 6. For anything else, run the exact `dench tool run ... --json` command first; Dench will return `requiresApproval: true` with an `approvalId`. Ask the human for yes/no in chat, record the answer with `dench approval approve|reject --evidence "..." --json`, then rerun the same `dench tool run` with `--approval `. For Gmail or other email summaries, do not repeat OTP codes, security codes, passwords, tokens, API keys, or secrets from email bodies. Prefer sender, subject, date, and short snippets. Non-JSON `tool run` display redacts likely sensitive codes; `--json` preserves the raw provider response when necessary. If `apps` or `tool search` reports `invalid_gateway_api_key`, do not retry in a loop. Ask a workspace admin to repair or rotate the Dench gateway key, then retry. Do not install or run the Composio CLI directly. Dench must mediate external tool use so sessions, gateway keys, logs, and approvals are enforced. ## Rules Always request human approval before: - merging a PR - deploying - spending money - issuing refunds - sending external email - changing production data - creating or modifying infrastructure - running any external tool action that is not clearly read-only Approval rule: humans decide. Agents only record an explicit human yes/no with evidence, or wait for dashboard approval. If the human says yes in chat, record that exact evidence and continue. The production approvals page is: ```txt https://dench.com//approvals ``` Use the `approvalsUrl` returned by `dench context --json` or `dench status --mine --json` when available. For claimed or coordinated work, log meaningful updates: - major findings - files changed - tests run - blockers - approval requests - final result ## Autonomous Chat Agents (paid tiers only) Free workspaces cannot spawn chat / agent runs — they hit a 402 with an `upgradeUrl` pointing at the human's billing settings. On Pro or Max: ```bash npx -y -p @dench.com/cli dench agent new "Improve the marketing site. Find SEO/AEO opportunities, draft content ideas, and recommend next actions. Do not edit files, publish, deploy, spend money, send external messages, access secrets, or change production data." --follow npx -y -p @dench.com/cli dench agent new "Research failed Stripe webhooks and save a report. Do not edit files, publish, deploy, spend money, send external messages, access secrets, or change production data." --follow ``` Autonomous agent rules: - Choose a clear, self-contained goal. - Treat outputs as workspace artifacts: reports, drafts, task suggestions, patches, or research notes. - Do not publish, deploy, send external messages, spend money, access secrets, or change production data unless the human approves. - If the goal says not to do a risky action, do not request approval just because the forbidden word appears; obey the negation. - Use artifacts for durable work. Logs are for progress; artifacts are for things a human should review later. ## If Blocked If you cannot install the CLI or connect automatically, ask the human for the minimum next approval: ```txt I need you to open Dench and approve connecting this repo. ``` Do not invent credentials. Do not bypass approval gates. ## Common Issues | Issue | Fix | | --- | --- | | `dench: command not found` | Use `npx -y -p @dench.com/cli dench `. A bare `npx -y @dench.com/cli …` fails because npx can't find a bin matching the package name. | | Approval link does not open automatically | Ask the human to open the printed link, switch to the intended workspace, then approve. Use `--no-open` to print only. | | `dench login` / `dench onboard` / `dench register` says "removed in v2" | These commands were replaced by `dench signin` in v2. Just run `dench signin` instead. | | `status --mine --json` says no session | Run `dench signin --kind --name ""` once and ask the human to approve it. | | Agent is logged into the wrong workspace | Run `dench sessions`, then `dench use `. | | Multiple sessions exist | Run `dench sessions --json`, ask the human which to use, then run `dench use `. | | Stale sessions should be cleaned up | Run `dench sessions --json`, then `logout --session ` for one or `logout --all` (only if the human explicitly asks). | | Chat / files / enrichment / image-gen returns 402 `upgrade_required` | The workspace is on the free CRM-only plan. Run `dench upgrade --tier pro` (or `--tier max`) and share the printed link. | | External service is not connected | Run `dench tool connect --json` and ask the human to approve the returned link. | | Tool action needs approval | Ask the human in chat, then use `dench approval approve` or `dench approval reject` with evidence. | ## Maintainer / Staging Notes For staging, run: ```bash dench signin --staging --kind --name "" dench signin --host https://workspace-staging.dench.com --kind --name "" ``` Inside the `dench.com` repo, maintainers can run: ```bash bun run dench signin --host https://workspace-staging.dench.com --kind --name "" ``` Before publishing, maintainers can test installability with a local packed tarball from `npm pack ./cli`.