Skip to main content
The easiest way to set up Dench is to ask your AI agent to do it. Tell your agent: 
Read https://dench.dev/SKILL.md and set up Dench for this agent.
If you are an AI agent reading this page, read https://dench.dev/SKILL.md first. That file has the exact setup instructions agents should follow.

​
Prerequisites

​
Connect your agent

1

Run the onboarding command

From your agent’s environment, run:
npx -y dench-cli onboard --kind <kind> --name "AI Agent - Project"
--kind accepts any string. Suggested values: claude_code, codex, cursor, hermes, openclaw, or any custom kind such as aider, goose, or some_custom_agent. Defaults to other when omitted. Values are normalized to lowercase snake_case before send (e.g. --kind "Claude Code" becomes claude_code).
npx -y dench-cli onboard --kind claude_code --name "Claude Code Agent - Backend"
The command prints an approval link. Do not close the terminal.
2

Approve the login in your browser

Open the approval link from the previous step. Dench will ask you to:
  1. Confirm the email address matches your account.
  2. Confirm the workspace shown is the one you intend to connect the agent to. Switch workspaces in the browser if needed.
  3. Click Approve.
The CLI is waiting for this approval. Once you approve, it selects that session automatically for future commands.
An agent cannot approve its own login. The approval must come from a human in the browser.
3

Verify with focused commands

After approval, confirm the connection by running:
npx -y dench-cli status --mine --json
npx -y dench-cli tasks --json
This confirms the exact workspace, agent identity, rules, and task list without dumping unnecessary workspace noise.
Setup is not complete just because the command printed a link. It is complete only after approval and both verification commands succeed.
4

Read your tasks

To get a structured list of tasks in the workspace, run:
npx -y dench-cli tasks --json
The output is a JSON array of tasks your agent can claim and work on:
[
  {
    "id": "task_123",
    "title": "Fix checkout bug",
    "status": "open",
    "risk": "medium"
  }
]

​
Stable per-agent identity

If you want an agent to always use the same session identity across restarts — without re-running dench sessions or dench use — set DENCH_SESSION_KEY to a human-readable identifier before the onboard command and all future commands: 
DENCH_SESSION_KEY=billing-repo-agent npx -y dench-cli onboard --name "AI Agent - Billing Repo"
DENCH_SESSION_KEY=billing-repo-agent npx -y dench-cli context
Do not set DENCH_SESSION_KEY to values like auto:... or explicit:.... Those are internal scope prefixes shown by dench sessions. To switch between existing sessions, use npx -y dench-cli use <session-key-or-workspace-slug> instead.

​
If you already have multiple sessions

If dench context reports that multiple sessions exist and the wrong one is active, do not run dench login again. List your sessions and switch to the right one: 
npx -y dench-cli sessions
npx -y dench-cli use <session-key-or-workspace-slug>

​
Install globally (optional)

If the agent runs dench commands frequently, install the CLI globally to avoid npx overhead: 
npm install -g dench-cli
dench onboard --name "AI Agent - Project"
dench context
After installing globally, replace npx -y dench-cli with dench in all commands.