Update to Base44

{
  "name": "base44-remote-dev",
  "description": "Develop a Base44 app remotely from your own coding agent (Claude Code, claude.ai, or any MCP client) by connecting it to the Base44 sandbox. Cloud agents connect over MCP; local agents can connect over MCP or drive the same sandbox with the `base44 sandbox` CLI subcommands (the CLI uses shorter names — e.g. read_file is `sandbox read`, list_directory is `sandbox ls`, run_command is `sandbox run`). Covers connecting/ authenticating, the available sandbox tools (run_command, read_file, write_file, edit_file, grep, list_directory, create_checkpoint, get_app_preview_url, get_app_status, list_user_apps, and the connector tools list_connectors / initiate_connector_connection), the edit→preview→verify loop, how changes persist, builder/external-agent concurrency, the in-editor \"Send to Coding Agent\" button + onboarding README URLs, and tips like reading the Vite dev-server logs. Triggers on \"develop my Base44 app remotely\", \"connect Claude Code to Base44\", \"bring my own agent\", \"edit a Base44 app over MCP\", \"Base44 sandbox MCP\", or \"Send to Coding Agent\".",
  "included_files": [],
  "skill_md_contents": "---\nname: base44-remote-dev\ndescription: >-\n  Develop a Base44 app remotely from your own coding agent (Claude Code,\n  claude.ai, or any MCP client) by connecting it to the Base44 sandbox. Cloud\n  agents connect over MCP; local agents can connect over MCP or drive the same\n  sandbox with the `base44 sandbox` CLI subcommands (the CLI uses shorter\n  names — e.g. read_file is `sandbox read`, list_directory is `sandbox ls`,\n  run_command is `sandbox run`). Covers connecting/\n  authenticating, the available sandbox tools (run_command, read_file,\n  write_file, edit_file, grep, list_directory, create_checkpoint,\n  get_app_preview_url, get_app_status, list_user_apps, and the connector tools\n  list_connectors / initiate_connector_connection), the edit→preview→verify loop, how changes\n  persist, builder/external-agent concurrency, the in-editor \"Send to Coding\n  Agent\" button + onboarding README URLs, and tips like reading the Vite\n  dev-server logs. Triggers on \"develop my Base44 app remotely\", \"connect\n  Claude Code to Base44\", \"bring my own agent\", \"edit a Base44 app over MCP\",\n  \"Base44 sandbox MCP\", or \"Send to Coding Agent\".\n---\n\n<!--\n  Vendored from base44-dev/apper PR #11608\n  (docs/features/bring-your-own-model/base44-remote-dev/SKILL.md).\n  Keep in sync with the upstream source if it changes.\n-->\n\n# Remotely develop a Base44 app over MCP\n\nConnect your own coding agent to a Base44 app's sandbox and develop in it\ndirectly — run commands, read and edit files, grep, list directories — while\nBase44 supplies the sandbox and you supply the agent and the LLM.\n\nThis works with any MCP-capable client. The examples use Claude Code.\n\n> **Easiest start:** in the Base44 app editor, click **Send to Coding Agent**. For a local agent\n> it gives you a ready-to-paste prompt (which fetches a README and drives the sandbox over MCP or\n> the `base44 sandbox` CLI — Section 10);\n> for the web it gives a prompt to paste into a **claude.ai** chat (with the Base44 MCP connector)\n> plus an **Open Claude** button. The button is the discovery surface — the rest of this skill is\n> the reference.\n\n> **Two transports:** web agents use **claude.ai** with the Base44 **MCP connector** (Sections\n> 1–9) — note this is the regular claude.ai chat, *not* Claude Code on the web (`claude.ai/code`),\n> which runs in its own repo-backed sandbox. A local agent can connect that same MCP server, or\n> drive the sandbox with the **`base44 sandbox` CLI** (a Base44 CLI token, Section 10) — same tools,\n> same behavior, same error codes; the CLI just exposes them under shorter command names\n> (`sandbox read`, `sandbox ls`, …).\n\n---\n\n## 1. Connect the MCP server\n\nThe Base44 MCP endpoint is:\n\n```\nhttps://app.base44.com/mcp\n```\n\nRegister it with Claude Code (run from any folder):\n\n```bash\nclaude mcp add --transport http base44 https://app.base44.com/mcp\n```\n\nAdd `--scope user` if you want it available in every project rather than just\nthe current folder.\n\n`claude mcp add` only writes the config — it does not authenticate yet.\n\n## 2. Authenticate\n\nStart Claude Code and open the MCP menu:\n\n```bash\nclaude\n```\n\nthen, inside Claude Code:\n\n```\n/mcp\n```\n\nSelect **base44** → **Authenticate**. A browser opens for the Base44 OAuth\nflow (PKCE) — log in and approve. When it succeeds, `/mcp` shows **base44** as\nconnected and lists its tools.\n\n**Pure-CLI / headless clients** that can't open a browser use the OAuth device\nflow (`/oauth/device/code`) instead — request a code, approve it in a browser\non another device, and the client receives the token.\n\n### Scopes\n\n| Tools | Required scope |\n|---|---|\n| `read_file`, `grep`, `list_directory`, `get_app_preview_url`, `get_app_status`, `list_user_apps` | `apps:read` (granted by default) |\n| `write_file`, `edit_file`, `run_command`, `create_checkpoint` | `sandbox:write` |\n\n`sandbox:write` is **not** granted by default — shell and file mutation\nrequire it explicitly. If the read tools work but the mutating ones return\n`NOT_AUTHORIZED`, your token is missing `sandbox:write`; reconnect and grant\nsandbox access (the device flow can request it explicitly).\n\n---\n\n## 3. Pick the app and orient yourself\n\nEvery tool takes a required `appId`. Find your apps with `list_user_apps`, then\npin the id in your requests so the agent passes it on every call.\n\nStart **read-only** to build a mental model before changing anything:\n\n```\nUsing the base44 tools on appId <APP_ID>:\n1. list_directory on the app root (recursive, depth 2)\n2. read_file src/App.jsx and src/pages.config.js\n3. grep for the component I want to change\nSummarize the structure before editing.\n```\n\n> **Cold start:** if the app has no running sandbox, the first tool call\n> transparently brings one up from your last commit — it just takes a bit\n> longer. Subsequent calls are fast.\n\n> **CLI names:** over the `base44 sandbox` CLI (Section 10) these read tools are\n> `list_directory` → `sandbox ls`, `read_file` → `sandbox read`, and\n> `grep` → `sandbox grep`.\n\n---\n\n## 4. Make changes\n\n- **`edit_file`** (`sandbox edit` in the CLI) — preferred for changing existing files. Provide exact\n  `old_text`→`new_text` edits. Each `old_text` must be unique in the file\n  unless you set `replace_all`. All edits in a call apply atomically\n  (all-or-nothing) and you get a unified diff back. Pass `dry_run: true` to\n  preview the diff without writing.\n- **`write_file`** (`sandbox write` in the CLI) — for creating new files. To overwrite an existing file you\n  must pass `overwrite: true` (it never silently clobbers).\n- **`run_command`** (`sandbox run` in the CLI) — run any bash command in the sandbox (build, install,\n  scaffolding, codemods). The working directory defaults to the app root; `cd`\n  does not persist across calls, so use the `cwd` parameter or chain commands\n  (`cd sub && cmd`). Timeout defaults to 120s (max 600s); output is capped at\n  ~1 MB.\n- **`create_checkpoint`** (`sandbox checkpoint` in the CLI) — save a named\n  restore point the user can later roll back to. Takes an optional `name`\n  (message/title; auto-generated if omitted). Any pending changes are **flushed\n  and committed first** so the checkpoint anchors to your latest code; it then\n  returns the checkpoint id, name, and git commit hash. Use it to mark a\n  known-good state before or after a chunk of edits. (If a recent auto-commit\n  can't be confirmed durable yet, it refuses with the retryable\n  `COMMIT_FLUSH_PENDING` rather than checkpoint stale state — retry shortly.)\n\nExample:\n\n```\nOn appId <APP_ID>, use edit_file to change the homepage heading in\nsrc/pages/Home.jsx from \"Welcome\" to \"Welcome back\". Show me the diff first\nwith dry_run, then apply it.\n```\n\n---\n\n## 5. Preview and verify (the edit → check loop)\n\nThere is no live log-streaming tool, but you can close the feedback loop:\n\n- **See it live:** `get_app_preview_url` brings up the dev server and returns\n  the preview URL. Vite HMR reflects your edits as you make them.\n- **Build status:** `get_app_status` returns `ready` / `processing` / `error`.\n- **Surface build/type/lint errors on demand** with `run_command`:\n  ```bash\n  npm run build       # bundler/compile errors\n  npx tsc --noEmit    # type errors\n  npm run lint        # lint errors\n  ```\n- **Read the dev-server (Vite) logs** — the managed dev server writes to\n  `/tmp/vite.log`. Tail it via `run_command` to see HMR/compile errors:\n  ```bash\n  tail -c 32000 /tmp/vite.log\n  ```\n  (This is outside the app tree, so it's only reachable through `run_command`,\n  not the file tools — and therefore needs `sandbox:write`.)\n\nA solid loop: `edit_file` → `npm run build` (or tail `/tmp/vite.log`) → fix any\nerrors → `get_app_preview_url` to eyeball it.\n\n> **Browser-runtime errors** (a component that compiles but throws on render,\n> a failing client API call) appear in the browser console, not in\n> `/tmp/vite.log`. Open the preview URL to catch those.\n\n---\n\n## 6. How your changes persist\n\nYou don't need to \"save.\" Every mutating call schedules a **debounced\nauto-commit** (~5 seconds): the change is committed and pushed to Base44's code\nstorage, so it:\n\n- survives sandbox death (the sandbox is recreated from the last commit),\n- appears in the builder's Library/Data tabs,\n- keeps backend-function deploys consistent, and\n- is included when you publish the app.\n\nPractical implications:\n\n- There's a small loss window (~5s) — don't kill the session immediately after\n  the last edit; give it a moment to commit.\n- Edits to entities, agents, workflows, backend functions, and page routing are\n  synced into Base44 automatically after the commit. Plain page/component/CSS\n  edits live in git and need nothing extra.\n\n---\n\n## 7. Concurrency: you vs. the Base44 builder\n\nYou and the in-app Base44 builder can't mutate the same app at once:\n\n- **While you're actively using the sandbox tools**, the Base44 builder chat is\n  blocked (\"An external agent is currently working on this app\"). Your session\n  is implicit — recent tool calls *are* the session; it ends after a short idle\n  period (~10 min).\n- **If the Base44 builder is mid-build**, your mutating tools return\n  `BUILDER_BUSY`. Poll `get_app_status` and retry once it's `ready`. Read-only\n  tools still work during a build.\n\n---\n\n## 8. Guardrails & limits\n\n- **Paths are confined to the app.** File tools operate only within the app\n  directory; traversal/absolute paths are rejected (`PATH_OUTSIDE_SANDBOX`).\n- **`.agents/` is off-limits to file tools** (`PROTECTED_PATH`) — it holds\n  agent-managed config and secrets (`.agents/.env`). Don't try to read or edit\n  it through the file tools.\n- **Rate limits** apply per app: reads ~120/min, mutations ~60/min, commands\n  ~30/min. If you hit `RATE_LIMITED`, slow down.\n- **`delete_file` isn't a dedicated tool** — delete via `run_command rm`.\n\n### Error codes you may see\n\n`NOT_AUTHORIZED` (missing scope/flag) · `APP_NOT_FOUND` (wrong id or no access)\n· `PATH_OUTSIDE_SANDBOX` · `PROTECTED_PATH` · `NOT_FOUND` · `BINARY_FILE` ·\n`EDIT_TEXT_NOT_FOUND` · `EDIT_TEXT_NOT_UNIQUE` (make `old_text` unique or use\n`replace_all`) · `OVERWRITE_NOT_ALLOWED` (pass `overwrite: true`) · `TIMEOUT` ·\n`OUTPUT_TRUNCATED` · `BUILDER_BUSY` ·\n`COMMIT_FLUSH_PENDING` (a pending auto-commit isn't durable yet; retry shortly —\ne.g. on `create_checkpoint`) · `RATE_LIMITED` · `BACKEND_ERROR`.\n\nMessages are written so the agent can self-correct — read them and adjust.\n\n---\n\n## 9. Tips & tricks\n\n- **Read before you write.** A quick `list_directory` + `read_file` (or `grep`)\n  pass costs little and dramatically improves edit accuracy.\n- **Use `dry_run` on `edit_file`** to confirm the diff before committing to a\n  change, especially for multi-edit calls.\n- **Prefer `edit_file` over `write_file`** for existing files — surgical edits\n  avoid clobbering and produce a reviewable diff.\n- **Read line ranges** with `read_file`'s `offset`/`limit` on large files\n  instead of pulling the whole thing into context.\n- **When something \"looks broken,\" tail `/tmp/vite.log`** before guessing —\n  it usually names the exact file and line.\n- **Let it commit.** Pause a few seconds after your final edit so the auto-commit\n  lands before you disconnect or publish.\n- **Checkpoint known-good states.** Use `create_checkpoint` (`sandbox checkpoint`)\n  to mark a restore point before or after a risky chunk of edits — it flushes\n  pending changes first, so the user can always roll back to that point.\n- **One agent at a time.** The feature is designed for a single external agent\n  per app; don't run parallel sessions against the same app.\n\n---\n\n## 10. Local agents via the `base44 sandbox` CLI\n\nIf your agent runs on your machine, it can drive the same sandbox through the Base44 CLI instead of\nMCP, authenticating with the Base44 CLI instead of OAuth. Same tools, same behavior, same error\ncodes (Section 8) — only the surface and auth differ.\n\n**Auth.** Log in with the Base44 CLI (`base44 login`) — the same credential used for\n`base44 functions deploy`. Like the projectless `base44 connectors` commands, the sandbox\nsubcommands resolve the app id from `--app-id`, then `BASE44_APP_ID`, then a local `.app.jsonc`;\nno `config.jsonc` is required.\n\n**Command names.** The CLI exposes each sandbox tool under a shorter name:\n\n| MCP tool | CLI command |\n|---|---|\n| `list_directory` | `base44 sandbox ls` |\n| `read_file` | `base44 sandbox read` |\n| `write_file` | `base44 sandbox write` |\n| `edit_file` | `base44 sandbox edit` |\n| `run_command` | `base44 sandbox run` |\n| `grep` | `base44 sandbox grep` |\n| `create_checkpoint` | `base44 sandbox checkpoint` |\n\n```bash\nnpx base44 sandbox read --app-id <APP_ID> src/App.jsx\n```\n\n`base44 sandbox checkpoint` takes an optional `--name` (message/title) and saves a restore point:\n\n```bash\nnpx base44 sandbox checkpoint --app-id <APP_ID> --name \"before refactor\"\n```\n\n**Hand an agent the full reference** for a specific app (instructions, public, no\nauth needed to fetch):\n\n```\nhttps://app.base44.com/api/sandbox/<APP_ID>/local-agent/readme.md\n```\n\n(The cloud/MCP equivalent is `.../api/sandbox/<APP_ID>/claude-web/readme.md`.)\n\nEverything else in this skill — the edit→preview→verify loop (Section 5), persistence\n(Section 6), concurrency (Section 7), and guardrails (Section 8) — applies identically; only the\nsurface and auth differ.\n\n---\n\n## 11. Connectors (OAuth integrations)\n\nBeyond the sandbox file/shell tools, the Base44 MCP server exposes two tools for managing a\nthird-party OAuth connector (Google Calendar, Gmail, Slack, …) on an app. They don't touch the\nsandbox filesystem — they operate on the app's connector state directly. Both take `appId`.\n\n| Tool | Scope | Purpose |\n|---|---|---|\n| `list_connectors` | `apps:read` | List the app's connectors. With no `integrationTypes`, returns the full catalog (name, description, connected?, and — if connected — status and granted scopes). Pass `integrationTypes` for detail on specific ones. |\n| `initiate_connector_connection` | `apps:write` | Connect (or re-scope) a connector. Inputs: `appId`, `integrationType`, `scopes`, optional `connectionConfig`. |\n\nTwo semantics to get right:\n\n- **Declarative scopes (replace, not merge).** `initiate_connector_connection` sets the connector\n  to **exactly** the `scopes` you pass. Omitted scopes are removed and the user is re-prompted to\n  consent. **Always call `list_connectors` first**, then pass the complete desired set (existing\n  scopes you want to keep **plus** any new ones).\n- **OAuth needs a human.** The tool returns either `already_authorized: true` (nothing to do) or a\n  `redirect_url` the **user** must open in a browser to sign in and consent — you can't complete it\n  yourself. After they finish, call `list_connectors` again to verify and read the **granted**\n  scopes (a provider may grant fewer than requested).\n\nThese need only `apps:read` / `apps:write` — **not** `sandbox:write`. Over the CLI surface\n(Section 10), the equivalent is the projectless `base44 connectors` commands\n(`list-available`, `initiate --integration-type <t> --scopes <s...> --app-id <id>`, `pull`), which\nprint the same authorization URL.\n"
}