frappe-app-dev
How to run and change Frappe apps with Pilot. Use before any work in a Frappe app (a repository with hooks.py and DocTypes): writing or reviewing code, running migrate or tests, or getting a test site for a PR.
How do I install this agent skill?
npx skills add https://github.com/frappe/skills --skill frappe-app-devIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The skill provides instructions for Frappe app development using the Pilot tool. It includes procedures for environment setup, database migrations, and security scanning using official Frappe semgrep rules. The security posture is appropriate for a development environment, with documented configurations for specific testing scenarios.
- Socketpass
No alerts
- Snykwarn
Risk: MEDIUM · 1 issue
What does this agent skill do?
Frappe app development
Pilot replaces bench for development. Run Frappe commands through it, such as pilot frappe --site SITE migrate. Always pass --site, because a bench's default site can be a different one.
Code is done when you have run it on the app's site as a user with the right role, and scanned the files you changed (see Code). Report the scan result.
Run the app you are changing
Work in the bench your checkout already uses, and leave other benches and their Python alone. Pilot supports two layouts:
- Bench with several apps: the checkout sits in a bench's
apps/folder, next tofrappe. Pilot commands run anywhere inside the bench folder use that bench. Herepilot dev inforeports "no bench yet" and suggestspilot dev setup. Ignore that, and use the bench you are in. - Bench per app: the checkout is a standalone repository, and
pilot dev setupmade a bench for it, with the app linked in. In the checkout,pilot dev infoshows that bench and the site URL. No bench yet?pilot dev setupcreates one.
Then:
- Turn off what you do not need. An idle bench uses about 3.8 GB by default, and about 450 MB with both of these:
- Set
watch_apps_js = falseunder[bench]inbench.toml(2.8 GB), unless you are changing Frappe or Desk bundles. - Run
pilot processes disable frappe-flow_server(200 MB), unless you need Frappe's AI chat.
- Set
- Start the bench:
pilot startin a bench with several apps,pilot dev startin a standalone checkout. Both stay in the foreground, so run them in a way that outlives your session.migrate,execute, and tests need the Redis they run. - Run
pilot frappe --site SITE migrate.ls sitesin the bench lists the sites.
While you work:
pilot stopin the bench or checkout stops that bench and leaves other benches running.- On a frappe-ui app,
pilot dev startregeneratesfrontend/src/types/doctypes.ts. Keep that file out of commits unless the change is intended.
To set up a new bench for several apps, or to change Frappe itself, run pilot new NAME --frappe-branch BRANCH, pilot -b NAME init, pilot -b NAME get-app <repo URL> for each app, and pilot -b NAME new-site SITE --apps <apps>. For one app, pilot dev setup in its checkout is quicker. pilot new defaults to version-16 and MariaDB, while pilot dev setup defaults to develop and SQLite.
Test site for a PR
Give the PR a bench of its own, so your work stays as it is. Check the PR's base branch first: gh pr view <N> --json baseRefName. Frappe develop fits a develop base. For a version-N base, use Frappe version-N. Use MariaDB when the PR touches raw SQL, and SQLite otherwise. The Frappe branch and the database are fixed once the bench exists.
The app runs alone. Use a bench per app (about 4 minutes):
cd <app checkout>
git worktree add --detach <WT> # WT: a new folder outside any bench, such as ~/worktrees/<app>-pr<N>
cd <WT>
gh pr checkout <N> --detach
pilot dev setup # add --frappe-branch version-N or --database mariadb if needed
pilot dev info
The app needs other apps, or you work in a bench with several apps. Make a new bench with all of them (about 6 minutes for one app). Benches live in benches/ in the Pilot folder, such as ~/pilot/benches/<B>.
pilot new <B> --frappe-branch develop --database sqlite # or version-N, or leave out --database for MariaDB
pilot -b <B> init
pilot -b <B> get-app <repo URL> # once for each app the PR's app needs
pilot -b <B> get-app <PR app repo URL> --skip-assets
cd ~/pilot/benches/<B>/apps/<app>
gh pr checkout <N> --detach
pilot -b <B> build --apps <app>
pilot -b <B> new-site <B>.localhost --apps <apps> --admin-password admin
Then trim and start the bench as described in Run the app you are changing.
- Ready: you can log in, and the app's own page loads in a browser, such as
/gfor Gameplan.pingand login pass even when the frontend is missing. Hand over the URL and the login. - New commits: in a bench per app, run
pilot dev setupagain. It installs requirements, migrates, and rebuilds, but never pulls or switches branches in a linked app. In a bench with several apps, rungh pr checkout <N> --detachinapps/<app>, thenpilot -b <B> build --apps <app>andmigrate. - Remove: run
pilot stopfirst. In a bench per app, runpilot --yes dev drop, thengit worktree remove --force <WT>from the main checkout. In a bench with several apps, runpilot -y -b <B> drop-site <site> --no-backup, thenpilot -y -b <B> drop. Ask before you drop a site or bench you did not create.
Serve a site on another hostname
Frappe picks the site from the hostname. Add an alias in the bench's sites/ folder with ln -s <site> <hostname>, or requests return 404. Remove the alias before you drop the site.
Point the hostname at the port that fits the work:
- Site port (
http_portinbench.toml): realtime works. A frontend change appears only after a rebuild. - Vite port (the app's
devscript): a frontend change reaches the page without a reload. Realtime does not connect. The page has no CSRF token, so logged-in POST requests return 400 until you runpilot frappe --site SITE set-config ignore_csrf 1. Set it back to 0 when you move to the site port.
Code
- Give every
@frappe.whitelistmethods=[...]and a type hint on every parameter. GET requests do not commit, and hints are how Frappe validates arguments. frappe.qb.get_querydefaults toignore_permissions=True. PassFalsein user-facing code.- A
has_permissionhook must returnTrueorFalse. Frappe treatsNoneas a denial, so returnTruefor users the hook does not restrict.
Scan the files you changed with Frappe's rules, which cover type hints, guest access, SQL injection, manual commits, translations, and more:
R=/tmp/frappe-semgrep-rules
git -C $R pull -q 2>/dev/null || git clone -q --depth 1 https://github.com/frappe/semgrep-rules.git $R
uvx semgrep scan --config $R/rules <files you changed>
Fix findings on the lines you changed. Report older findings in those files without fixing them. A clean scan does not cover the get_query and has_permission points above.
Tests
pilot frappe --site SITE set-config allow_tests true
pilot frappe --site SITE run-tests --doctype "My DocType"
Subclass IntegrationTestCase from frappe.tests. It runs against the real database and rolls back after each test, so write tests without mocks. Report the exact command you ran.
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/frappe/skills/frappe-app-dev">View frappe-app-dev on skillZs</a>