# 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.

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.

Create these four labels at the org level (<org>/-/labels) so every repo inherits them. Make these exclusive so that there can only be one agent/* label applied at a time. The colors are suggestions; the names are required. 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.

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.

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.

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.

In every repo the agents will operate on:

cd <repo>
fjx init

This scaffolds the Claude Code wrappers (.claude/agents/, .claude/commands/) that delegate to fjx <role> prompt. It's idempotent — safe to re-run. Use --force to overwrite files that have drifted from the stub.

Then commit the scaffold:

git add .claude 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.

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=.fj-cache-<role>.json  # e.g. .fj-cache-dev.json

# Run the agent's bootstrap loop
just agent-dev   # or agent-qa, or agent-pm

The just agent-* recipes in this repo's Justfile are concrete examples of how to drive each role; copy them into your own project's Justfile and adjust.

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.

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.