Working with Claude Code and Codex

Claude Code and Codex can write, test and save Chartnaut scripts through the CLI. chartnaut init gives them a guide to the loop, and every command answers in plain text tables and fixed exit codes they can read. You describe the indicator, definition or study you want; the agent edits the files, runs them on Chartnaut's servers and reads the numbers that come back.

You need the CLI installed and signed in on the machine where the agent runs. The agent uses your login, so it can do anything you can do from the CLI.

An agent can also read the CLI itself: chartnaut/cli on GitHub has the source and an AGENTS.md written for coding agents.

Set up the folder

Run chartnaut init in the folder the agent works in, even one that already has a CLAUDE.md:

$ chartnaut init
chartnaut.json: created
indicators/: created
definitions/: created
studies/: created
CLAUDE.md: added the Chartnaut section at the end (your content is untouched)
AGENTS.md: created
next: chartnaut new indicator my-first-indicator

init never removes or rewrites anything you wrote:

Run init again after you upgrade the CLI. It replaces only the text between the markers and leaves the rest of the file alone. Anything you add inside the markers is lost on the next init, so put your own instructions outside them.

What the guide tells the agent

• Scripts run on Chartnaut's servers, need no market data or build step, and never return raw candles.

• The folder layout and project defaults, and that script.json is never edited by hand.

• The loop below, how to fetch full results and a definition's stored events, and what each failure and exit code means.

• A table of the scripting reference topics. If init could not fetch them, for example before you signed in, the guide tells the agent to run chartnaut docs instead.

The loop

The guide has the agent work the same way on every change:

1. Read the reference with chartnaut docs <topic> before writing code.

2. Create the script with chartnaut new <kind> <slug>, or edit an existing one.

3. Run chartnaut validate <path> and fix every error line.

4. Run it on a short window with chartnaut run <path> --last 30d. Nothing is saved.

5. Read the summary. Blank outputs or zero events usually mean a logic bug, not missing data.

6. Widen the window, then try other instruments with --on BTC,ETH.

7. Save with chartnaut push <path> -m "what changed".

A study is the exception at step 4: it runs by slug after a push, so the agent pushes it first. On a version conflict at step 7, the guide tells the agent to pull and re-apply its change, and to use --force only if you agree to overwrite the version in the app. Saving and versions

How the agent reads full results

The summary run prints is a digest. Every run prints its id, and the agent fetches the rest with it:

chartnaut runs results run_4k2m9x7q1b8z3n5p --all
chartnaut runs results run_4k2m9x7q1b8z3n5p --format csv --all > ema.csv
chartnaut runs results run_8d1q0v5m2k7w3x9a --full

--all returns every point of an indicator or every event of a definition, as JSON or CSV. A study returns its metrics inline and lists its other blocks as omitted with a row count, until --full or --keys asks for them. Adding --json to any command gives the agent the raw response. Runs and results

Exit codes

The agent branches on the exit code rather than parsing text. The guide gives it this table:

Exit 3 is the one you act on: sign in again, fix the key's scopes, or move off Free. Exit 5 usually means the agent's runs have used up your runs at once, which it shares with the app, or your API limits. Errors and exit codes