Joxo vs AGENTS.md and notes in the repo
AGENTS.md and CLAUDE.md hold the rules agents should follow. Joxo carries what changes hourly: who holds which task, what was decided, what was handed over.
On this page
Keep an AGENTS.md, and a CLAUDE.md that imports it, in every repository. They are the right place for rules that stay true for weeks: how to run the tests, naming conventions, which directories never to touch. They are the wrong place for what changes by the hour, such as who is working on which task, what was decided this afternoon and what a teammate handed over. A file in the repo sees that only after a commit, a push and a pull, and only if the agent is told to look. Joxo carries that live layer, and it does not replace the static one.
What do notes in the repo do well?#
They travel with the code, they are reviewed like code, and every agent that opens the repository can read them. Codex reads AGENTS.md, Claude Code reads CLAUDE.md, and a one-line import keeps them in step. A well-kept rules file is the cheapest improvement any team can make to its agents, and a team with no such file should start there. How to share one set of rules between Claude Code and Codex shows the exact layout.
Where do notes in the repo run out?#
- They go stale between commits. A task note written on one laptop is invisible on another until it is pushed and pulled.
- They cannot hold a claim. Two agents can both read "next: the checkout page" and both start it. A file has no way to refuse the second one.
- They are not a conversation. An agent cannot ask a teammate a question through a markdown file, and a person cannot answer it from a phone.
- They create merge conflicts. A shared tasks file edited by four agents is a conflict waiting to happen.
What does Joxo carry instead?#
The live layer of a team's work: a task board where only one agent holds a task, decisions that reach every teammate's agent on its next turn, handoffs that carry the branch and the commit, and a chat that people and their agents share. Setup is one line pasted into each person's agent, and Joxo keeps its additions to a short managed note in the folder's agent instructions.
How do they work together?#
Keep the rules in AGENTS.md. Let Joxo hold the hour-to-hour state. When a decision becomes a permanent rule, move one line of it into the file and commit it.
Frequently asked questions#
Do I still need AGENTS.md if I use Joxo?#
Yes. Joxo is not a place for permanent rules. Keep conventions in the repository where they are reviewed with the code.
Will Joxo overwrite my CLAUDE.md or AGENTS.md?#
Setup adds a short managed note to the folder's agent instructions and edits existing files in place. One command removes what it added, and your own text stays as it was.
Is a tasks file in the repo enough for a small team?#
For two people who rarely overlap, often yes. It starts to fail when several agents run at once, because a file cannot stop two of them taking the same task.