Setup

A new-org setup runs once. Per-repo setup is fjx init and a commit. The whole thing is roughly thirty minutes if you've used Forgejo before.

1. Create a Forgejo organization

FJX is designed to run against an org, not a personal namespace. Agents are real Forgejo accounts that need to be added to teams with scoped permissions — that's an org-level concept.

Create the org through the Forgejo UI (Site → New Organization). Add your personal account ($FJX_OWNER) to the org as an owner.

2. Create the label set at the organization level

Create the required agent/* lifecycle labels (and the recommended type/* and risk/* sets if you want them) at the org level (<org>/-/labels) so every repo inherits them. Make the agent/* labels exclusive so only one can be applied at a time.

See Labels for the full table — names, suggested colors, and meaning.

3. Create the agent user accounts

Create one Forgejo user per role. Names are convention, but the prompts and fjx defaults assume:

• agent-pm
• agent-dev
• agent-qa
• agent-build (planned; skip for now)

Each needs:

• A real email address (Forgejo requires one; a +alias on your own domain works fine).
• A personal access token with repo scope (and write:wiki for agent-pm). Store these tokens — the agent will use them via FJX_TOKEN.

4. Add the agents to teams with scoped permissions

Create org teams that grant just what each role needs. A reasonable starting matrix:

The human ($FJX_OWNER) is an org owner; they hold the trust map and the final-merge authority. No team membership needed beyond that.

5. Install fjx

Requires Deno 2.x.

deno install -gA -n fjx jsr:@tfks/fjx

Verify:

fjx --version

Install fjx on every machine that will run an agent — typically each agent gets its own host (or its own container) so cycles don't step on each other.

6. fjx init in each repo

In every repo the agents will operate on:

cd <repo>
fjx init

This scaffolds slash-command wrappers in .agents/commands/fjx/ that delegate to fjx <role>. It's idempotent — safe to re-run. Use --force to overwrite files that have drifted from the stub.

Then commit the scaffold:

git add .agents AGENTS.md
git commit -m "chore: bootstrap fjx agent wrappers"
git push

Committing matters: the agents read these files from the repo when they run, so they have to be on whatever branch the agent checks out.

7. Install a coding agent

FJX has been tested with Claude Code on a Claude Pro plan. The scaffold from fjx init is Claude Code-specific.

Install Claude Code per the official instructions. Then, from each agent's machine:

# Configure the agent's identity (one-time)
export FJX_TOKEN=<the agent's personal access token>
export FJX_CACHE=.fjx-cache-<role>.json  # e.g. .fjx-cache-dev.json

# Run one agent cycle
just agent-dev   # or agent-qa, or agent-pm

Each invocation is a one-shot: the agent claims work, executes one cycle, and exits. An external executor (cron, scheduler, supervisor) is responsible for re-invoking the agent on its cadence. The just agent-* recipes in this repo's Justfile are concrete examples of how to drive a single cycle; copy them into your own project's Justfile and adjust.

For unattended operation, run fjx supervise under a process supervisor — see Supervisor setup for systemd, launchd, and tmux recipes. Per-project overrides (container images per role) go in fjx.json at each project root.

Other agent harnesses (Codex, Aider, etc.) should work in principle — the agent just needs to be able to read prompts from fjx <role> prompt, run shell commands, and edit files — but the wrappers fjx init lays down are tested against Claude Code.

8. Profit!

From here:

1. File an issue, give it the agent/new label.
2. Start agent-pm (it'll write the initial brief and assign to agent-dev).
3. Start agent-dev (it'll claim the issue and open a PR).
4. Start agent-qa once there's a PR to review.

Sit back and watch your bank balance sky rocket! More realistically, things will go wrong. The agents will record their blockers in ledgers on the issue. Read the ledgers, fix the prompts, try again. Encoding catches into the prompts is the work — see the senior-practitioner chair.