Simply Fleet · Engineering

SF Agent Developer Onboarding

This is the complete setup guide for the Simply Fleet AI agent framework — written for developers who are new to GitHub, the command line, and AI tooling. Every step explains what you're installing and why. Work through it top to bottom and you'll have a working environment in about 30 minutes.

⏱ ~30 min end to end 💻 macOS or Windows (WSL2) 🧠 No AI experience required

01What is the SF Agent?

The SF Agent is a collection of AI helpers (we call them sub-agents) that build and document Zoho Creator applications on your behalf. Instead of clicking through the Zoho form builder for hours, you write a short brief in plain English and the agents create the forms, fields, reports, scripts, dashboards and user manuals for you.

You'll be installing three layers on your laptop:

Foundation tools — a terminal, Git, Node.js, Python, Pandoc, Chromium. Standard developer plumbing.
The SF Agent code — pulled from our GitHub repository (SimplyFleet/sf-agent).
Claude Code — Anthropic's official command-line tool for talking to Claude. This is the AI runner that drives the sub-agents.

Once it's all wired together, you talk to Claude in a chat window and it operates Zoho Creator through a real browser session — exactly the way you would, just much faster and more consistent.

Read me first

Work top to bottom. Each step depends on the one before it — don't skip ahead.
Two of the installs are slow. MacTeX (or texlive-xetex on Windows) is ~3–4 GB. Kick step 05 off early and read the rest while it runs.
Don't fight a problem for more than 15 minutes. Skip to section 14 and ping Zane on Slack — it's faster for everyone.

02Concepts in 60 seconds

You'll see these terms over and over. Skim once, then move on — they'll click as you go.

Terminal

The text window where you type commands instead of clicking. Mac calls it Terminal; on Windows we use Ubuntu inside WSL2.

⎇

Git & GitHub

Git tracks every change to the code; GitHub is the website that hosts our code. git clone downloads a copy.

Node.js / npm

Node.js runs JavaScript outside the browser. npm is its package installer — it downloads code libraries we depend on.

Python / pip

Python is the language used by the browser-automation parts. pip is its package installer (same idea as npm).

📄

.env file

A plain text file that holds your secret credentials (passwords, tokens). Never gets uploaded to GitHub.

🔐

OAuth

A way to give software permission to act on your behalf without sharing your password. We use it for Zoho's data API.

🤖

Sub-agent

A specialist AI helper with one job — e.g. form-builder creates forms, qa-agent verifies the build.

🏃

Sprint

A coordinated multi-step build. One sprint can spawn 10+ sub-agents to deliver a full app + manual + QA report.

03Before you start

What you'll need

A laptop running macOS 12+ or Windows 10/11 with WSL2 enabled.
About 10 GB free disk space (most of that is LaTeX, used to render PDF manuals).
Your Zoho login (simplyfleet account) — Zane will share the password through 1Password.
An Anthropic API key (for Claude Code) — Zane will provision this for you.
30 minutes uninterrupted. The LaTeX install in particular takes a while; start it early.

Windows users — read this first

Everything below assumes you're working inside WSL2 (Windows Subsystem for Linux). If you've never used it, install it now:

Open PowerShell as Administrator (right-click Start → "Terminal (Admin)").
Run: wsl --install
Restart when prompted. On reboot, Ubuntu will finish installing and ask you to create a Linux username + password (this is a new Linux account, not your Windows one).
From now on, open Ubuntu from the Start menu — that's your terminal for this guide. Anywhere this guide says "open the terminal", you mean Ubuntu.

04Open your terminal

The terminal is where every command in this guide gets typed.

Press ⌘+Space to open Spotlight, type Terminal, press Enter. A black-and-white window appears with a prompt that ends in $. That's it — that's your terminal.

Click Start → type Ubuntu → press Enter. A window appears with a prompt ending in $. Everything we do happens inside this Ubuntu window, not in regular Windows PowerShell or Command Prompt.

What does $ mean?

It's just the prompt — the terminal's way of saying "ready for your next command". When this guide shows code that starts with $, you do not type the dollar sign. Type only what comes after it.

So if you see $ npm install, you type just npm install and press Enter.

How do I know if a command worked?

Most successful commands print nothing and just give you a fresh $ prompt. Errors are loud — they print red text or words like error, not found, denied.

If you're unsure, the next step in this guide always tells you what you should expect to see.

05Install the foundation tools

These are the building blocks. None of them are AI yet — this is the standard developer toolkit the SF Agent runs on top of.

Tool	What it is	Why we need it
Homebrew macOS only	A package manager for macOS — like an app store for developer tools.	The cleanest way to install everything below in one go.
Node.js (via nvm)	Runs JavaScript outside the browser.	Our toolkit scripts and Claude Code itself are JavaScript.
Python 3.10+	A general-purpose programming language.	The browser-automation pieces (logging into Zoho, clicking through forms) are Python.
Pandoc	Converts documents between formats.	Turns Markdown manuals into polished PDFs.
XeLaTeX (MacTeX / TeX Live)	The PDF rendering engine Pandoc uses.	Without it, manuals can't be exported to PDF. Big download (~4 GB).
Chromium	An open-source build of the Chrome browser.	The agents log into Zoho through this browser to make changes that aren't possible via API.
Playwright	A library that controls Chromium from code.	This is the "remote control" the agents use to drive the browser.

Run the install

Pick your operating system and copy the entire block into your terminal. Each block is safe to re-run if it fails partway.

1. Homebrew

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

You'll be asked for your Mac login password — type it (you won't see characters appear; that's normal) and press Enter. Takes a few minutes. When it finishes, follow any "Next steps" Homebrew prints — usually two echo commands to add itself to your PATH.

2. Node.js, Pandoc, Chromium

brew install node@20 pandoc chromium
brew install --cask mactex-no-gui

MacTeX is ~4 GB and takes 10–15 min on a normal connection. While it runs, keep going with the next step — they're independent.

3. Python packages

pip3 install playwright requests python-dotenv
playwright install chromium

playwright install chromium downloads a controlled copy of Chromium that Playwright manages. This is separate from the regular Chromium you just brewed — and that's intentional.

1. nvm + Node.js

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
source ~/.bashrc
nvm install 20
nvm use 20

nvm is the Node Version Manager — it lets you swap Node.js versions easily. We pin to Node 20 because that's what the project is tested against.

2. System packages

sudo apt-get update
sudo apt-get install -y python3 python3-pip pandoc texlive-xetex texlive-fonts-recommended chromium-browser

sudo means "run this as the admin user" — Ubuntu will ask for the Linux password you set during WSL setup. The texlive-* packages are the LaTeX engine (~3 GB).

3. Python packages

pip3 install playwright requests python-dotenv
playwright install chromium

I see a wall of text scrolling — is something wrong?

No. Installers are noisy by design. Wait until your prompt comes back (the line ending in $), then read the last few lines. If they say things like installed, complete, or just go back to a prompt, you're fine. If the last line says error, copy it and ask in support.

06Get the code from GitHub

Our project lives at github.com/SimplyFleet/sf-agent. You're going to clone it — make a local copy on your laptop.

Wait — what is GitHub, exactly?

GitHub is a website that stores code. Think of it like Google Drive, but for source code, with a full history of every change ever made (that history is the "Git" part).

You don't edit code directly on the GitHub website. You download a copy to your laptop, edit it locally, and then send your changes back. Three terms you'll see over and over:

Clone — first-time download of the whole project to your laptop.
Pull — fetch the latest changes from GitHub into your local copy.
Push — send your local changes back up to GitHub for everyone else to see.

Step 1 — sign in to GitHub and get added to the org

Make sure you have a github.com account and that Zane has added you to the SimplyFleet organisation. Without that, every clone attempt will fail with "permission denied".

Step 2 — pick how you want to clone

You've got two ways to do this. If you've never used a terminal for Git before, use Option A (GitHub Desktop) — it handles everything visually and takes care of authentication for you. Option B is the same thing in the terminal.

Option A — GitHub Desktop (easiest)

GitHub Desktop is a free app from GitHub that gives you a proper window with buttons for everything Git does. You'll use it for cloning today, and later for pulling updates and pushing your own changes — all without typing.

Go to desktop.github.com and download the installer for your OS. Windows users: install this on regular Windows, not inside WSL — it's a Windows app.
Open it. The first launch asks you to sign in to GitHub.com — click the button, your browser opens, you log in, GitHub Desktop is now linked to your account. That's the auth done — no Personal Access Tokens, no passwords to copy around.
On the welcome screen click Clone a repository from the Internet….
In the search box type SimplyFleet/sf-agent. It should appear (if not, you're not in the org yet — go back to Step 1).
Set the Local path to somewhere easy like ~/Documents on macOS, or C:\Users\<you>\Documents on Windows.
Click Clone. The repo downloads — usually under a minute.
When it's done, click Repository → Open in Terminal in the menu bar. This is the bridge between the visual app and the rest of this guide — every command from this point on goes in that terminal window.

Why use GitHub Desktop later, too?

Once you start making your own changes, GitHub Desktop shows you a side-by-side view of every line you've changed and lets you click Commit and Push instead of typing the commands. It's strictly easier than the terminal for day-to-day work — most of our team uses it.

Option B — Terminal (if you prefer the CLI)

In your terminal, navigate to where you want the project to live, then clone:

cd ~
git clone https://github.com/SimplyFleet/sf-agent.git
cd sf-agent

The first time, Git asks for your GitHub username and a Personal Access Token (PAT) — not your password. To create one: GitHub → click your avatar (top right) → Settings → Developer settings → Personal access tokens → Tokens (classic) → Generate new token (classic) → tick repo → Generate. Copy the token immediately (you only see it once) and paste it where Git asks for "password".

After this step (either option)

You have a folder called sf-agent on your laptop. Every command from here on assumes your terminal is inside that folder. Run pwd to confirm — the output should end in /sf-agent.

07Install project dependencies

The repo lists which JavaScript libraries it depends on in a file called package.json. npm install reads that file and downloads them all into a local node_modules folder.

npm install

Expect a flurry of output, possibly some yellow "warnings" (which are usually fine), and finally a summary line like added 247 packages in 12s. If you see red npm ERR! lines, copy them into support.

Why is node_modules so huge?

Each library may depend on dozens of smaller libraries, which depend on more libraries, recursively. node_modules ends up with hundreds of folders. This is normal — it's gitignored, so it never gets committed to GitHub.

08Configure your credentials

The agents need credentials to log into Zoho on your behalf. They live in a file called .env at the root of the project. This file is gitignored — it never gets uploaded to GitHub.

What is the .env file?

It's just a plain-text file with one KEY=value per line. Programs read it on startup and treat each line as an environment variable. The reason we use it (rather than hard-coding values into the code) is so that secrets stay separate from code, and each developer can have their own copy.

Step 1 — get the credentials snippet from Zane

We use a single shared development Zoho account for the SF Agent — it can only edit dev environments, which means it's safe to share between developers. Zane will send you the snippet via 1Password (or directly, since these creds can't touch production data).

Step 2 — create your `.env` file

From inside the sf-agent folder:

cp .env.example .env
nano .env

The first command makes a copy of the template. The second opens it in nano, a simple terminal editor. Use the arrow keys to move around; press Ctrl+O then Enter to save, Ctrl+X to exit.

Paste the snippet from Zane over the placeholder values. The eight lines you need to end up with are:

ZOHO_EMAIL=(from Zane)
ZOHO_PASSWORD=(from Zane)
ZOHO_CLIENT_ID=(from Zane)
ZOHO_CLIENT_SECRET=(from Zane)
ZOHO_REFRESH_TOKEN=(from Zane)
ZOHO_TOKEN_ENDPOINT=https://accounts.zoho.com/oauth/v2/token
ZOHO_OWNER=simplyfleet
ZOHO_APP=ai-sf-corp

Variable	What it does
`ZOHO_EMAIL` + `ZOHO_PASSWORD`	Used by Playwright to log a real browser into Zoho. Required for any change that goes through the form builder UI.
`ZOHO_CLIENT_ID` `ZOHO_CLIENT_SECRET` `ZOHO_REFRESH_TOKEN`	Used by Zoho's REST API for reading and writing data. The refresh token is long-lived — you don't need to rotate it.
`ZOHO_OWNER` + `ZOHO_APP`	Tells the agents which Zoho Creator app to operate on by default. `ai-sf-corp` is the dev sandbox — leave it set there.

The dev account is dev-only — but still treat it carefully

The credentials only have permission to edit the ai-sf-corp dev app, so a leak isn't catastrophic. But: don't paste them into shared chat channels, don't commit them, and never set ZOHO_APP=zane-sfcorp — that's a production app and the agents must never touch it.

09Verify everything works

Two quick checks. Run them from inside the sf-agent folder.

Check 1 — OAuth token works

source scripts/zoho-auth.sh
TOKEN=$(get_oauth_token)
echo $TOKEN

You should see a long string starting with eyJ0eXAi.... That's your access token, refreshed live from Zoho. If you see error or an empty line, double-check that you pasted the credentials snippet into .env exactly — no extra spaces, no quotes.

Check 2 — environment file is being read

python3 -c "from dotenv import load_dotenv; import os; load_dotenv(); print('Email:', os.getenv('ZOHO_EMAIL'))"

You should see your ZOHO_EMAIL printed back. If it prints Email: None, your terminal isn't in the sf-agent folder, or .env wasn't saved properly.

Check 3 (optional) — full validator

The repo includes a script that runs every check at once:

bash scripts/validate-setup.sh

If you see all green ticks, you're ready for your first task.

10Run your first task

Time to install Claude Code — Anthropic's official command-line tool for talking to Claude. It's a single command-line program that you chat with, just like the Claude website, except it can read your files, edit them, run shell commands, and (most importantly for us) spawn the SF Agent's sub-agents.

Step 1 — install it

npm install -g @anthropic-ai/claude-code

Step 2 — set your API key

Zane will give you an API key starting with sk-ant-. Add it as an environment variable:

export ANTHROPIC_API_KEY=sk-ant-your-key-here

To make this permanent (so you don't retype it every new terminal), append the same line to your shell config:

echo 'export ANTHROPIC_API_KEY=sk-ant-your-key-here' >> ~/.zshrc   # macOS
echo 'export ANTHROPIC_API_KEY=sk-ant-your-key-here' >> ~/.bashrc  # WSL

Step 3 — start Claude Code

Make sure your terminal is inside the sf-agent folder, then run:

claude

An interactive prompt appears. Type your first message:

Inspect the ai-sf-corp app and show me all forms.

Claude will read the project's CLAUDE.md, follow the rules in docs/CORE.md, spawn the app-inspector sub-agent, log into Zoho through Playwright, walk the app, and print a tree of forms back at you. This is the moment everything clicks.

Important — only use the dev environment

Always work against ai-sf-corp (the dev app) when you're learning. Never run sub-agents against zane-sfcorp — that's the production app and changes there go to live customers.

11Run a full sprint

A sprint is a coordinated multi-step build. It's defined as a plain-English brief in sprints/<name>/sprint.md — what forms to build, what fields, what scripts, what reports.

To run an existing sprint, just tell Claude Code to do it:

Read sprints/sf-corp-sprint-0/sprint.md and execute it end to end.
Spawn the right sub-agents for each task and report back as you go.

Claude will typically:

Read the spec from sprints/sf-corp-sprint-0/sprint.md.
Spawn form-builder, report-builder, script-builder, and page-builder sub-agents in sequence.
After each step, run qa-agent to verify the build matches the spec.
Run narrative-manual-agent to generate user + admin manuals.
Send you a completion summary with links to every artifact in the sprint folder.

A typical sprint takes 30–90 minutes of agent time and produces an entire app + documentation in one shot.

Tip — start small

Before running a multi-form sprint, ask Claude to build a single form end-to-end first. It's the same workflow at smaller scale, and it's much easier to debug if something goes wrong.

12The sub-agents

Each sub-agent has one job. You don't usually call them by name — Claude picks the right one — but knowing what each one does helps when you read sprint output or debug a failure.

Agent	What it does
`app-inspector`	Snapshots the current state of a Zoho Creator app — forms, fields, reports, scripts. The first thing run before any change.
`form-builder`	Creates forms and fields. Handles every field type (lookups, dropdowns, auto-numbers, sections, etc.).
`report-builder`	Creates list/grid reports with filters, sorting, custom columns.
`script-builder`	Writes Deluge — Zoho's scripting language — for workflows, validations, and custom functions.
`page-builder`	Builds dashboard pages with widgets that pull from reports.
`qa-agent`	Verifies what was built matches the spec. Catches regressions before they reach production.
`narrative-manual-agent`	Generates prose user + admin manuals (Markdown → PDF via Pandoc).
`visual-guide-agent`	Generates step-by-step visual guides with screenshots.
`doc-qa`	QAs the manuals — checks the docs match what was actually built.

Each agent has a PROMPT.md in agents/<name>/ describing exactly what it does and how. If you want to extend or customise an agent, that's the file to read.

13Troubleshooting

Symptom	Most likely cause & fix
`command not found: brew`	Homebrew not on your `PATH`. Re-run the "Next steps" lines Homebrew printed at the end of its installer.
`EACCES: permission denied` on `npm install -g`	Don't use `sudo`. Instead, install Node.js via `nvm` (step 5) — it puts everything in your home directory.
`Permission denied (publickey)` when cloning	You used the SSH URL but haven't set up SSH keys. Use the HTTPS URL instead: `https://github.com/SimplyFleet/sf-agent.git`.
`No OAuth token` from `get_oauth_token`	Re-check `ZOHO_CLIENT_ID`, `ZOHO_CLIENT_SECRET`, `ZOHO_REFRESH_TOKEN` in `.env`. Refresh tokens don't expire, but a typo will fail silently.
`Pandoc: pdflatex not found`	LaTeX isn't installed. macOS: `brew install --cask mactex-no-gui`. WSL: `sudo apt-get install texlive-xetex`.
Browser login fails with "MFA required"	The Zoho account uses OneAuth on Craig's iPhone. Ping Zane on Slack to approve the prompt.
Agent runs forever and never returns	Bump the timeout in `agents/<name>/config.json` → `"runTimeoutSeconds": 1800`.
Code 1130 from Zoho data API	You're hitting the production environment. Add `environment: development` as an HTTP header — see `scripts/zoho-data.sh` for an example.

14Get help

If anything in this guide didn't work, don't fight it for more than 15 minutes — ask. Engineering questions are quick to answer in chat and slow to dig out of a stale install.

📧 Email — Hello@simplyfleet.co.za
🐛 Bug or unclear step? — open an issue at github.com/SimplyFleet/sf-agent/issues
📖 Going deeper — README.md, AGENTS.md, and docs/ in the repo

Where to next?

Read README.md for the full feature list and advanced configuration.
Read AGENTS.md to understand how each sub-agent is prompted.
Look in sprints/ for example sprint specs you can copy and adapt.
When you're ready to build something real, ask Claude to draft a sprint brief with you, then run it.

01What is the SF Agent?

02Concepts in 60 seconds

Terminal

Git & GitHub

Node.js / npm

Python / pip

.env file

OAuth

Sub-agent

Sprint

03Before you start

What you'll need

04Open your terminal

05Install the foundation tools

Run the install

1. Homebrew

2. Node.js, Pandoc, Chromium

3. Python packages

1. nvm + Node.js

2. System packages

3. Python packages

06Get the code from GitHub

Step 1 — sign in to GitHub and get added to the org

Step 2 — pick how you want to clone

Option A — GitHub Desktop (easiest)

Option B — Terminal (if you prefer the CLI)

07Install project dependencies

08Configure your credentials

Step 1 — get the credentials snippet from Zane

Step 2 — create your .env file

09Verify everything works

Check 1 — OAuth token works

Check 2 — environment file is being read

Check 3 (optional) — full validator

10Run your first task

Step 1 — install it

Step 2 — set your API key

Step 3 — start Claude Code

11Run a full sprint

12The sub-agents

13Troubleshooting

14Get help

Where to next?

Step 2 — create your `.env` file