Kelam docs

Install and connect

Kelam is a thin CLI that talks to a Kelam server. The public default server is https://app.kelam.sh; set KELAM_API_URL for your own box.

curl -fsSL https://kelam.sh | sh
kelam --version
kelam login https://your-kelam-host   # optional when using env vars
kelam list

For shared-password deployments, set KELAM_PASSWORD. Use KELAM_WORKSPACE when you need a non-default tenant.

The agent loop

Agents live as files: agent.yaml, scenarios/*.md, and optional Python tools. Every push creates a version; deploy makes that version callable.

kelam create frontdesk             # scaffold + provision a number
kelam create qa-bot --no-number   # browser/direct-agent calls only
kelam verify frontdesk
kelam push frontdesk
kelam deploy frontdesk

New agents speak English, Spanish, and French by default, can switch language mid-call, navigate IVR menus with DTMF, and can use ambient background audio when configured.

Place calls

kelam call reaches phone numbers or other agents. kelam web starts a browser/WebRTC call with no phone number.

kelam call frontdesk +12065550123 --watch
kelam call frontdesk booking-bot       # direct agent-to-agent call
kelam call frontdesk +33612345678 --lang fr
kelam call frontdesk +12065550123 -p "ask about availability this Friday"
kelam call frontdesk +12065550123 -t billing-bot
kelam web frontdesk

Structured extraction

Use --extract / -e when a call should return typed fields, such as price, budget, timeline, a yes/no answer, or a lead grade.

kelam call sales-bot +12065550123 \
  -e "price:number:the quoted price in USD" \
  -e "agreed:boolean:whether they agreed to a follow-up" \
  --watch

The field syntax is name:type:description. Types are string, number, boolean, or enum(a|b|c). Names become keys in call.extracted, so use lowercase identifiers like price or lead_grade.

When fields are attached to a call, the worker gives the agent a live record_field tool. Values the agent logs are available on the terminal CallLog as extracted, with an extractions provenance sidecar.

{
  "extracted": {"price": 42.5, "agreed": true},
  "extractions": [
    {"name": "price", "value": 42.5, "source": "tool", "confidence": null}
  ]
}

For existing calls, or fields the live tool missed, run the backend extractor over transcripts:

kelam extract sales-bot \
  -e "price:number:the quoted price in USD" \
  --since 7d

kelam extract sales-bot \
  -e "lead_grade:enum(hot|warm|cold):lead quality" \
  --overwrite

Follow calls with watch files

Coding agents should avoid holding long streams open. Use --watch; the CLI starts a detached watcher and appends one JSON event per line.

kelam call frontdesk +12065550123 --watch
kelam watch <call_id>
kelam watch                         # attach to the one live call

The last line is always terminal: ended with the full CallLog inline, timeout, or watch_error. If the last line is not terminal, the call is still live.

Humans should use kelam monitor instead: it opens a browser dashboard with live audio, transcript, and hang-up controls.

Transcripts, exports, and stats

kelam calls
kelam calls frontdesk --live
kelam transcript <call_id>
kelam transcript frontdesk +12065550123
kelam export --since 7d -o calls.jsonl
kelam export --format csv -o calls.csv
kelam stats --since 24h

JSON and JSONL exports include complete CallLogs. CSV export includes stable metric columns plus dynamic extracted.<name> columns when structured extraction results are present.

Install the operating guide into your project

The CLI ships a canonical operating guide for coding agents. Print it with kelam skill, or install it where your harness reads instructions.

kelam skill
kelam skill --install

Claude Code users can also install the Kelam plugin:

/plugin marketplace add samsadsam/nousdata
/plugin install kelam@nousdata

Server knobs worth knowing