DEV Community: Muhammad Usman

I built a CLI tool so I never have to write FFmpeg commands again

Muhammad Usman — Wed, 25 Mar 2026 04:24:49 +0000

If you build websites, you've been here before:

ffmpeg -i hero.mp4 -c:v libx264 -crf 23 -preset slow -movflags +faststart -c:a aac -b:a 128k out.mp4

Wrong flag order? Re-run. Need a WebM version too? Write the whole thing again with completely different flags. Forgot -movflags +faststart? Your video won't stream properly in the browser — and you won't know until a user complains.

I got tired of copy-pasting this from my notes every single project. So I built VidX.

Try it in 10 seconds

npx @muhammadusmangm/vidx

What is VidX?

VidX is an interactive CLI tool for web video optimization. Instead of memorizing FFmpeg flags, it walks you through everything with a beautiful terminal UI.

You run one command:

vidx

And it handles the rest — scanning your project for videos, letting you pick which ones to process, choosing format, quality, and resolution, then running the perfect FFmpeg command behind the scenes.

The Problem It Solves

FFmpeg is incredibly powerful — but its interface is designed for people who already know exactly what they're doing. For web developers who just need compressed, web-ready videos, it's way more friction than it should be.

The specific pain points VidX eliminates:

1. Remembering codec flags — libx264 for MP4, libvpx-vp9 for WebM, the exact CRF sweet spots for web, -movflags +faststart so videos stream before fully downloading, -pix_fmt yuv420p so Safari doesn't choke. VidX bakes all of this in.

2. Generating both formats — Modern best practice is to serve both MP4 and WebM and let the browser pick. With raw FFmpeg that means writing and running two completely separate commands. With VidX you just pick "Both" and it handles both in one run.

3. Resizing — Need to scale down a 4K video for web? VidX uses scale=-2:720 which keeps the aspect ratio and ensures the width stays divisible by 2 — something that trips up a lot of manual FFmpeg users and causes libx264 to error out.

4. Starting over every project — VidX supports a .vidxrc config file. Set your preferred preset once per project and next time you just confirm and go.

How It Works

Step 1 — Detect

VidX scans your project and lists every video file it finds, sorted by size (largest first since those are the most impactful to compress):

📁 Found 3 videos in this project:

  • src/assets/hero-banner.mp4        48.2 MB
  • public/product-demo.mov          120.4 MB
  • public/bg-loop.webm                8.1 MB

Step 2 — Select

Pick which videos to process with Space/A keys — all pre-selected by default.

Step 3 — Configure

Choose your output format, quality preset, and resolution through simple menus — no flags, no docs.

Step 4 — Process

VidX runs FFmpeg with a real-time progress bar showing percentage and ETA per file.

Step 5 — Summary

See exactly how much space you saved, and the exact FFmpeg commands that were used — so you learn as you go.

🎉 Done! 2 videos processed in 43s

  hero-banner.mp4
    → hero-banner.mp4     48.2 MB  →   4.1 MB   (91% smaller) ✔
    → hero-banner.webm    48.2 MB  →   2.8 MB   (94% smaller) ✔

Quality Presets

VidX ships with three tuned presets:

Preset	Best For
Web Optimized	Most websites — great balance
High Quality	Hero videos, product showcases
Small File	Background loops, mobile-first
Custom	Full manual control

Each preset uses carefully chosen CRF values, bitrate caps, and codec settings that I've tuned specifically for web delivery — not just generic FFmpeg defaults.

FFmpeg Auto-Detection

VidX checks if FFmpeg is installed on your system first. If it is, it uses it. If not, it silently falls back to a bundled static binary — so it works on any machine with zero manual setup.

CI/CD Mode

VidX also supports a fully non-interactive mode for build pipelines:

vidx --preset webOptimized --format both --resolution 720p --yes

And a --dry-run flag that prints the FFmpeg commands without executing them — useful for debugging or learning.

Tech Stack

Built with Node.js using:

@inquirer/prompts for the TUI
cli-progress + ora for progress display
chalk for terminal colors
fast-glob for video detection
ffmpeg-static as the bundled fallback binary

Installation

npm install -g @muhammadusmangm/vidx
# or
npx @muhammadusmangm/vidx

Requires Node.js 18+. Works on macOS, Windows, and Linux.

What's Next

VidX v1 is live on npm right now. I'm actively maintaining it and would love feedback — if you try it, let me know what you think in the comments or open an issue on GitHub.

If it saves you time, a ⭐ on the repo goes a long way.

🔗 npm: npmjs.com/package/@muhammadusmangm/vidx

🔗 GitHub: github.com/MuhammadUsmanGM/VidX

Built for web devs, by a web dev who got tired of FFmpeg flags.

Notion Reverse Autopilot - AI That Watches Your Chaos and Builds Order

Muhammad Usman — Tue, 24 Mar 2026 13:41:23 +0000

This is a submission for the Notion MCP Challenge

What I Built

Notion Reverse Autopilot - an AI agent that flips the productivity paradigm on its head.

Every productivity tool assumes you're organized. This one assumes you're not - and fixes it autonomously.

You dump random notes, half-thoughts, and messy content into Notion. The agent does the rest:

Scans your entire workspace through Notion MCP and generates a Chaos Score (0-100)
Categorizes every page using AI — project, idea, task, journal, reference, etc.
Discovers hidden connections between pages you never linked yourself
Generates cognitive insights — your thinking patterns, blind spots, contradictions, and predictions
Auto-annotates pages with category/tag/summary callouts
Creates a Brain Briefing — a rich Notion page with your workspace health, cognitive profile, and what you'll likely need next
Builds an Autopilot Dashboard with health scores, chaos breakdown, and top insights
Groups pages into Topic Clusters automatically
Runs on schedule — set it and forget it, your workspace organizes itself every X hours

The core idea: you stay messy, the AI builds order — and understands you better than you understand yourself.

Key Highlights

Multi-provider AI — works with Groq (free), Google Gemini (free), Ollama (free/local), or Anthropic. Zero cost to run.
Full changelog — every action the agent takes is logged for transparency and undo
CLI-first — clean terminal interface powered by Rich. Scan, organize, briefing, schedule, history — all one command away.
Chaos detection — tracks untagged pages, orphan content, duplicates, empty pages, structureless content, and more
Smart rescanning — after organizing, the agent recognizes its own annotations and the chaos score drops accordingly

Video Demo

Show us the code

MuhammadUsmanGM / notion-reverse-autopilot

Notion Reverse Autopilot

Your workspace organizes itself.

Most productivity tools assume you're organized. This one assumes you're NOT — and fixes it autonomously.

Notion Reverse Autopilot is an AI agent that continuously watches your messy Notion workspace, auto-organizes everything, discovers hidden patterns about how you think, and surfaces insights you never knew existed.

"What if you never had to organize Notion again — and it actually understood you better than you understand yourself?"

How It Works

You dump chaos into Notion
        |
        v
┌─────────────────────────┐
│   Workspace Scanner     │  Crawls every page, database, block
└────────┬────────────────┘
         v
┌─────────────────────────┐
│   AI Analysis Engine    │  Categorizes, finds connections,
│                         │  detects cognitive patterns
└────────┬────────────────┘
         v
┌─────────────────────────┐
│   Auto-Organizer        │  Tags pages, links related ideas,
│                         │  builds topic clusters & dashboards
└────────┬────────────────┘
         v
┌─────────────────────────┐
│   Brain Briefing        │  Health score, hidden connections,
│                         │  contradictions, predictions
└─────────────────────────┘

You stay messy. The AI builds order.

…

View on GitHub

Tech Stack

Layer	Technology
Notion Integration	Official `@notionhq/notion-mcp-server` via MCP stdio protocol
MCP Client	Python `mcp` SDK with auto-discovery of tools
AI Engine	Google Gemini / Groq / Ollama / Anthropic (user's choice)
CLI	Click + Rich
HTTP	httpx (for LLM API calls)
Package Manager	uv

How I Used Notion MCP

Notion MCP is the core backbone of this project. Every single interaction with Notion — reading pages, scanning content, creating dashboards, writing annotations — goes through the official MCP server. No direct REST API calls.

Architecture

CLI Command (scan / organize / briefing)
│
▼
Python MCP Client (mcp SDK)
│ stdio transport
▼
@notionhq/notion-mcp-server (spawned as subprocess via npx)
│
▼
Notion Workspace (read + write)

How MCP is integrated

1. Auto-discovery at startup
When the agent connects, it calls session.list_tools() to discover all 22 available MCP tools dynamically. It then resolves each logical operation (search, create page, append blocks, etc.) to the correct tool name using a deterministic mapping. This makes the agent forward-compatible with any future MCP server version.

2. Reading the workspace
The agent uses MCP's API-post-search to crawl every page and database in the workspace, then API-get-block-children to read the full content of each page — all through the MCP protocol.

3. Writing back to Notion
After AI analysis, the agent writes results back through MCP:

API-post-page — creates the Autopilot Hub, Dashboard, Brain Briefing, and Topic Clusters pages
API-patch-block-children — appends annotation callouts to existing user pages and updates the dashboard with scan results

4. Full read-write loop
The complete cycle — scan → analyze → organize → briefing — is a full MCP read-write loop. The agent reads your chaos through MCP, processes it with AI, and writes the organized structure back through MCP. On the next scan, it reads its own annotations through MCP to recognize already-organized pages.

What MCP unlocks

Without MCP, this would require direct REST API calls with manual auth headers, pagination handling, and rate limiting. MCP provides:

Standardized tool interface — one protocol for all Notion operations
Server-managed auth — token passed via environment, not per-request headers
Version-agnostic — auto-discovery means no hardcoded endpoints that break on API changes
Composable — the same agent architecture could connect to multiple MCP servers (Notion + Slack + GitHub) in the future

Notion MCP turns Notion from a document store into a programmable workspace brain — and this project proves it by making that brain self-organizing.

7 Mistakes I Made With Claude Code (And How I Fixed Them)

Muhammad Usman — Sun, 22 Mar 2026 12:19:35 +0000

I've been using Claude Code daily for months. It lives in my terminal, it knows my codebases, and on a good day it feels like pairing with a senior engineer who never gets tired.

On a bad day, it wastes my time, hallucinates conventions, and racks up token costs for nothing.

The difference between those two experiences? Almost entirely configuration and habits — not the tool itself. After enough frustration, I started documenting what actually works. That turned into a GitHub repo of Claude Code best practices — guides, real CLAUDE.md templates, hook scripts, MCP configs, and a contributing workflow for teams.

Here's what I wish I'd known from day one.

Mistake 1: Not having a CLAUDE.md file

This was the biggest one. Without a CLAUDE.md, Claude has no idea what your project does, where things live, or what conventions your team follows. It guesses — wrong test commands, wrong file locations, wrong code style.

CLAUDE.md is a Markdown file you commit to your repo root. Claude reads it automatically at the start of every session. Here's a minimal one that actually works:

# MyApp

Node.js/Express backend with PostgreSQL.

## Commands
- `npm test` — run tests
- `npm run lint` — ESLint check
- `npm run dev` — start dev server

Run `npm run lint && npm test` before committing.

## Structure
- `src/routes/` — API route handlers
- `src/models/` — Sequelize models
- `src/middleware/` — Express middleware

## Rules
- TypeScript strict mode — no `any`
- All API responses: `{ data, error, status }`
- Use `src/utils/logger.ts`, not console.log

Twenty lines. Claude now knows your commands, your structure, and your rules — every session, without you repeating yourself.

The repo has ready-to-use CLAUDE.md templates for React/TypeScript, Python/FastAPI, monorepos, and a minimal starter.

Mistake 2: Writing vague prompts

I used to say things like "fix the bug" or "clean up this file." Claude would explore broadly, make assumptions, and often miss the point entirely.

The fix is embarrassingly simple: be specific.

# Bad
"fix the bug"

# Good
"fix the null reference error in src/auth/login.ts:42
 where user.email is accessed before the null check"

Point Claude at the file. Give it the line number if you have it. Tell it the symptom and the expected behavior. The more specific you are, the fewer tokens Claude wastes exploring, and the better the result.

Mistake 3: Never running /compact

Every message you send gets more expensive as the conversation grows — all that history is re-sent with each new message. I used to let sessions run for 80–100 exchanges without thinking about it.

/compact summarizes the conversation history, dramatically cutting context size. I now run it after every completed subtask:

/compact focus on the auth refactor

The optional focus hint tells the compressor what to preserve. Everything else gets aggressively summarized.

Rule of thumb: /compact every 20–30 exchanges, or whenever you finish one piece of work and move to the next.

Mistake 4: Using --dangerously-skip-permissions in the wrong places

This flag disables all permission prompts. Claude can read, write, execute, and commit without asking. It's necessary for CI pipelines — but I made the mistake of using it locally on repos containing production credentials.

The rule I follow now:

CI/CD pipelines and containers → --dangerously-skip-permissions is fine and necessary
Local development on anything sensitive → never

In CI, pair it with --allowedTools to limit the blast radius:

claude -p "review src/ for bugs" \
  --dangerously-skip-permissions \
  --allowedTools "Read,Grep,Glob"  # read-only, no writes

Full CI/CD patterns are in the CI and Automation guide.

Mistake 5: No .claudeignore file

Claude can read any file in your project. Without a .claudeignore, that includes your .env files, private keys, and credential configs.

.claudeignore uses the same syntax as .gitignore and lives at your project root:

.env
.env.*
credentials/
*.pem
*.key
secrets.yaml

Files matching these patterns are completely invisible to Claude. Use it liberally — there's no cost to ignoring files Claude doesn't need. More security patterns are in the Security Practices guide.

Mistake 6: Trying to do too much in one session

I used to start a session and just keep going — bug fix, new feature, refactor, PR description — all in one 120-message conversation. By the end, Claude was confused about which decisions we'd made and why.

Claude works best with focused sessions. One goal per session. When you're done, commit and start fresh.

For large tasks touching more than a handful of files, use plan mode first:

plan how to refactor the authentication system to use JWT

Review the plan. Ask questions. Only then:

looks good, go ahead and implement it

Mistake 7: Not setting up hooks

Hooks let you run shell commands automatically when Claude performs an action. I went months without setting any up, which meant Claude's edits didn't always match my formatting standards and I had no audit trail.

Two hooks I now use on every project:

Auto-format after every file edit:

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Edit|Write",
      "command": "npx prettier --write \"$CLAUDE_FILE_PATH\" 2>/dev/null || true"
    }]
  }
}

Desktop notification when Claude finishes:

{
  "hooks": {
    "Notification": [{
      "matcher": "",
      "command": "osascript -e 'display notification \"$CLAUDE_NOTIFICATION\" with title \"Claude Code\"'"
    }]
  }
}

The notification sounds minor but is genuinely useful — Claude often finishes while you've switched windows and you don't notice for five minutes. More ready-to-use hook scripts are in the examples folder.

The repo

All of this — and more — is in claude-code-best-practices. It includes:

Guides on CLAUDE.md setup, context management, cost management, MCP servers, multi-agent workflows, CI/CD automation, security practices, and team setup
CLAUDE.md templates for React, Python/FastAPI, monorepos, and minimal projects
Ready-to-use hook scripts and MCP server configurations
A CONTRIBUTING.md so the community can help keep it current

If you've found patterns that work (or patterns that don't), PRs are open.

What mistakes did I miss? Drop them in the comments — if enough people have hit the same wall, I'll add a guide.