Build a Real Desktop App With Claude Code — No Coding

Meet FileFlow

For this Guide, we will build FileFlow — a simple desktop file organizer. The user selects a folder containing mixed files such as:

invoice.pdf vacation.jpg video.mp4 notes.txt archive.zip logo.png

FileFlow scans the folder and organizes the files into:

Documents Images Videos Audio Archives Code Other

Why Build This as a Desktop App?

A normal website cannot freely work with files on your computer. A desktop application can use native operating-system features such as:

- folder selection

- local filesystem access

- desktop windows

- local file processing

That makes FileFlow a good demonstration of a real desktop application.

What You Need

Install:

- Node.js

- VS Code

- Claude Code

You do not need:

- a database

- Firebase

- Supabase

- an API key

- hosting

- authentication

Create the Project Folder

Create a folder named:

fileflow

Open it in VS Code and start Claude Code. Then use:

Create the FileFlow Desktop Foundation

Scaffolds the FileFlow desktop application foundation using the latest stable Electron, Electron Forge, and TypeScript via Electron Forge's official project generator: a real Electron window with a clean minimal interface, context isolation enabled, and a preload script for privileged functionality — no unrestricted Node.js/Electron APIs exposed to the renderer, no React, Angular, Firebase, Supabase, auth, backend, cloud storage, external APIs, or analytics. Starts the app and verifies it opens as a desktop window, finishing with a READY / NOT READY verdict — nothing is committed, pushed, published, or deployed.

Build a real desktop application called FileFlow in this folder. FileFlow will eventually let users select a folder on their computer and organize its files. For this first step, create only the desktop application foundation. Use: - the latest stable Electron - Electron Forge - TypeScript - the current recommended Electron project structure Use Electron Forge's official project generator rather than manually creating an outdated Electron configuration. Before implementation, inspect the current project and use the current Electron/Electron Forge conventions available to you. Requirements: - create a real Electron desktop window - application name: FileFlow - create a clean minimal interface - remove unnecessary starter/demo content - use a secure Electron architecture - keep context isolation enabled - use a preload script for privileged desktop functionality - do not expose unrestricted Node.js or Electron APIs to the renderer Do not add: - React - Angular - Firebase - Supabase - authentication - backend services - cloud storage - external APIs - analytics Install only dependencies genuinely required by the application. Start the app when finished and verify that FileFlow opens successfully as a desktop window. Do not commit, push, publish, or deploy anything. Finish with: Desktop foundation: READY / NOT READY

NOTE

Electron recommends Electron Forge as its tooling for starting and packaging applications, especially for beginners.

Test It

Claude should provide the command to start the application, normally:

npm start

Run it. You should now see FileFlow opening in its own desktop window. Not Chrome. Not localhost in your browser. That is the first important result.

The Workflow

Now give FileFlow its actual desktop functionality. The workflow should be:

Choose Folder → Scan → Preview → Confirm → Organize

It should never move files immediately after selecting a folder.

Build the Complete File Organizer

Use:

Build the Complete FileFlow Organizer

Builds the complete first working version of FileFlow: a native folder-selection dialog, extension-based categorization (Images/Documents/Videos/Audio/Archives/Code/Other) of only the files directly inside the selected folder, a preview shown before anything changes, a disabled-until-ready Organize Files action gated behind an explicit confirmation dialog, safe unique-filename generation on collisions (never overwriting or deleting), and a completion summary. Keeps all filesystem operations in the Electron main process behind narrowly scoped, input-validated preload/IPC functions, handles errors without crashing, and builds a clean desktop-software interface — no accounts, AI features, cloud sync, backend, file deletion, or automatic background organization. Runs TypeScript checks and launches the app, finishing with a READY / NOT READY verdict.

Build the complete first working version of FileFlow. Preserve the existing Electron architecture. ## Choose Folder Add a prominent: Choose Folder button. Use Electron's native folder-selection dialog. The application must work only with the folder explicitly selected by the user. After selecting a folder, show: - folder name - folder path - total files found ## Scan Scan files located directly inside the selected folder. Do not recursively process existing subfolders. Ignore directories. Categorize files by extension. Use these categories: ### Images jpg, jpeg, png, webp, gif, svg ### Documents pdf, doc, docx, txt, rtf, csv, xls, xlsx, ppt, pptx ### Videos mp4, mov, avi, mkv, webm ### Audio mp3, wav, m4a, aac ### Archives zip, rar, 7z, tar, gz ### Code Common source-code and development file extensions. ### Other Files that do not match another category. Make extension matching case-insensitive. ## Preview Before Changing Anything After scanning, show a clear preview such as: Images — 12 files Documents — 7 files Videos — 3 files Archives — 2 files Let the user expand or inspect each category to see the filenames. Do not move files during scanning. Add: Organize Files Keep it disabled until scanning finishes successfully. ## Organize When the user clicks Organize Files: 1. Show a confirmation dialog. 2. Explain what will happen. 3. Continue only after explicit confirmation. Then create the required category folders inside the selected folder and move each file into the appropriate folder. Never delete files. Never silently overwrite existing files. If a file with the same name already exists, generate a safe unique filename. Example: photo.jpg becomes: photo (1).jpg rather than replacing the existing file. ## Completion When finished show: Organization Complete Include: - files moved - files skipped - categories used - errors Add: Choose Another Folder ## Error Handling Handle: - empty folders - permission errors - inaccessible files - files disappearing after scanning - filename conflicts - unsupported file types One failed file must not crash the entire application. ## Security Filesystem operations must happen through the Electron main process. Expose only narrowly scoped functions through the preload/context bridge. Do not expose: - unrestricted fs - unrestricted ipcRenderer - shell execution - arbitrary filesystem access directly to the renderer. Validate IPC inputs before performing filesystem operations. ## Design Create a clean professional desktop interface. Use: - clear folder information - simple category cards - readable filenames - obvious primary actions - useful loading states - confirmation states - clear success and error messages Make it feel like desktop productivity software rather than a developer tool. Do not add: - accounts - AI features - cloud sync - backend - file deletion - automatic background organization Run the relevant TypeScript checks and launch the application when finished. Do not package it yet. Finish with: FileFlow: READY / NOT READY

NOTE

Electron specifically recommends isolating privileged functionality from renderer code and exposing only narrow capabilities through preload/contextBridge APIs.

Set Up a Disposable Test Folder

Create a temporary folder called:

IMPORTANT

Do not immediately test FileFlow with your real Downloads or Documents folder.

FileFlow Test

Add copied or disposable files such as:

photo.jpg logo.png invoice.pdf notes.txt video.mp4 music.mp3 backup.zip example.json

Open FileFlow and Preview

Open FileFlow.

Choose Folder FileFlow Test

FileFlow should first show a preview. For example:

Images 2 Documents 2 Videos 1 Audio 1 Archives 1 Code 1

Nothing should have moved yet.

Organize the Folder

Organize Files Confirm

Now open the folder in Finder or File Explorer. You should see something like:

FileFlow Test │ ├── Images │ ├── photo.jpg │ └── logo.png │ ├── Documents │ ├── invoice.pdf │ └── notes.txt │ ├── Videos │ └── video.mp4 │ ├── Audio │ └── music.mp3 │ ├── Archives │ └── backup.zip │ └── Code └── example.json

This is the most important before → after moment for the video.

Test Duplicate Files

Now test something that could otherwise cause data loss.

Create:

photo.jpg

in the main test folder while this already exists:

Images/photo.jpg

Run FileFlow again. It should create something like:

Images/photo (1).jpg

It must never overwrite the existing file.

Run the Safety Audit

Use:

Audit FileFlow for Local-File Safety

Audits every code path that reads, creates, or moves files for local-file safety without adding features: only the explicitly selected folder is processed, nested directories aren't unexpectedly reorganized, no file is ever deleted or silently overwritten, filename collisions get unique names, paths are normalized and validated, malformed renderer/IPC input can't trigger arbitrary file operations, permission failures and single-file failures are handled safely, and the UI reports skipped/failed files — preserving context isolation, preload-based APIs, and main-process filesystem operations, with Node integration never enabled in the renderer. Fixes only genuine safety problems, then re-launches FileFlow and finishes with a READY / NOT READY verdict.

Audit FileFlow specifically for local-file safety. Do not add new features. Review every code path that reads, creates, or moves files. Verify: - only a folder explicitly selected by the user can be processed - nested directories are not unexpectedly reorganized - no user file is deleted - files are never silently overwritten - filename collisions create unique filenames - paths are safely normalized and validated - malformed renderer/IPC input cannot request arbitrary file operations - permission failures are handled safely - one failed file does not crash the entire operation - the UI clearly reports skipped or failed files Preserve: - context isolation - preload-based APIs - main-process filesystem operations Do not enable Node integration in the renderer. Fix only genuine safety problems. Then run the relevant checks and launch FileFlow again. Finish with: File safety: READY / NOT READY

Run the Final Pre-Package Audit

Until now, FileFlow has been running in development mode. Now turn it into an application that you can launch normally. Use:

Final Pre-Package Audit

Runs a final pre-package audit of FileFlow across core functionality (launch, Choose Folder, scanning, categorization, preview-before-changes, confirmation, organizing, safe collision handling, accurate completion summary), desktop behavior (correct title, sensible window size, works without a browser or internet connection, no leftover localhost/dev-server dependency), security (context isolation, no unrestricted Node.js access, IPC-gated filesystem access, validated paths), and technical checks (TypeScript, runtime errors, Electron Forge config, production asset paths) — without adding code signing, notarization, auto updates, publishing, or app-store configuration, fixing only what's required for safe local packaging. Finishes with a READY / NOT READY verdict.

Perform a final pre-package audit of FileFlow. Do not add new features. Verify: ## Core Functionality - FileFlow launches correctly - Choose Folder works - scanning works - categorization works - preview happens before any file changes - confirmation is required - organizing works - filename conflicts are handled safely - completion summary is accurate ## Desktop Behavior - application title is FileFlow - window opens at a sensible size - the UI works without a browser - the app does not require an internet connection - no localhost or development-server dependency remains in the packaged application ## Security - context isolation remains enabled - renderer has no unrestricted Node.js access - filesystem access remains behind narrowly scoped IPC - user-controlled paths are validated ## Technical - TypeScript checks pass - the app starts without important runtime errors - Electron Forge configuration is valid - production asset paths work correctly Do not add: - code signing - notarization - auto updates - publishing - App Store configuration - Microsoft Store configuration Fix only issues required for safe local packaging. Finish with: Package status: READY / NOT READY

Create the Desktop Build

Electron Forge supports:

npm run package

for creating a packaged application, while:

npm run make

also creates OS-specific distributables such as installers or archives depending on the configured makers. Electron's official tutorial uses Forge for this workflow. For this beginner Guide, start with:

npm run package

Open the Packaged App

Look inside:

out/

On macOS, you should find a .app bundle. Open FileFlow.app directly.

Do not run npm start. Do not open VS Code. Do not open Chrome. Just launch FileFlow normally.

Now choose another disposable test folder and organize it. If it works, Claude Code has successfully created a real packaged desktop application.

Cross-Platform Expectations

Electron applications can share one JavaScript codebase across:

- macOS

- Windows

- Linux

but packaging is platform-specific. Therefore, do not promise in this Guide that your Mac will generate and fully test every Windows installer.

The Promise

Build one cross-platform desktop application and package it for the computer you are currently using.

A Windows user can follow the same Guide on Windows. A Mac user can follow it on macOS.

Packaging vs. Publishing

There is an important difference between:

Packaging

Packaging an app

Distributing

Distributing an app publicly

Public distribution introduces things such as:

- code signing

- Apple notarization

- Windows certificates

- installers

- auto updates

- download hosting

NOTE

Electron strongly recommends code signing applications intended for distribution because macOS and Windows apply trust checks to downloaded software.

That is intentionally outside this Guide. We only need to prove:

The Point

Claude Code can build a real desktop application that runs independently on your computer.

Launch the Packaged Version

Launch the packaged version of FileFlow. Without opening Claude Code, verify:

Application launches normally

Choose Folder works

Folder preview works

Categories are correct

Nothing moves before confirmation

Organize Files works

Files appear in the correct folders

Existing files are not overwritten

Errors are handled without crashing

The application works without an internet connection

If everything passes:

Result

Desktop App: READY

What You Built

You started with an empty folder. Claude Code created:

Desktop application → Native app window → Native folder picker → Local filesystem access → File organization → No backend → No API cost → Packaged application

And FileFlow can run without Claude Code or VS Code being open.

The Complete Workflow

Claude Code → Electron → Build FileFlow → Choose Folder → Preview Changes → Organize Local Files → Test → Package → Launch as Desktop Software