The chatty command

pip install chatty-lab puts a chatty on your path. Its body is the same Rust the library calls, so what you drive from a terminal and what you drive from Python cannot drift into two different tools.

$ chatty init
$ chatty commit -m "the reader is stricter"
$ chatty push

python -m chatty_lab is the same command said the other way.

The working copy

Unlike a Workdir in Python — which is a handle, because a caller there is already holding a dict — the command keeps a copy on disk for you to edit. It is git’s split, for git’s reason: a working copy is not a version, and telling the two apart is the whole point.

• graph.json the working copy — this is what you edit
• Directoryagents/

  • 8f21….json the definitions the blob pins by id
• Directory.chatty/

  • HEAD which lineage, which branch
  • Directoryobjects/

    • …
  • Directorygraph/

    • …

Why the agents are files beside the graph

A graph blob pins agent_definition_id and nothing else, so the soul, the model and the tools a node runs with are not in it. The platform reads them out of a table and folds them into the version’s name; without the same thing here, a graph committed from a terminal and the same graph committed from a browser would be two versions.

An agent nobody put in agents/ is absent from the pin, not null. Absent means this version predates pinning them; a recorded null means the reference dangled when the version was cut.

The verbs

Every verb takes --at <dir>, which defaults to the current directory and any directory inside it.

Command	What it does
chatty init [--id <uuid>]	Start a workdir here. --id is the lineage this is a working copy of — without it, nothing pushed from here would land on the same one.
chatty status	Where you are, and whether anything would be lost by leaving.
chatty commit -m <msg>	Name what the working copy holds, on the branch you are on. Without -m, the message is read from stdin.
chatty log [<range>]	The versions of this lineage, newest first. Everything by default.
chatty branch <name> [<start>]	Give a name to a version that already exists. <start> defaults to HEAD.
chatty checkout <rev> [-b <name>] [--force]	Go to a branch, bringing what it holds into the working copy.
chatty diff <a> [<b>]	What changed between two versions. <b> defaults to HEAD.
chatty merge <from> -m <msg> [--ours <id>] [--theirs <id>] [--force]	Bring another branch into the one you are on.
chatty remote [<api>] [--id <uuid>] [--workspace <uuid>]	Where this lineage also lives. Said with nothing, it shows what is set.
chatty push [<branch>]	Send a branch to the remote.
chatty pull [<branch>] [--force]	Bring one back, into the working copy.

Leaving an old version

A checkout always ends on a branch, so going back to an old version is spelled as starting a variant there:

$ chatty checkout HEAD~2 -b stricter

Answering a merge’s clashes

--ours keeps this branch’s side of a node or edge the two lines changed differently; --theirs keeps the other. Say it once per id.

$ chatty merge stricter -m "bring it in" --ours reader --theirs e_input__reader

The token

$ export CHATTY_TOKEN=…
$ chatty push

--token exists, but the environment is the way to mean it: a token on a command line is a token in a shell history — and half of what this is for is being driven by something that already has it in its environment.

Set the remote once, and it is remembered:

$ chatty remote https://chatty-lab.com --id 3f47b2c8-… --workspace 91ac…
$ chatty remote

Exit codes

git’s codes, which is what a script already expects.

0	done
1	a verb that compares found a difference
2	it could not be done

$ chatty diff main stricter || echo "they differ"

A whole session

$ chatty init --id 3f47b2c8-4b1a-4f0e-9c2e-77b6f5c1a0d3
  edit graph.json, and put the agents it runs in agents/

$ chatty commit -m "one reader, one pass"
$ chatty remote https://chatty-lab.com
$ chatty push

$ chatty checkout HEAD -b panel
  ... edit graph.json into a three-seat panel ...
$ chatty commit -m "three specialists and a chair"
$ chatty push panel

$ chatty diff main panel
$ chatty checkout main
$ chatty merge panel -m "the panel wins"
$ chatty push

Where to go next

Versioning The same verbs, called from Python.

Sending it to the platform What push and pull actually carry.

End to end The loop this command exists to serve.