Automation and Integrations

Let CORA search and read the web, get notified when it needs you, and run it from scripts.

Searching and reading the web

CORA can search the web and read a page when the answer is not in your project, a library's documentation, an error message nobody has seen before, or an API's current behaviour.

It is subject to the same approvals as everything else: a search or a fetch asks you first, in every mode. Pulling an outside page into the conversation is your decision, not CORA's.

Two limits worth knowing:

1. A search gives titles, links, and short summaries. To read a page properly, CORA fetches it; you will see that as a second step.

2. A fetched page is cut off at 40,000 characters, and the cut is announced in the text, so a page that ends mid-sentence never reads as if the page ended there.

Only web addresses are accepted. cora cannot use this to read files off your disk; that is what its normal file tools are for, with their own approvals.

---

Notifications

When your terminal is not the window you are looking at, cora rings the bell and raises a desktop notification for the three moments you have walked away from:

1. a permission request CORA is blocked until you answer

2. a question the same

3. a turn taking longer than thirty seconds

The notification says what is wanted, not just that something is, so you can decide whether to go back yet.

Only when you are not looking. If your terminal is in front of you, nothing pops up.

To turn them off, either put this in ~/.cora-cli/config.json (or <project>/.cora-cli/config.json for one project):

{ "notifications": false }

or set the environment variable CORA_NO_NOTIFICATIONS=1.

---

Using CORA in scripts

cora works without the interface: one question, one answer, no screen.

cora --run "what does this project do?"
git diff | cora --run "review this change"
cora --run "summarise the failing tests" -m ask

Machine-readable output

cora --run "say hi" --json

You get one JSON object per line: a start line, the streamed text, one line per action taken, and a final result line. It can be read as it arrives, and a run that is interrupted still leaves every completed line readable.

Exit codes

Scripts branch on these, so they are a promise:

Code	Meaning	What to do
0	The turn completed	Read the output
1	The turn or cora itself failed	Look at the log file named in the error output
2	The command was wrong	Fix the command, retrying will not help
3	The environment is not ready	Start the Toolbox, or sign in

3 exists so an automated build can tell "something is broken" apart from "nobody started the Toolbox".

cora --run "$PROMPT" --json > events.ndjson
case $? in
  0) echo "done";;
  2) echo "bad command" >&2;;
  3) echo "start the Toolbox" >&2;;
  *) echo "failed, see the log" >&2 ;;
esac

The one important limit

A script has nobody to approve an edit. So in a script, cora refuses file changes and commands and says so out loud in the output. The turn still runs: cora is told it cannot do that and answers with what it can.

In short: scripted cora is for asking, not for doing. Building things needs the interface, where you are there to answer.