> ## Documentation Index
> Fetch the complete documentation index at: https://docs-agentic-id.icustomer.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Claude Code plugin

> Install Agentic ID in Claude Code: tools, skills, a lead-qualification agent, spending approval and a local usage log.

The plugin adds the Agentic ID [MCP tools](https://docs-agentic-id.icustomer.ai/mcp-server.md), six skills, one agent, four commands, three hooks and the `agentic-id` [CLI](https://docs-agentic-id.icustomer.ai/cli.md) to Claude Code.

Requirements: Node.js 18 or later. The plugin installs no packages.

## Install

```bash theme={null}
claude plugin marketplace add icustomerai/agentic-id-plugin
claude plugin install agentic-id@icustomer
```

Claude Code asks for the plugin options when you enable it. All four are optional.

## Options

| Option | Name | Default | What it does |
| - | - | - | - |
| Agentic ID API key | `api_key` | empty | Leave empty to sign in. For CI and headless runs, set a key. Claude Code keeps it in your system keychain. A key, when set, is used instead of a sign-in. |
| Agentic ID API URL | `api_url` | `http://127.0.0.1:3100` | Where the Agentic ID API runs. Set it to `https://YOUR_AGENTIC_ID_HOST`. |
| Session credit budget | `session_budget` | empty | The most one Claude Code session may spend through the plugin. Empty means no session budget. |
| Ask before spending more than | `confirm_above` | `10` | Claude Code asks you to approve any single call that could spend more than this many credits. `0` asks before every paid call. |

To change an option later, run `/plugin configure agentic-id@icustomer`, or open `/plugin`, select Agentic ID on the **Installed** tab and choose **Configure options**.

## Sign in

**1. Start sign-in**

Type `/agentic-id-login`, or run `agentic-id login` in a terminal. Your browser opens the sign-in page.

**2. Return to Claude Code**

When the page says you are signed in, go back to Claude Code. The session is stored in `~/.agentic-id/session.json`, readable by you only, and renews itself for 30 days.

**3. Check**

Type `/agentic-id-status`. It says which workspace you are connected as.

Skip sign-in if you set an API key. `agentic-id logout` ends the session.

> [!WARNING]
>
> Never paste an API key into the chat. A key goes in the plugin options. The skills tell Claude never to ask for one.

## How spending confirmation works

Three checks apply to every paid call, in this order.

| Check | Where | What happens |
| - | - | - |
| Session budget | Hook, before the call | With `session_budget` set, a paid call is denied once the session's logged calls have charged that many credits, or when the call's own worst case is more than what is left. |
| Approval | Hook, before the call | Claude Code asks you to approve a call whose worst case is above `confirm_above`, and shows the amount. It asks again each time the session's total spend would pass another multiple of `confirm_above`. |
| Cap required | Tool | A call that could cost more than 10 credits and has no `max_credits` is refused with the estimate. |

The worst case of a call is its `max_credits`, or the list-price estimate when it has none.

These calls always pass: facts, ledger, estimate, status, workspace, report, login, discover with `count_only`, and list with `dry_run` or the `report` action.

Each call is also capped by its own `max_credits`, which the API never exceeds. See [Credits](https://docs-agentic-id.icustomer.ai/credits.md).

## What ships

### Skills

| Skill | What it does |
| - | - |
| `agentic-id` | Picks the right tool, gives Claude the exact arguments, and applies the credit and level rules |
| `agentic-id-credits` | Costs, estimates and counts before buying, caps, and how to read what was charged |
| `who-matters` | A playbook: check, resolve, enrich, find and discover inside a budget agreed with you first |
| `clean-a-list` | De-duplicate a lead or CRM file and check its emails, written back as extra columns |
| `lookalike-prospecting` | From your best customers to a shared profile to a list of similar companies |
| `trust-check` | Whether a record is safe to act on, and why two records are the same ID |

### Agent

| Agent | What it does |
| - | - |
| `lead-qualification` | Works a list of leads end to end inside a credit budget and returns a list grouped by account, with each value's level and the credits used per step. With no budget given, it uses a ceiling of 50 credits. |

### Commands

| Command | What it does |
| - | - |
| `/agentic-id-login` | Signs you in with your account, in the browser |
| `/agentic-id-status` | Checks the connection: server, workspace, and whether contact values are masked |
| `/agentic-id-clean-list <csv> [budget]` | Starts `clean-a-list` on a file, estimate first |
| `/agentic-id-usage [n]` | Credits available, spend by tool and recent charges from your workspace, then this machine's own call log |

### Hooks

| Hook | Runs | What it does |
| - | - | - |
| Budget guard | Before each Agentic ID tool call | Applies the session budget and the approval threshold |
| Usage log | After each Agentic ID tool call | Appends one line to `~/.agentic-id/usage.jsonl` |
| Prompt hint | When you submit a prompt | If the prompt looks like a company, people, list or credits question, reminds Claude to use the plugin's tools. It writes and sends nothing. |

### CLI

The plugin puts the `agentic-id` command on the PATH of shells that Claude Code starts. See [CLI](https://docs-agentic-id.icustomer.ai/cli.md).

## What the plugin sends and stores

**Network.** The plugin talks only to the API at the URL in the **Agentic ID API URL** option. It sends the arguments of each call, your credential as a Bearer token, and the header `x-agentic-id-client: agentic-id-plugin/<version>`.

**Held back on your machine.** Personal email addresses, phone numbers and malformed input are dropped before any call. The answer says how many were held back.

**Local files**, all in `~/.agentic-id` (or the folder in `AGENTIC_ID_CONFIG_DIR`):

| File | Contents |
| - | - |
| `session.json` | Your sign-in session |
| `usage.jsonl` | One line per call: time, session ID, tool, success, error code, request ID, credits quoted and charged. No tool inputs or results. Created with mode `0600`. You can delete it at any time. |
| `server.json` | The API address, so the CLI talks to the same server |

The usage log is not the billing record. For spend, use `/agentic-id-usage` or the `agentic_id_workspace` tool.

## Errors you may see

| Code | What to do |
| - | - |
| `auth.missing_key`, `auth.invalid_key` | Sign in with `/agentic-id-login`, or correct the API key in the plugin options |
| `unreachable` | Check the API URL in the plugin options. Run `/agentic-id-status`. |
| `cap_required` | The call could cost more than 10 credits. Agree a budget and pass `max_credits`. |
| `credits.insufficient` | The workspace balance cannot cover the call |
| `rate_limited` | The plugin waits and retries once. If it persists, slow down. |
| "session budget ... is spent" | Raise **Session credit budget** in the plugin options, or start a new session |

Full list: [Errors](https://docs-agentic-id.icustomer.ai/errors.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.