Skip to main content
An agent is a named session that represents an AI worker in your Dench workspace. When an AI tool logs in with dench login, Dench creates an agent record with an identity, a kind, and a session token. That agent can then claim tasks, read context, request approvals, and use connected external tools — all under a recognizable name that humans can see in the dashboard and approval requests.

​
Agent kinds

--kind accepts any string. Common values: claude_code, codex, cursor, hermes, openclaw. Custom strings like aider, goose, or some_custom_agent are also accepted. Defaults to other if omitted. Normalized to lowercase snake_case.

​
Logging in and creating an agent

The login command creates an agent in your workspace and links it to your current session. Choose a descriptive name that identifies both the AI tool and the repository or project it is working in. 
dench login \
  --name "Claude Code Agent - Billing Repo" \
  --kind claude_code
The CLI prints an approval link. Ask the human to open the link in a browser, confirm the workspace shown is the correct one, and approve the login. After approval, the CLI selects this session for all future commands.
1

Run login

Run dench login --name "..." --kind <kind>. The CLI prints a browser link.
2

Human approves

Ask the human to open the link, verify the workspace, and click Approve.
3

Verify with context

After approval, run dench context to confirm the correct workspace and agent name are selected.
Run dench status --mine --json immediately after login approval. It confirms which workspace and agent are active without dumping data from every other agent in the workspace.

​
Stable per-agent identity with DENCH_SESSION_KEY

By default, Dench derives the session key automatically. For stable, reproducible identity across restarts — useful in CI or long-running agent frameworks — set DENCH_SESSION_KEY to a human-readable string before login. 
DENCH_SESSION_KEY=claude-billing-agent dench login \
  --name "Claude Code Agent - Billing Repo" \
  --kind claude_code
Use the same key for every subsequent command from that agent: 
DENCH_SESSION_KEY=claude-billing-agent dench status --mine --json
Do not set DENCH_SESSION_KEY to values beginning with auto: or explicit:. Those are internal scopes from dench sessions output. Use them with dench use, not as environment variable values.

​
Managing multiple sessions

If multiple agents or sessions exist in your workspace, use dench sessions to list them and dench use to switch. 
# List all sessions
dench sessions --json

# Switch to a specific session
dench use <session-key-or-workspace-slug> --json
If dench status reports that multiple sessions exist, do not log in again. Run dench sessions and then dench use to select the right session.

​
Naming best practices

A good agent name makes it immediately clear who took an action in the dashboard or approval inbox. Follow this pattern: 
<Tool Name> Agent - <Repo or Project>
Good examples:
  • Claude Code Agent - Billing Repo
  • Codex Agent - PR Review
  • Cursor Agent - Frontend
Avoid:
  • Generic names like AI Agent (unclear which tool)
  • Names with no project context (hard to trace in approval history)
  • Reusing the same name for multiple agents in the same workspace

​
Logging out

To log out the current session: 
dench logout --json
To log out a specific session by key: 
dench logout --session <session-key> --json
To remove all stored sessions: 
dench logout --all --json