BccFS – brainCloud Cloud Code File System

BccFS is a Visual Studio Code extension for browsing, editing, and syncing brainCloud Cloud Code scripts directly within the editor. It works both as a standalone virtual file system and as a companion to any existing workspace.

✨ Features

Virtual File System

• Automatically selects the last-used brainCloud team from your portal login.
• Displays brainCloud Apps as top-level folders in the VS Code file explorer.
• Lists all Cloud Code scripts for each App.
• Full support for creating, opening, saving, deleting, and renaming scripts.
• Switch teams at runtime without restarting the editor.
• View and edit script metadata (permissions, author, description) from a dedicated panel.
• Enhanced editing experience with brainCloud service code completion and script validation.

Offline Folder Sync

Link any local folder to a brainCloud App for bidirectional sync without leaving your normal workspace:

• Local → Cloud: Edit .ccjs files in your regular Explorer. On save, a "Sync Now?" prompt appears so you can push changes to the cloud immediately.
• Cloud → Local: Changes made by other users or via the portal are detected automatically. A "Refresh Now?" prompt appears so you can pull them down right away.
• Background polling checks the cloud every ~10 seconds for new or modified scripts without downloading content unless you choose to sync.
• Sync status badges decorate linked folders and files in the Explorer:
  • ↑ — local edits pending push to cloud
  • ↓N — N cloud changes ready to pull
  • 🔗 — folder is linked and in sync

Git Branch → App Mapping

• Map git branches to specific brainCloud Apps (e.g. develop → Dev App, main → Production App).
• Switching branches automatically activates the correct App and suppresses spurious sync events caused by git's working-tree changes.
• Branch mappings are stored in a .bcsync file that can be committed and shared across your team so everyone uses the same branch-to-app rules.
• Per-machine sync state is stored in .bcsync.local (gitignored automatically) so local metadata never pollutes the shared repo.

Activity Bar Integration

• Displays current connection and workspace status at a glance.
• Shows all linked offline folders with their active branch and pending sync counts.
• Quick-access buttons for push, pull, and folder management.
• Access features including:
  • Login and connect to a brainCloud workspace
  • View logged-in user and team information
  • View and edit the server in use
  • Switch between brainCloud teams
  • Reset all client-side data to recover from errors
  • View extension version and open the details page

Status Bar Integration

• Shows connection status, server, and extension version at all times.
• Click when disconnected to reconnect.
• Click when connected to view environment/user details or log out.

Live App Protection

• Live Apps display a lock indicator in the explorer.
• Right-click and select Toggle Lock to enable edit mode.
• Locked apps do not persist local edits, preventing accidental changes to production scripts.

Works with the brainCloud MCP

BccFS and the brainCloud MCP server (used by AI assistants such as Claude) can operate on the same linked folder at the same time. They cooperate through the shared sync-state file rather than through a live connection:

• Both tools read and write .bcsync.local using the same shared format (@braincloud/cloudsync-core) — The canonical map of each script's scriptId, version, and content hash.
• Because they share that base state, edits made through the MCP and edits made in VS Code merge against a common baseline instead of overwriting each other. No re-baselining or manual reconciliation is required.
• The extension behaves identically whether or not the MCP is installed — there is no separate mode. The MCP is simply a second editor of the same scripts; BccFS's normal background polling and three-way merge pick up its changes like any other cloud edit.

You do not need the MCP to use BccFS, and you do not need BccFS to use the MCP. Install the MCP only if you also want AI-assisted cloud-code workflows alongside the editor.

🚀 Getting Started

Option A — Activity Bar (recommended)

1. Install BccFS from the Visual Studio Code Marketplace.
2. Select the brainCloud icon in the Activity Bar.
3. Click Connect to brainCloud.

Option B — Command Palette

1. Install BccFS from the Visual Studio Code Marketplace.
2. Open the Command Palette (F1 or Ctrl+Shift+P) and run brainCloud: Open Workspace.
3. Optionally save the resulting workspace file for future sessions.

Setting Up Offline Sync

1. Connect to brainCloud (see above).
2. Open the Command Palette and run brainCloud: Link Folder to brainCloud App.
3. Choose the local folder you want to sync and the App to link it to.
4. If your folder is a git repo, run brainCloud: Link Branch to App to map branches to Apps.
5. Run brainCloud: Pull Cloud to Folder for an initial download of all cloud scripts.

From that point on, saving a .ccjs file prompts you to sync to the cloud, and cloud changes prompt you to refresh locally.

(Optional) Adding the brainCloud MCP

If you also want AI-assisted cloud-code workflows, add the hosted brainCloud MCP server to your MCP-compatible client (Claude Code, the Claude.ai MCP connector, etc.). It is added by URL, and the client runs the OAuth login flow on first use:

• Production: https://mcp.braincloudservers.com/mcp

For example, in Claude Code:

claude mcp add --transport http braincloud https://mcp.braincloudservers.com/mcp

The MCP and BccFS can then share the same linked folder — see Works with the brainCloud MCP above.

⚙️ Available Commands

Access all functionality via the Command Palette (F1 or Ctrl+Shift+P) by typing brainCloud.

🔧 Workspace & Team Management

• brainCloud: Open Workspace — Initializes a brainCloud workspace. (Visible only when not connected)
• brainCloud: Close Workspace — Closes the active brainCloud session.
• brainCloud: Switch brainCloud Team — Switch to another team on your account.
• brainCloud: Open Server in Browser — Opens the configured server URL in your browser.
• brainCloud: Edit Server Configuration — View or update the current server configuration.
• brainCloud: Logout — Ends the current brainCloud session.
• brainCloud: Reset Client Info — Clears local data (team, server, cache) to resolve client-side issues.
• brainCloud: Show Extension Details — Opens the extension details page in VS Code.

📂 Offline Sync

• brainCloud: Link Folder to brainCloud App — Link a local folder to a brainCloud App for bidirectional sync.
• brainCloud: Link Branch to App — Map the current git branch to a specific App.
• brainCloud: Show Local Sync Status — View all linked folders, their branch mappings, and pending sync counts.
• brainCloud: Sync Local to Cloud — Push all local changes in a linked folder to the cloud.
• brainCloud: Pull Cloud to Folder — Pull all cloud scripts into a linked folder.
• brainCloud: Sync with brainCloud — Push a single .ccjs file to the cloud (also available via right-click in the Explorer).
• brainCloud: Open Offline Folder — Reveal the linked local folder in the Explorer.

🧪 Developer & Debug Tools

Only visible when bccfs.debug is enabled.

• brainCloud: (D) Clear Team — Clears the currently selected team data.
• brainCloud: (D) Clear Config — Clears stored configuration settings.
• brainCloud: (D) Clear Cache — Clears the internal extension cache.

📂 Contextual (Right-Click) Commands

• Sync with brainCloud — Push the selected .ccjs file to the cloud.
• Link Offline Folder — Link a virtual filesystem folder to a local directory.
• Check Sync Status — Show diff status for the selected App folder.
• Open Offline Folder — Open the linked local folder in the Explorer.
• Toggle Lock — Toggle edit mode for a Live App. Locked apps do not save local edits.
• Switch brainCloud Team — Switch teams from the Explorer or status bar.
• Refresh Script Info — Reload metadata in the brainCloud Script Info panel.
• Edit Script Info — Edit permissions, author, or description inline in the Script Info pane.

🧠 Tips

• Type brainCloud in the Command Palette to see all available commands.
• If your client is stuck, use Reset Client Info and reconnect.
• If you change the server URL, use Reset Client Info before reconnecting to ensure a clean state.
• Commit .bcsync to your repo so teammates automatically inherit your branch-to-app mappings.
• .bcsync.local is added to .gitignore automatically — never commit it.
• The "Sync Now?" and "Refresh Now?" prompts only appear once per pending batch. If you dismiss them, the ↑ / ↓ badges remain so you can sync manually whenever you're ready.