A folder report built in a small Claude Code session
A crowded Downloads folder is a useful place to begin with a command-line tool. You might want to know how many PDFs, images, and archives it contains without opening every file. This is a small enough job to describe clearly, build with Claude Code, and check yourself.
The result will be a Python program called folder_report.py. It will read a folder and print a summary. It will not rename, move, or delete anything.
§ Start with a task you can explain
A command-line tool is a program you run by typing a command in a terminal. Instead of clicking through a window, you give the program an instruction, sometimes followed by a folder name or an option.
For this project, the intended command is python folder_report.py ./sample-files. On systems where Python is installed as python3, use that instead. The final part names the folder to inspect.
Keep the first version narrow:
- Count files directly inside the chosen folder.
- Group them by extension, such as .pdf or .jpg.
- Report their combined size in bytes.
- Put files without an extension in a separate group.
- Show a readable error if the folder cannot be inspected.
Leave nested folders for later. A smaller specification makes both the generated code and its behavior easier to understand.
§ Prepare the working folder and connection
You need Python, Claude Code, and a terminal. Create an empty project folder, open your terminal there, and start Claude Code using the setup instructions for your system. Keep this project separate from important documents while you learn.
If you use Vana API for the connection, it provides one endpoint at https://api.vanaapi.com that supports OpenAI-compatible requests, Anthropic Messages, and Gemini native protocols. Its Anthropic Messages support is what makes it useful with Claude Code.
Create a Vana API account to obtain an API key, then follow the current Claude Code connection instructions to configure the base URL and authentication. Keep the key out of prompts, source files, and version control. Vana API bills per real token with no monthly fee; the coding session uses tokens, while this finished local script will not need an API connection.
§ Give Claude Code a concrete first prompt
A useful prompt describes the output and the boundaries, not just the general idea. You could write:
Build a beginner-friendly Python command-line tool named folder_report.py. Use only the Python standard library. Accept one folder path and summarize its immediate files by lowercase extension, showing counts and total bytes. Skip subfolders and symbolic links. Handle missing paths and permission errors clearly. Never modify files. Add a short README and automated tests.
Ask Claude Code to explain its plan before editing. Review any requested permissions, especially commands it proposes to run. Permission to help with the project is not a reason to allow unrelated changes elsewhere on your computer.
§ Check the result with files you understand
Make a sample-files folder containing a few disposable files: two with a .txt extension, one with an uppercase .TXT extension, and one without an extension. Add an empty subfolder too.
Run the proposed command. The three text files should appear in the same group, the extensionless file should have its own group, and the subfolder should not count as a file. Compare reported sizes with the actual files.
Also try a nonexistent folder and a file path where a folder is expected. Ask Claude Code to run the automated tests and explain failures. Passing tests help, but checking the visible output yourself remains important.
§ Add one option, then stop
Once the basic tool behaves correctly, ask for an optional --recursive flag to include nested folders. Keep the default unchanged, continue skipping symbolic links, and request tests for the new behavior.
This is a useful stopping point. You have a tool with a clear purpose, a small interface, and checks you can repeat. Claude Code helped write it, but the specification and verification stayed in your hands.