Claude Code

The Kavanah plugin for Claude Code lets Claude work in your workspace from the terminal. It can read and update tasks, projects, clients, time entries, planning, deals and reports, and it can run the Kavanah AI agent's tools. Ask in plain language, and Claude finds the right call through the bundled kvn command-line tool.

Install

Run these two commands inside Claude Code. The plugin needs Node 18 or later.

Claude Code

/plugin marketplace add aw3-technology/kavanah-claude-plugin
/plugin install kavanah@kavanah

Sign in

1Ask Claude to sign you in to Kavanah, or run kvn login yourself. It prints a short code and opens kavanah.ai/cli/authorize.
2Check that the code matches, and approve it. Approving needs a workspace admin. If you are not an admin, send the link to an admin of your workspace.
3The CLI saves an API key to ~/.kavanah/credentials.json, readable only by you, and Claude can start working.

The key acts as the person who approved it, in the workspace that was active in their browser, with exactly their permissions. Those permissions are re-checked on every request. Revoke it with kvn logout, or at Settings → API keys, where it is listed under the computer's name.

What Claude can do

The REST API. Every documented endpoint is a named command, for example kvn tasks.list or kvn clients.create. kvn ls and kvn help list them.
Agent tools. kvn tool <name> runs one tool from the Kavanah agent's toolkit, and kvn agent "…" hands a request to the Kavanah agent itself.
The same guardrails as chat.Persona scopes, guardrails, the action ledger and undo all apply. An action your workspace's policy sends for approval is parked, not run, because no human is watching a programmatic call.

Safety

Writes go to your real workspace immediately. Claude is told to dry-run any write it is unsure of.
Deletes, bulk writes, imports and fan-out sends need an explicit --yes, which Claude should only pass for something you asked for.
A 403 means the key's user lacks that permission. The CLI does not try to route around it.

Kavanah inside Claude (connector)

To use Kavanah from claude.ai, Claude Desktop or the Claude mobile apps, you do not need the plugin or an API key. Add it as a connector:

1In Claude, add a custom connector with the URL https://kavanah.ai/api/mcp.
2Sign in to Kavanah when Claude asks, check the workspace named on the consent page (Switch workspace if it is wrong), and approve.
3Each connection acts as you, in that workspace, with your permissions. Any active member can connect. Disconnect it at Settings → API keys → Connected apps.

Other MCP clients that cannot sign in can reach the same endpoint with an API key from Settings → API keys (admins only):

Terminal

claude mcp add --transport http kavanah https://kavanah.ai/api/mcp \
  --header "Authorization: Bearer kvn_live_…"

Claude Code

1Ask Claude to sign you in to Kavanah, or run kvn login yourself. It prints a short code and opens kavanah.ai/cli/authorize.

2Check that the code matches, and approve it. Approving needs a workspace admin. If you are not an admin, send the link to an admin of your workspace.

3The CLI saves an API key to ~/.kavanah/credentials.json, readable only by you, and Claude can start working.

What Claude can do

The REST API. Every documented endpoint is a named command, for example kvn tasks.list or kvn clients.create. kvn ls and kvn help list them.

Agent tools. kvn tool <name> runs one tool from the Kavanah agent's toolkit, and kvn agent "…" hands a request to the Kavanah agent itself.

The same guardrails as chat.Persona scopes, guardrails, the action ledger and undo all apply. An action your workspace's policy sends for approval is parked, not run, because no human is watching a programmatic call.

Safety

Writes go to your real workspace immediately. Claude is told to dry-run any write it is unsure of.

Deletes, bulk writes, imports and fan-out sends need an explicit --yes, which Claude should only pass for something you asked for.

A 403 means the key's user lacks that permission. The CLI does not try to route around it.

Kavanah inside Claude (connector)

To use Kavanah from claude.ai, Claude Desktop or the Claude mobile apps, you do not need the plugin or an API key. Add it as a connector:

1In Claude, add a custom connector with the URL https://kavanah.ai/api/mcp.

2Sign in to Kavanah when Claude asks, check the workspace named on the consent page (Switch workspace if it is wrong), and approve.

3Each connection acts as you, in that workspace, with your permissions. Any active member can connect. Disconnect it at Settings → API keys → Connected apps.

Other MCP clients that cannot sign in can reach the same endpoint with an API key from Settings → API keys (admins only):

Terminal

claude mcp add --transport http kavanah https://kavanah.ai/api/mcp \
  --header "Authorization: Bearer kvn_live_…"