🧹 desktop-organizer

See every move before anything moves.

🗂️  Documents, screenshots, installers, archives, and code projects have taken over your Desktop? 👀  You want a clean workspace, but you want to review every proposed move first? 🛡️  You need automation that treats uncertain files, shortcuts, and conflicts carefully?

✨ desktop-organizer turns clutter into a reviewable plan.

Folder → dry-run plan → your approval → safe moves → verification

✨ Highlights · ⚡ Install · 🚀 Usage · 🎬 Demo · 🛡 Safety · 🧭 Classification · 📂 Structure

中文 · Español · Deutsch · 日本語 · Русский · Português · 한국어

---

✨ Highlights

Desktop Organizer is a privacy-safe Codex skill for organizing the top level of a Windows Desktop or another local folder.

Stage	What happens	What stays under your control
🔎 Inspect	Reads top-level items and lightweight project markers	No filesystem changes
🧭 Classify	Proposes six purpose-based destinations	Ambiguous items go to the inbox
👀 Preview	Prints a complete dry-run plan	Nothing moves
✅ Approve	Waits for explicit confirmation	-Execute is required
📦 Move	Moves only conflict-free items	No deletes and no overwrites
🔍 Verify	Reports moved, skipped, and failed items	Locked items remain in place

Core loop: Inspect → Plan → Approve → Execute → Verify

---

⚡ Install

Give your Agent this line:

Install the desktop-organizer skill for me: https://github.com/okht/desktop-organizer/tree/main/skills/desktop-organizer

The Agent can place the skill in the active Codex skills directory. Start a new Codex turn after installation, then invoke $desktop-organizer.

🛠️ Prefer to install it yourself? Open the PowerShell steps

git clone https://github.com/okht/desktop-organizer "$env:TEMP\desktop-organizer"

$source = Join-Path $env:TEMP 'desktop-organizer\skills\desktop-organizer'
$target = Join-Path $env:USERPROFILE '.codex\skills\desktop-organizer'

if (Test-Path -LiteralPath $target) {
  throw "Skill already exists at $target"
}

New-Item -ItemType Directory -Path (Split-Path $target) -Force | Out-Null
Copy-Item -LiteralPath $source -Destination $target -Recurse

Installed location:

%USERPROFILE%\.codex\skills\desktop-organizer

---

🚀 Usage

For your Desktop:

Use $desktop-organizer to scan my Desktop, show a safe dry-run organization plan, and wait for confirmation before moving anything.

For another folder:

Use $desktop-organizer on C:\path\to\folder. Show the complete dry-run plan first and wait for my approval.

The expected conversation is short:

Step	You or the Agent
1	The Agent inspects the selected folder
2	The skill prints category counts and the proposed mapping
3	You approve the plan or change the taxonomy
4	The Agent reruns the script with -Execute
5	The Agent verifies the resulting folder state

⌨️ Run the bundled script directly

$script = Join-Path $env:USERPROFILE '.codex\skills\desktop-organizer\scripts\desktop-organizer.ps1'

# Dry-run: inspect and print the plan
powershell -ExecutionPolicy Bypass -File $script -DesktopPath ([Environment]::GetFolderPath('Desktop'))

# Execute: use only after approving the dry-run
powershell -ExecutionPolicy Bypass -File $script -DesktopPath ([Environment]::GetFolderPath('Desktop')) -Execute

---

🎬 Demo

Given a folder with these items:

Item	Signal	Proposed destination
product-research.pdf	Work keyword	01_Work_Career
course-notes.docx	Learning keyword	02_Learning_Projects
screenshot.png	Media extension	03_Media_Assets
installer.exe	Installer extension	04_Archives_Installers
sample-app/ with package.json	Code marker	05_Code_Projects
meeting-notes.pdf	Ambiguous document	00_Inbox_Review
project-shortcut.lnk	Shortcut	Left untouched

The first run remains read-only:

Mode: DRY-RUN
Move candidate count: 6

No files were moved. Re-run with -Execute only after user confirmation.

---

🛡 Safety by design

Guardrail	Behavior
👀 Dry-run first	The default mode only prints a plan
✅ Explicit approval	Moving requires a separate -Execute run
🗑️ No deletion	The bundled script contains no delete operation
🚫 No overwrite	Any destination conflict stops the run before moves begin
🔗 Shortcut protection	.lnk, .url, and desktop.ini stay untouched
📥 Safe fallback	Unknown items go to 00_Inbox_Review
📍 Root boundary	Generated destinations must remain under the selected folder
🔒 Locked-item handling	Failures are reported; locked items remain where they are

The public skill contains generic rules only: no usernames, private filenames, project names, credentials, or machine-specific absolute paths. The bundled PowerShell script performs local filesystem operations and makes no network requests.

---

🧭 How classification works

The script checks reusable signals in order:

1. Project markers such as .git, package.json, pyproject.toml, Cargo.toml, and solution files.
2. Generic keywords for work, learning, media, archives, and code.
3. File extensions for media, archives, installers, documents, and source code.
4. Inbox fallback for anything uncertain.

Default folder	Typical contents	Override parameter
00_Inbox_Review	Ambiguous files and folders	-InboxFolder
01_Work_Career	Resumes, portfolios, interviews, product work, research	-WorkFolder
02_Learning_Projects	Courses, assignments, theses, capstones	-LearningFolder
03_Media_Assets	Images, screenshots, fonts, audio, video	-AssetsFolder
04_Archives_Installers	Archives, installers, backups	-ArchiveFolder
05_Code_Projects	Repositories, scripts, source files	-CodeFolder

Treat the taxonomy as a starting point. Ask the Agent to rename categories or revise assumptions, then review the updated dry-run before execution.

---

📂 Project structure

desktop-organizer/
├── README.md
├── LICENSE
└── skills/
    └── desktop-organizer/
        ├── SKILL.md
        ├── agents/
        │   └── openai.yaml
        └── scripts/
            └── desktop-organizer.ps1

The skill follows the AgentSkills folder convention and includes Codex UI metadata under agents/openai.yaml.

---

📌 Notes

• Windows PowerShell 5.1 or newer is recommended.
• The script classifies top-level items only; it does not reorganize the contents of ordinary folders.
• Code-project detection reads only lightweight markers directly inside a candidate directory.
• A conflict stops the complete execution before target folders or moves are created.
• A locked item is reported while other conflict-free moves continue.
• Review the dry-run whenever you change the selected folder or category names.

Issues and pull requests are welcome.

---

A calmer workspace, with every move still yours to approve.

MIT License © okht