axon job

Hand a piece of work to an agent and get on with something else.

axon job create -p "update the changelog for the last three commits"

This is the other half of axon <agent>. That command is a conversation — you are present, watching it think. A job is delegation: you say what you want once, it happens without you, and you deal with the result whenever you come back.

A job is not an agent run

An agent run is one attempt. A job is the thing you asked for, and it survives its attempts — retry it and the thread you have been reading stays intact.

That distinction is why jobs have their own commands rather than being flags on run.

Creating

axon job create -p "do the thing"
axon job create "do the thing"                    # the bare form works too
axon job create -p "do the thing" -t "Changelog"  # with an explicit title

The title is optional on purpose. The flow this exists for is typing one instruction and thinking about nothing else, so a missing title is taken from the first line of the content.

Where the work happens is captured when you create the job, from the directory you were standing in. It is never resolved later — a job that worked out its own directory at run time would act on whatever tree happened to be current, which is not the one you meant.

axon job create -p "run the linter" --cwd ~/code/api

Listing and reading

axon job list           # what still wants something from you
axon job list --all     # including everything already dealt with
axon job show 9c533cee

Jobs are addressed by a short ref — the first eight characters of the id, as shown by list. A longer prefix works too. An ambiguous one is refused rather than guessed at, because the verbs that take a ref include cancel.

Two states, not one

Every job carries two independent answers:

They are separate deliberately. If they were one field, either the agent would clear your list on your behalf, or you would have no way to clear it yourself.

blocked is the state that makes this useful: the agent has hit something only you can answer, and that is what axon job list puts in front of you.

Answering

axon job say 9c533cee "use the gb layout"

Replying to a blocked job is what unblocks it. On a running job it is simply another turn in the conversation.

Finishing

axon job done 9c533cee      # you are satisfied with it
axon job cancel 9c533cee    # stop it
axon job retry 9c533cee     # run it again, same thread

done is your acknowledgement, not the agent's report. An agent saying it has finished and you agreeing that it did what you wanted are different claims, and only the second one clears the job from your list.

Agents can create jobs. They cannot close them.

An agent may run axon job — delegating a piece of work to another agent is a real thing to want. But done, cancel and retry belong to whoever asked for the work:

acknowledge is a person's decision — an agent cannot acknowledge a job

Without that rule the list would arrive pre-ticked by the thing that did the work, which is the same as having no list.

You are recognised as a person by being signed in — see axon login. An agent is recognised by the session identity every agent process carries. A command run with neither can still create jobs, and still cannot close them.

Options

Where jobs live

The daemon owns them, so a job outlives the terminal that created it — closing the window does not take the work with it.

Jobs are stored as an append-only log of everything that happened, and their state is read back from that log rather than being kept as a field. It is what lets the record be shared across machines later without two writers overwriting each other.