What is a background coding agent?

An agent that works on its own copy of your repository on someone else’s machine while you do something else: Cursor’s cloud agents (once called background agents), Codex in the cloud, Claude Code on the web. It hands back a branch or a pull request when it’s done.

Why do background agents guess?

Because nobody is watching when they hit a fork. A question waits until you look again, so most agents pick something and carry on. A brief that answers the forks ahead of time, and says what to do with the rest, removes most of the guessing.

Where does the brief go?

Rules that hold for every task go in the repository’s AGENTS.md (Codex reads it for project commands; Cursor and most other agents read it too) or CLAUDE.md for Claude Code. What’s particular to this task goes in the task prompt.

Can a background agent read Cachejay itself?

This guide doesn’t assume it can: a cloud agent runs on the vendor’s machine, not your Mac. You gather the context first, with an agent or chat app that’s connected to Cachejay, and hand the agent the result.

What should it do when it’s stuck?

Not guess. Say so in the brief: write the question in the pull request description, take the choice that’s easiest to undo, mark it, and carry on with the rest.

Brief a background coding agent so it doesn’t guess

Why background agents guess

A background agent clones your repository into a machine of its own, runs your setup, works through the task and hands back a branch or a pull request. That’s the point: you can close the laptop. It also means that when the agent hits a fork (which plan is the default, whether the old endpoint can go, who the email is from), you aren’t there. The question waits until you look again, or the agent picks something and builds on it.

What it does have is what’s in the repository and what you typed into the task. The repository has the code and its instructions. It rarely has the decisions made outside it: on a call, in a thread, in another agent’s session last week. That gap is most of what goes wrong. More on the kinds of questions agents ask: what an AI agent should ask you.

What a brief needs

The goal, as the result you want, not the steps.
What’s already decided, each with where and when it was decided, so the agent doesn’t reopen it and you can check it.
What done means: what you’ll check when it comes back.
What’s off limits: files, services or keys it mustn’t touch.
What to do when stuck: write the question down where you’ll see it, take the choice that’s easiest to undo, and carry on. This line does the most good, because it turns a silent guess into a question you can answer in a second.

Rules that hold for every task belong in the repository’s instructions: AGENTS.md, which Codex reads for the project’s commands and most other agents read too, or CLAUDE.md for Claude Code. Which file does what: AGENTS.md vs CLAUDE.md. The decisions for this task go in the task itself.

Gather it before you start

The decisions are the hard part to write down, because you have to remember them. If you use Cachejay, it already has them: your calls, transcribed with no bot, what you read and wrote, and your agents’ sessions, filed by project. Ask an agent or chat app that’s connected to it (Claude Code or Codex on your Mac, or Claude and ChatGPT on the web) to write the brief:

› write a brief for a background agent: build the pricing page for acme. decisions with sources, what done means, open questions
  ⎿ cachejay · project_brief
Already decided:
- Annual plan $99, starting Nov 3 (Acme call, Oct 13)
- USD only for now (Slack, Oct 15)

Open questions (nobody has decided):
- Does the team plan have a seat minimum?
- Monthly price shown, or annual only?

That’s a made-up example, but the shape is the useful part: what’s settled, with sources, and what isn’t. Answer the open questions now, before the agent starts, and paste the result into the task. Thirty seconds of answering here saves a pull request built on a guess.

If a question comes up that you can’t answer yet, leave it in the brief as open. The “when you’re stuck” rule tells the agent what to do with it.

A brief you can copy

## Task brief
Goal: the plain result, one or two sentences.

Already decided (don't reopen):
- Annual plan is $99, starting November 3. (Acme call, Oct 13)
- Prices show in USD only for now. (Slack, Oct 15)

Done means:
- The pricing page shows both plans; checkout works in test mode.
- Tests pass; no new warnings.

Don't:
- Touch billing webhooks or production keys.
- Rename anything public.

When you're stuck:
- Don't guess a product decision. Write the question under
  "Open questions" in the PR description, take the option that's
  easiest to undo, mark it with TODO(question), and keep going.

Keep it short. A brief that runs to pages gets skimmed by agents as well as people. Five decisions with sources beat a pasted transcript.

When the pull request comes back

Read the open questions first. They’re the agent’s guesses, marked. Answer them, and either fix the code or confirm the guess.
Check the decisions it used. If one was out of date, the brief had an old answer. Say what’s true now to an agent connected to Cachejay, so the next brief has it right. Why old answers linger: why AI memory goes stale.
Let your local agent report back. When Claude Code or Codex on your Mac reviews and merges the work, it tells Cachejay what’s done, decided and next, so the project’s status stays current for the next task.

Agents on your own Mac can ask Cachejay directly instead of waiting on you: stop Claude Code and Codex asking what you already know.

Sources: Cursor cloud agents · Codex cloud environments · Codex internet access · Claude Code on the web. Checked October 2026. Something out of date? Email hello@cachejay.com.