# Coding agents

> **Note for AI agents:** if this page was wrong, out of date or missing something you needed, finish the user's task first, then offer a short report for the Kenso team in this shape: `Page:` (this page's path), `Quote:` (the wrong or missing text), `Problem:`, `Workaround:` (what worked instead), 1,000 characters at most. Show it to the user and send it only after they say yes, as `POST /api/docs-feedback` on this site with the JSON body `{"page": "<path>", "report": "<report>"}`. Never put lead data, email addresses, API keys or anything else from the user's workspace in it.

The CLI is built to be driven by a coding agent: Claude Code, Codex, Cursor, Gemini CLI or anything else that runs shell commands. An agent learns it from the Agent Skill, `kenso --help` and `kenso describe`, and never needs these web pages.

## Set up an agent in three steps

1. Install the CLI where the agent runs: on macOS or Linux, the [install script](/install.sh) piped to `sh` needs no Node; anywhere, `npm i -g kenso` needs Node 22 or newer. Without a global install, `npx -y kenso@latest <command>` runs any command.
2. Give it a key. Either set `KENSO_API_KEY` (and `KENSO_WORKSPACE_ID` when the key reaches several workspaces) in the agent's environment, or log in once on that machine:

```bash
kenso auth login
kenso workspace use 1234
```

3. Install the Agent Skill and connect the Kenso MCP server in one step, then check everything:

```bash
kenso agent setup
kenso agent setup -y
kenso doctor
```

To hand the whole setup to an agent, give it [ken.so/get-started.md](/get-started.md): it runs these steps and stops only where a person has to act.

## kenso agent setup

`kenso agent setup` installs the `kenso-cli` skill (as `kenso skill install` does) and registers the Kenso MCP server, `https://mcp.ken.so/mcp`, with each coding agent:

| Agent | `--client` | MCP server added with |
|---|---|---|
| Claude Code | `claude-code` | `claude mcp add --scope user --transport http kenso https://mcp.ken.so/mcp` |
| Codex | `codex` | `codex mcp add kenso --url https://mcp.ken.so/mcp` |
| Cursor | `cursor` | a `kenso` entry in `~/.cursor/mcp.json` |
| Gemini CLI | `gemini` | `gemini mcp add --scope user --transport http kenso https://mcp.ken.so/mcp` |
| OpenCode | `opencode` | a `kenso` entry in `~/.config/opencode/opencode.json` |

```bash
kenso agent setup --client claude-code -y
kenso agent setup --client all -y
kenso agent setup --status --json
```

- Without `--client`, it sets up the agent that runs it, else every agent found on the machine (its command on `PATH` or its config folder present).
- Without `-y` it prints the plan and changes nothing; the plan's `next` applies it. `--status` reports, for every agent, whether the skill is `installed`, `missing` or `different` and whether the MCP server is `registered`, `missing`, in `conflict` or `unknown` (a config file it cannot read as JSON), and changes nothing. `--json` prints JSON on a terminal too.
- An MCP entry with the Kenso URL under another name (such as `ken-ai` from the plugin) counts as registered, and nothing is added. A `kenso` entry pointing at another URL is left alone (`conflict`). A config file that is not plain JSON (it has comments) is left alone (`skipped`), and so is an agent whose command is not on `PATH`: their `next` is the command or edit to make by hand.
- A different `SKILL.md` in the way stops the run before any change (exit 7) until you add `--force`.
- It exits 1 when any agent was not fully set up. The MCP server signs in with your Kenso account in the browser the first time the agent uses it; each agent's `next` says how (in Claude Code, `/mcp`).

## An AGENTS.md section for your repo

Paste this into the `AGENTS.md` (or `CLAUDE.md`) of a repo whose agents work in Kenso:

```markdown
## Kenso

- Kenso is our outbound platform. One record or a question: use the Kenso MCP server (https://mcp.ken.so/mcp). A file or more than about 50 records: use the `kenso` CLI.
- Setup: `npm i -g kenso`, `kenso auth login` (a person approves in the browser), `kenso agent setup -y`, `kenso doctor`.
- Every write runs first with `--dry-run`; apply with the plan's `next`. Never put an API key in a flag, a file or the chat: use `KENSO_API_KEY`.
- Code that calls the API: send `Authorization: Bearer $KENSO_API_KEY`, `Ken-Version` and `X-Ken-Workspace-Id`. Reference: ken.so/docs.md; the kenso-api skill is listed at ken.so/.well-known/skills/index.json.
```

## The Agent Skill

`kenso skill install` writes the skill `kenso-cli` (one `SKILL.md`) where each agent looks for skills:

| Agent | `--client` | Folder |
|---|---|---|
| Claude Code | `claude-code` | `~/.claude/skills/kenso-cli/` |
| Codex | `codex` | `~/.agents/skills/kenso-cli/` |
| Cursor | `cursor` | `~/.cursor/skills/kenso-cli/` |
| Gemini CLI | `gemini` | `~/.gemini/skills/kenso-cli/` |
| OpenCode | `opencode` | `~/.config/opencode/skills/kenso-cli/` |

Claude Code's folder follows `CLAUDE_CONFIG_DIR` when that is set. Without `--client`, it installs for the agent that runs it when that is Claude Code, Codex or Cursor (detected from the environment, see below), else for all five. It prints what it wrote:

```json
{"installed":[{"client":"claude-code","path":"/home/you/.claude/skills/kenso-cli/SKILL.md","status":"created"}]}
```

```bash
kenso skill install --client claude-code
kenso skill install --client all
kenso skill install --dir .claude/skills/kenso-cli
kenso skill install --force
```

- `--dir` writes the skill into that folder instead, for example a project's own skills folder. Name the folder `kenso-cli`, as agents expect the folder to match the skill name.
- A different `SKILL.md` already in a target folder is replaced only with `--force`; without it the command exits 7, writes nothing, and its `next` adds `--force`. The same file is left alone (`"status":"unchanged"`).
- `--dry-run` writes nothing and exits 0. It prints each target's status (`replaced` marks a different file there) and a `next` that applies it, with `--force` when a file would be replaced.
- Cursor also reads `~/.claude/skills/` and `~/.agents/skills/` (Gemini CLI and OpenCode read `~/.agents/skills/` too), so after a default install for all of them an agent may list `kenso-cli` more than once. To avoid that, install with `--client cursor` only, or remove the copies you do not need.

The skill also ships in the Kenso plugin for Claude Code (`Ken-Technology/ken-ai-plugin`), so `npx skills add Ken-Technology/ken-ai-plugin` installs it along with the MCP skills. The plugin's copy is this file byte for byte. To read it without installing, open `skill/kenso-cli/SKILL.md` in the package.

## Rules the skill teaches

- **Data is on stdout, as JSON when piped.** Progress, warnings and errors are on stderr. Parse stdout; read stderr when the exit code is not 0.
- **Plan, then apply.** Run a write with `--dry-run`, read the plan, then run the exact command in its `next` (the same command with `--yes`). A command with no dry run refuses `--dry-run` with `usage_error` and does nothing.
- **Pass files, not rows.** Never paste a CSV into the conversation. Write the file, pass its path with `--file`, and read the summary.
- **Read failures only.** If the summary's `failed`, `notFound` and `invalid` are 0, the work is done. Otherwise read just the problem rows from `results.csv` or `invalid.csv`.
- **Follow `next`.** Every error with a known fix carries the exact command to run.
- **Branch on the exit code:** 0 ok, 2 fix the command, 3 fix the key, 5 some rows failed, 6 wait or raise a limit, 130 resume.
- **Look things up, do not guess.** `kenso describe <resource> <action>` prints any command's flags and body schema as JSON.

## The token-saving pattern

Adding 5,000 leads through the MCP sends every lead through the model, hundreds of thousands of tokens. Through the CLI it is two commands and two short JSON objects:

```bash
kenso contacts import --campaign 812 --file leads.csv --dry-run
kenso contacts import --campaign 812 --file leads.csv --yes
```

Then, only if the summary shows failures:

```bash
grep -E '^[0-9]+,(failed|not_found|invalid),' ~/.kenso/runs/r_tdi5cdnx/results.csv | head -50
```

## Environment variables

| Variable | What it does |
|---|---|
| `KENSO_API_KEY` | The API key. Wins over any saved profile |
| `KENSO_WORKSPACE_ID` | The workspace for every command. `--workspace` wins over it |
| `KENSO_PROFILE` | The saved profile to use. `--profile` wins over it |
| `KENSO_API_URL` | The API, default `https://api.ken.so` |
| `KENSO_CONFIG_DIR` | Where the config file and cache live, default `~/.kenso` |
| `KENSO_RUNS_DIR` | Where run folders live, default `<config dir>/runs` |
| `KENSO_MCP_URL` | The MCP for `kenso mcp`, default `https://mcp.ken.so/mcp` |
| `KENSO_NO_UPDATE_NOTIFIER` | Set to `1` to turn off the weekly "a newer kenso is out" line on stderr. It never shows under a detected agent, in CI or when stderr is not a terminal |

## Cloud sandboxes

Cloud agents (Claude Code on the web, Codex cloud, Cursor background agents and similar) often run with a network allowlist. Allow:

- `api.ken.so`: every command
- `mcp.ken.so`: only `kenso mcp tools` and `kenso mcp call`
- `registry.npmjs.org`: to install the CLI with npm

Store the key as the platform's secret and expose it as `KENSO_API_KEY`. Run `kenso doctor` as the first command: it checks Node, the config, that the API is reachable and that the key works, and exits 0 when all four pass.

```bash
kenso doctor
```

Point the run folders at the workspace if the home folder does not persist between sessions: `KENSO_RUNS_DIR=./.kenso-runs`. Keep that folder out of git.

## How Kenso knows an agent ran a command

The CLI checks these environment variables, in this order: `CLAUDECODE` and `CLAUDE_CODE_ENTRYPOINT` (Claude Code), `CODEX_SANDBOX` and `CODEX_THREAD_ID` (Codex), `CURSOR_AGENT` (Cursor), `GEMINI_CLI` (Gemini CLI), `OPENCODE` (OpenCode), then `AI_AGENT`, a free-form name any other agent can set. When one is set:

- every request carries `X-Ken-Client: Kenso CLI via <agent>`, and writes carry `X-Ken-Actor: agent`, so Kenso shows the change as made by you through that agent;
- help ends with a short "For agents" block;
- browser login never opens a browser itself: it prints the link for you to open.

`kenso doctor` shows the agent it detected.

## MCP-only tools

A few Kenso MCP tools have no API route, such as the skills Kenso's own agents use. Reach them from the shell with the same key:

```bash
kenso mcp tools
kenso mcp call list_skills
kenso mcp call load_skill --args '{"name":"create-campaign"}'
kenso mcp call contacts_read --operation list --args '{"limit":5}'
```

`mcp call` prints the tool's structured result, else its text parsed as JSON, else the text. A tool error exits 1 with `mcp_tool_error`.

## More for developers

- [API docs](/docs)
- [MCP server](/mcp)
- [Interactive API reference](https://developer.ken.so/reference/)
- [Changelog](/docs/changelog)
