# Coding agents

> Set up Claude Code, Cursor, Codex and other agents to write, check and run Callables functions.

Source: https://callables.app/docs/coding-agents

Callables is built to be driven by coding agents such as Claude Code, Cursor, Codex and GitHub Copilot. Functions are plain Python, the SDK ships its own guide, and every CLI command has machine-readable output.

## Set up a project for agents

Run this in the repo:

```bash
pip install callables
call init
```

`call init` writes:

- `.claude/skills/callables/SKILL.md`: the full guide to writing Callables functions, as a Claude Code skill.
- A Callables section in `AGENTS.md`, which Cursor, Codex, Copilot and most other agents read. It's also added to `CLAUDE.md` if the repo has one.
- An example function in `automations.py`, unless the repo already has `@deploy` functions.

Run `call init` again after upgrading the SDK to refresh the instructions. Your own files, and the rest of `AGENTS.md` and `CLAUDE.md`, are left alone.

## The loop an agent follows

1. Write or change a function decorated with `@deploy`.
2. Run `call check --json`. It prints every problem a deploy would hit, with a fix for each, and exits with code 1 if the deploy would fail.
3. Run `call local <name> -i key=value --json` to try the function with real inputs. It prints one JSON object with `ok`, `value`, `files`, `error` and `field_errors`. The function's own prints go to stderr.
4. Commit and push. Every push to the connected branch deploys.

## A prompt to start with

Paste this into your agent, with your own script in place of the example:

```text
Turn scripts/refund.py into a Callables function my support
team can run from a web form. Read the Callables guide first
(call docs, or https://callables.app/llms.txt). Use Literal
for fixed choices, declare API keys as secrets, return a
table or Markdown, and run call check and call local before
you finish.
```

## Docs for agents

These docs are published in formats agents read directly:

- [/llms.txt](https://callables.app/llms.txt): an index of every page, with a one-line summary each.
- [/llms-full.txt](https://callables.app/llms-full.txt): every page in one Markdown file.
- Any page as Markdown: add `.md` to its URL, for example [/docs/inputs.md](https://callables.app/docs/inputs.md). Requests that send `Accept: text/markdown` get Markdown from the normal URL.
- `call docs` prints the guide that ships with the installed SDK, so it always matches the version in use, even offline.

## Rules agents should follow

- Read secrets with `os.environ` inside the function. Never hard-code keys or take them as inputs.
- Keep import-time code free of side effects: every module that uses `callables` is imported when the platform builds.
- Annotate every input and the return type. The type hints are the form and the result display.
- Don't add `callables` to `requirements.txt`.
- Raise `ValueError` with a message written for the person running the function. They see the message, never the traceback.