fjx

Forgejo Accelerated

FJX is an opinionated workflow & agent harness to help teams build software in a way that is both natural & observable to humans while allowing for agent acceleration. fjx is a CLI to the Forgejo API that helps agents perform their work safely & efficiently.

It is very much a work-in-progress and heavily opinionated. Enjoy yourself. Take only what you need from it.

Install

Requires Deno 2.x.

# Install as `fjx` on PATH
deno install -gA -n fjx jsr:@tfks/fjx

# Or run ad-hoc without installing
deno run -A jsr:@tfks/fjx --help

Setup

just setup   # check prereqs, configure git hooks, cache deps, copy .env
just         # list available recipes
just dev     # run with file watching

Environment variables

Variable	Required	Purpose
FJX_CACHE	yes (agents)	Path to the JSON cache file used for labels, PM sweep checkpoints, and current-item pointer. Set per-role (e.g. .fj-cache-dev.json).
FJX_TOKEN	one of the auth vars	Forgejo personal access token (preferred).
FJX_USERNAME	one of the auth vars	Forgejo username for HTTP Basic auth.
FJX_PASSWORD	one of the auth vars	Forgejo password for HTTP Basic auth.

Auth priority: FJX_TOKEN → FJX_USERNAME/FJX_PASSWORD → credentials in the cache file.

Layout

• src/main.ts — entry point
• Justfile — task runner
• runbooks/ — operational workflows (also exposed as /runbooks:<name> slash commands)
• wiki/ — repo-local memory
• AGENTS.md — operating manual for AI agents (and humans)
• .forgejo/workflows/ — CI/CD