fxbot
AGENTS.md17 starsChanged 3 days agoApache-2.0View on GitHub
Read CONVENTIONS.md before changing code. CLAUDE.md points here. This file is the instruction source for coding agents. fxbot is AI assistants that do real work, built your way: bots that chat, remember, work on a computer of their own, and run tasks on a schedule, on any model, hosted or local, for one person on a machine of their own. It's a small core plus plugins, like Pi. The core is what every bot needs, what plugins plug into, and…
- Reads credentials
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 32,671 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository6 other files it gives its agents.
- packages/AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- engineeringSkill
- naive-panelSkill
- prep-releaseSkill
- show-meSkill
The file
We split this AGENTS.md into the rules it gives an agent
6 rules. About 0 are common, 3 are distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈3
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 3
Read CONVENTIONS.md before changing code.
- Distinctive: line 35
Prefer the smallest change that meets the task.
- Very specific: line 44
Never put a secret in the page or in @fxbot/sdk/client.
- Distinctive: line 47
Write "Hackers in the Loop" in full if that name is needed.
- Very specific: line 51
Run these from the repository root after npm install, with Node 22.18 or newer:
- Very specific: line 58
Add shadcn components from packages/ui: npx shadcn@latest add <name>.
≈ “Common” is an estimate: at least 1 in 5 of the 41,581 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
fxbot
Read CONVENTIONS.md before changing code. CLAUDE.md points here. This file is the instruction source for coding agents.
Where things are
- docs/_completed/: what's built. v1-plan.md, then a phase doc for each feature in
phases/, with what the owner asked, the research, the plan, its checklist, and "What the build changed". Read a feature's phase doc before changing it. The README's Phases list links each one. - docs/phases/: later ideas, as one-page stubs. Build one only when asked, and never report one as running behavior.
- docs/research-directive.md: how a phase is planned.
- docs/releases/: each release's short post.
- archive/: the old drovr design, including the sample
AGENTS.mdfiles in its spike. They are not instructions.
What this repo is
fxbot is AI assistants that do real work, built your way: bots that chat, remember, work on a computer of their own, and run tasks on a schedule, on any model, hosted or local, for one person on a machine of their own. It's a small core plus plugins, like Pi. The core is what every bot needs, what plugins plug into, and what fxbot needs to run. Everything else is a plugin an owner adds only if they want it.
The code:
packages/sdk:@fxbot/sdk, the agent system around libfx: providers and their catalog (providers-registry.json), bots, chats, memories, the library, skills, MCP servers, migrations, sealed secrets, and the plugin API.@fxbot/sdk/clientis the typed client a UI uses.packages/server: the HTTP API over the SDK.packages/ui: the app, a PWA.packages/website: fxbot.sh and its docs, static pages that import none of the other three.packages/web-app: outside the workspaces, what fxbot.sh hosts for web pairing: the app at web.fxbot.sh, a frame for each fxbot's own page, and a Cloudflare Worker that passes the sealed handshake and stores nothing.plugins/: fxbot's own plugins, outside the workspaces, added from GitHub like anyone's: the computer, with a room's computer when chat rooms is added, chat rooms, dreams, routines, messages, subagents, permissions, pages, mermaid, soul, and web pairing.setup.shanddeploy/: a release install, as containers under podman or docker (fxbot, pgvector's Postgres, and a local embedder), with a hostfxbotcommand for updates, backups, and uninstall.scripts/: what writes generated files (provider logos, blob data, screenshots, the link card), and the plugins'minFxbotcheck.
How it fits together:
- Records live in Postgres, and so do the chats: libfx's sessions, through Workflow's Postgres World.
- A plugin carries any mix of code, MCP servers, and skills. Its code changes the app through the plugin API: hooks into turns and tool calls, tools, routes, tables in a schema of its own, settings, sessions of its own, and places in the page. Plugins use one another through
fx.provideandfx.need. - A plugin says the oldest fxbot it runs on, and
plugin-breaks.jsonlists what each release broke, so one that can't run shows Unsupported. - There is no test suite or CI.
Rules
- Prefer the smallest change that meets the task. Drop an older convention when it fights that.
- Before building a feature, ask: is it core, or a plugin? The default is plugin. Follow Core or plugin, and say which in the phase doc. When a plugin can't do what it needs, widen the plugin API with the smallest hook it needs, not the feature.
mainholds releases, and updates to the site between them. Commit to the openrelease/<next version>branch, never tomain; the owner merges and releases (README: Releasing).- Commit as you go. When a piece of work is done and its checks pass, commit it on the open release branch, with a message that says what changed, so the owner only has to push. Keep unrelated changes in separate commits. Don't push, merge, or tag unless the owner asks.
- A change that removes or breaks something in the plugin API adds a line to
packages/sdk/src/plugin-breaks.json, and a note under## Unreleased(plugin compatibility). A plugin inplugins/that starts using something newer raises itsminFxbot. - A schema change is a new numbered file in
packages/sdk/src/migrations/. Never edit or remove one that has shipped in a release. Note it under## UnreleasedinCHANGELOG.md, for the release's Before upgrading list. - The stack is Vite, React, shadcn/ui, and a tiny Node server around libfx. Do not add Next.js, the Vercel AI SDK, a second agent runtime, or Hermes Agent.
- Agent logic, storage, and input checks belong in
@fxbot/sdk. The server only adds HTTP. The UI imports only@fxbot/sdk/client, never the SDK's main entry. - A bot's tools never act on the owner's machine: no file outside fxbot's own data, and no command there. Files and commands go through the computer plugin, and the machine's own folders only through the local access plugin, off by default (Bots and the owner's machine).
- Never put a secret in the page or in
@fxbot/sdk/client. Keys and tokens live only on the server, sealed in Postgres by the SDK. The page sends a key once and never receives one. Vite reads no.env. - libfx behavior comes from the installed package or the published docs. Say what you could not verify.
- This is a public repo. Do not add private hostnames, machine names, personal subscriptions, home-directory paths, or private project names.
- Write "Hackers in the Loop" in full if that name is needed.
Checks
Run these from the repository root after npm install, with Node 22.18 or newer:
npm run typecheckrunstsc --noEmitin each package, with that package's owntsconfig.json, then over the server code inplugins/, thenscripts/check-plugins.mjs, which checks each plugin'sminFxbotagainst the next release.npm run buildbuilds the page and service worker intopackages/ui/dist/. It does not typecheck.npm run build-sitebuilds the website intoout/with Astro and Starlight, and checks its links. It needs Node 22.22 or newer.npm run dev -w @fxbot/websiteserves it as you edit.- The docs are Markdown in
packages/website/src/content/docs/docs/, and the SDK's pages, for people who build their own apps on@fxbot/sdk, inpackages/website/src/content/docs/sdk/: one Diátaxis kind per page, each listed insrc/sidebar.ts. - The home page is React, in
src/home.tsx. The changelog page and the variables table come fromCHANGELOG.mdand the README.
- The docs are Markdown in
- Add shadcn components from
packages/ui:npx shadcn@latest add <name>. podman build .(ordocker build .) builds fxbot's image from theDockerfile.bash -n setup.sh deploy/fxbotchecks the shell scripts' syntax.- A plugin's
page.jsis built from itspage.jsxwith rolldown, by the command in its README. Commit both. node scripts/provider-logos.mjswritespackages/ui/src/provider-logos.ts, the Add provider page's logos, from models.dev and the sources it names. Run it after adding a provider topackages/sdk/src/providers-registry.json.node scripts/blob-data.mjswritespackages/ui/src/blob-data.ts, and copies it andblob-draw.tsto the site. Run it after changing a shape, a color, orblob-draw.ts.npm run shotsremakes the screenshots inpackages/website/public/shots/, for the site, the docs, and the README, from a throwaway fxbot with the made-up bots inscripts/screenshots/world.mjs. It rewrites only the shots that look different. Look at each one it rewrote before committing it.- It needs podman or docker, a built page (
npm run build), and Playwright's Chromium:npm ci --prefix scripts/screenshots, thennpx --prefix scripts/screenshots playwright-core install --with-deps chromiumonce.
- It needs podman or docker, a built page (
npm run cardredrawspackages/website/public/card.png, the image a link to fxbot.sh shows in chats and social posts, from the home page's crowd (packages/website/src/crowd.ts) and headline. It uses the screenshots' Playwright. Run it after changing either, and look at the card before committing it.- Web pairing has checks of its own, since its packages stay out of the workspaces. After
npm ciinpackages/web-appand inplugins/web-pairing:node packages/web-app/protocol/check.mjsruns the protocol against Noise's and CPace's test vectors.npm run typecheck --prefix packages/web-appchecks the app, its workers, and the Worker, andnpx tsc -p plugins/web-pairingthe plugin's server.npm run dev --prefix packages/web-appbuilds the app and runs the Worker athttp://localhost:8771, with frames athttp://<frame>.localhost:8771. Point a disposable fxbot's Settings › Web pairing › relay atws://localhost:8771/signal.- The plugin's
server.jsandpage.jsare built by the commands in its README. Commit them.
git diff --checkchecks whitespace on tracked changes. New files need a separate look; untracked files are outside that diff.
There are no automated tests. Behavior is checked by hand, in a browser or with curl, as each phase doc's checklist describes. npm run server needs Postgres (a checkout's comes from deploy/compose.dev.yaml), FXBOT_DATABASE_URL, and FXBOT_SECRET_KEY_FILE, from the environment or .env (see the README). Point checks at a disposable database and FXBOT_DATA, and at another port with FXBOT_PORT. Check the release compose file with another COMPOSE_PROJECT_NAME, FXBOT_PORT, and FXBOT_ROOT, so it stays clear of a real install on the same machine. Do not claim a check passed unless it ran.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

