sf-commit

A Claude Code skill that retrieves Salesforce org metadata and commits it to GitHub — with a browser-based component picker.

Works with any org type: source-tracked (scratch orgs, sandboxes) and non-source-tracked (production, Dev Hub). Falls back to a direct Metadata API SOAP browse for non-tracked orgs.

Install

curl -fsSL https://raw.githubusercontent.com/shinydrift/sf-commit/main/install.sh | bash

Or a specific version:

bash <(curl -fsSL https://raw.githubusercontent.com/shinydrift/sf-commit/main/install.sh) v1.0.0

Update

bash ~/.claude/skills/sf-commit/install.sh

Requirements

• Salesforce CLI v2 authenticated to at least one org
• GitHub CLI authenticated (gh auth login)
• Python 3.8+
• Git repo initialised at your Salesforce project root

Node/npm is not required at runtime — the picker UI is pre-built and included in the repo.

Usage

In Claude Code, from inside a Salesforce project directory:

/sf-commit

Claude will:

1. List your authenticated orgs and ask which to target
2. Try to preview source-tracked changes — falls back to a full Metadata API browse if the org isn't source-tracked
3. Open a browser-based component picker (two-panel: types on the left, components on the right)
4. Retrieve selected components via sf project retrieve start
5. Create a feature branch, commit, push, and open a GitHub PR

How it works

┌─────────────────────────────────────────────┐
│  picker_server.py  (Python HTTP server)      │
│  • Serves picker-ui/dist/ as static files    │
│  • /api/types   — describeMetadata (SOAP)    │
│  • /api/expand  — listMetadata (SOAP)        │
│  • /api/submit  — writes selections.json     │
└─────────────────────────────────────────────┘
         ↑
         │  direct SOAP  (no sf CLI filter)
         ↓
┌─────────────────────────────────────────────┐
│  sf_soap.py  — Metadata API SOAP client      │
│  Auth via `sf org display` (reuses sf token) │
│  Handles folder types automatically          │
│  (Report, Dashboard, Document, EmailTemplate)│
└─────────────────────────────────────────────┘
         ↑
         │  static files
         ↓
┌─────────────────────────────────────────────┐
│  picker-ui/  — React + Tailwind + shadcn     │
│  Two-panel: Command list + checkbox picker   │
│  Pre-built to picker-ui/dist/                │
└─────────────────────────────────────────────┘

Contributing

The skill installs directly into ~/.claude/skills/sf-commit/ which is this git repo — so your edit/test/commit loop happens in one place.

# 1. Fork this repo on GitHub, then install your fork:
REPO=https://github.com/YOUR_FORK/sf-commit.git
git clone "$REPO" ~/.claude/skills/sf-commit

# 2. Create a branch and make changes
cd ~/.claude/skills/sf-commit
git checkout -b fix/my-improvement

# 3. Test by running /sf-commit inside any Salesforce project in Claude Code

# 4. If you changed the React UI, rebuild:
cd scripts/picker-ui && npm run build && cd ../..

# 5. Commit and push — the pre-push hook rebuilds dist/ automatically
git add -A && git commit -m "fix: my improvement"
git push origin fix/my-improvement

# 6. Open a PR against shinydrift/sf-commit main

Project structure

sf-commit/
├── SKILL.md                  # Skill instructions (read by Claude)
├── install.sh                # One-liner installer
├── README.md
└── scripts/
    ├── picker_server.py      # Python HTTP server + API
    ├── sf_soap.py            # Salesforce Metadata API SOAP client
    └── picker-ui/            # React UI
        ├── src/
        │   ├── App.tsx
        │   ├── components/ui/  # shadcn-style components
        │   └── lib/utils.ts
        ├── dist/             # Pre-built, committed — no Node needed at runtime
        └── package.json

License

MIT