---
name: kelam-operate
description: Operate Kelam voice AI agents from the terminal — create/edit/deploy phone agents, place real calls, follow live calls, batch-call a list, capture structured fields with --extract / kelam extract, send SMS. Use when the user says "call this number", "have my agent call...", "batch call these leads", "follow/watch the call", "extract/capture fields", "what did the call say", "text them back", or mentions kelam agents at all.
---

# Operating Kelam

The `kelam` CLI is the whole interface: it drives real phone calls end to end and
prints JSON whenever output is piped. The **canonical operating guide ships inside the
CLI** and always matches the installed version — read it first and follow it:

```bash
kelam skill
```

(`kelam` missing or erroring? The `kelam-setup` skill in this plugin installs and
configures it. After setup, `kelam skill --install` plants this guide in the project
for every coding agent — AGENTS.md, Claude skill, Cursor rule, Copilot instructions.)

The two things people get wrong, inlined so you never do:

**Follow live calls through watch files, never by blocking.** `kelam call <agent>
<number> -p "<goal>" --watch` returns immediately with a `watch_file` path; a detached
watcher appends each call event to it as one JSON line. Read or tail the file between
other work. The last line of a finished file is always terminal — `"ended"` carries
the complete CallLog (full transcript, recording, cost, and any `extracted` fields)
inline. `kelam watch <call_id>` attaches to a call already in progress; bare
`kelam watch` attaches to the single live call. `kelam monitor` is for humans
(browser, live audio) — offer its link to the user, never open it yourself.

**Steer a call per-call, not by redeploying.** `-p "ask about their email, budget, and
timeline"` seeds THIS call only. Use `--extract` / `-e` for structured data you need back:
`kelam call <agent> +1206... -e "budget:number:their budget in USD" -e
"timeline:string:their timeline" --watch`. The agent gets a live `record_field` tool and
logs values onto `call.extracted` as soon as it hears them. Fields it misses are filled by
the janitor backstop when enabled, or on demand with `kelam extract <agent> -e ...`.
Editing the agent's files (`agent.yaml`,
`scenarios/*.md`, `tools/*.py`) is for durable behavior and requires
`kelam verify && kelam push && kelam deploy`.

Batch calling: loop `kelam call ... --watch` over the list (the server queues past its
concurrency cap — over-placing is safe, `kelam queue` shows what's parked), keep the
watch-file paths, then sweep them for `ended` lines and harvest `call.extracted` /
transcripts. For old calls or missed fields, run `kelam extract <agent> -e
"field:type:description" --since 7d`; it persists results back onto the CallLog.

Analysis or dashboards from call data → the `kelam-viz` skill in this plugin
(`kelam export` / `kelam stats` are the feeds).