axon job

A job is one thing you want done. It holds a brief, an append-only log of everything that has happened to it, and the runs an agent has made against it.

axon job                                      # what is still open
axon job create "the session tokens never expire"
axon job <ref>                                # show one
axon job <ref> -ac "try the lazy check first" # comment, starting a new run
axon job <ref> -us done                       # close it

The grammar

Two rules cover the whole surface:

The reference always sits immediately after job, the same way it does for agents:

axon <ref> -p "…"
axon job <ref> -ac "…"

create and list are the only verbs, because they are the only two operations with no job to name.

The workspace

Jobs live beside the code they are about, in .agents/work inside the repository. That is what makes a job travel with the checkout: clone the repo and you have the work, its history and its evidence.

.agents/work/
├── 9c533cee-….jsonl      one job, one append-only event log
├── auth-tokens.jsonl     a job created with a chosen id
└── attachments/          content-addressed, shared across jobs

Use --cwd to act on another repository's jobs:

axon job --cwd ../other-repo
axon job auth-tokens --cwd ../other-repo

A reference can be a full id, or any unambiguous prefix of one. An ambiguous reference fails and lists what matched; Axon never guesses.

Create

axon job create "the session tokens never expire"
axon job create "rewrite the ingest worker in Rust" -t "Rust ingest"
axon job create "audit the public endpoints" --agent @axon/zeno
axon job create "lint stays clean" -ui lint-health
axon job create "the layout breaks at 900px" -aa ./screenshot.png

The brief leads, because creating a job is the one moment where what you want matters more than what it is called. A title is derived from the brief unless -t gives one.

Creating a job starts a run. The agent picks it up immediately.

Chosen ids

-ui names the job, so auth-tokens is both its filename and its reference:

axon job create "tokens never expire" -ui auth-tokens
axon job auth-tokens -ac "found it"

An id is set once and never changes. It is the log's filename and the address every other surface holds, so renaming one later orphans anything pointing at it. -ui is available on create and nowhere else. Use -ut to change the title, which is only a label.

Show and list

axon job                          # open jobs
axon job list --all               # including closed
axon job list --json
axon job <ref>                    # one job, with its thread
axon job <ref> --json

A bare reference with no flags shows the job. A job leaves the default list when a person marks it done — not when an agent finishes, which is a different thing.

Update

axon job <ref> -ub "what the work actually is now"
axon job <ref> -ut "a clearer title"
axon job <ref> -us done
axon job <ref> -us open

The brief states the work as now understood and is meant to be rewritten as that understanding moves. The previous wording is kept in the log, so editing it never loses what was said before.

-us takes only done and open, because those are the only two states a person declares. How a run is going is a fact about a process and is never set by hand — see Runs.

Append

axon job <ref> -ac "try the lazy check before adding a sweeper"
axon job <ref> -aa ./screenshot.png
axon job <ref> -ac "here is the failure" -aa ./run.log -aa ./trace.png

A comment starts a run. It is not a remark filed for later — it is how you steer the work, and answering a blocked agent with -ac is what unblocks it.

-aa attaches a file to the entry. It repeats, because several files can belong to one thought. With no -ac, the attachment is the whole entry — sending a screenshot with nothing to add is a normal thing to do.

Attachments are stored by the hash of their content, so the same file attached twice is stored once, and they are committed alongside the code. A job that travels with the checkout brings its evidence. The limit is 25MB per file.

Runs

An agent's attempt at a job is a run, and a job may have many. A run ends in one of two things:

Only a proposal is waiting on a decision, which is what makes the difference worth keeping.

axon job <ref> --cancel           # stop the run that is going
axon job <ref> --retry            # start another against the same job

A run can also block mid-flight, which is different from ending: the agent is waiting on an answer and resumes when it gets one. Reply with -ac.

This is the second axis, and it is deliberate. --cancel and --retry act on a run; -us done is you saying you are finished with the job. An agent may report that its work is complete, and only a person can close a job — otherwise everything would arrive already ticked off by the thing that did it.

Schedules

A job with a recurring trigger is standing work — the same job, with something other than a person pulling the trigger.

axon job <ref> --every "0 3 * * *" --agent @axon/barry.mk3 -p lint-sweep
axon job <ref> --every "0 * * * *" --agent @axon/zeno -p typecheck --context recent
axon job <ref> --pause
axon job <ref> --resume

--every is a five-field cron expression. --context decides how much of the job each run is told about:

brief is the default and is what keeps a loop affordable: a standing check like "is coverage above 80% today" does not depend on what it was three weeks ago, so sending the whole log would grow every run's cost forever for nothing.

Pausing suspends the trigger without losing how it was set up, which is usually what you want — a loop you are not running now is one you will want back.

Composing

Flags combine, and one invocation is one atomic pass:

axon job auth-tokens -ub "tokens are weak AND immortal" -ac "widened the scope" -aa ./repro.png
axon job auth-tokens -ac "good, ship it" -us done

They are applied in a fixed order rather than the order typed: updates, then appends, then schedule changes, then run control, then status. So -ac "…" -us done always means "say this, then close it".

Options