Agentic Programming with AI: Creating a Small Python Port Scanner on Windows

Introduction

Today, a guide like this may seem almost useless. You can simply ask an AI, “How do I create a program?” or even “Create a program that…”, and you will probably get a long and detailed answer, maybe even better than what I can write in a blog post.

But the point is not to replace ChatGPT, Codex CLI or any other AI tool.
The point is to organize ideas.

This guide is meant to be a small starting point: a simple way to understand how to set up a project, prepare files, write prompts, use Git to keep control, and let an AI agent work in an ordered way.

Everything is very simplified.

In this guide we will use Python because today it is probably one of the easiest ways to start programming.

Python has a very readable syntax. Its instructions often look almost like English sentences. This makes it suitable for beginners, because it lets you focus on the problem, on the logic, and on how the program works, without getting lost in too many technical details at the beginning.

Python is often used in Italian technical high schools to introduce the basics of imperative programming: variables, input, output, conditions, loops, functions and first algorithms. It is also the language I use at school to introduce students to computational thinking and programming.

The idea is simple: even a student or an enthusiast who has never programmed before should be able to open the file generated with the help of the AI agent, read the code, and understand at least the general idea of what is happening. This is also because the project description, the rules, and the expected behavior of the program are already explained in the Markdown files (.md) we prepare before development.

In this article we will see a small practical example of agentic programming with AI: we will use ChatGPT to reason about the project and prepare prompts, and Codex CLI to let the agent work directly on the files.

The project will be intentionally simple: a small TCP port scanner in Python.

I will not explain how to install Python, Git, Visual Studio Code or Codex CLI. The guide would become too long and would go off topic.
If you do not have these tools installed yet, you can search the official guides or ask your AI assistant to help you step by step.

This is also part of the learning process: learn how to search, ask precise questions, try, make mistakes, fix them, and try again.

Software Used

For this example, we imagine a normal Windows PC with:

Why Start from Windows

This article is written for Windows users for a very simple reason: in my experience, most students and enthusiasts who want to start programming almost always begin from a Windows computer.

People with no software development experience usually do not already use a Unix-like system such as GNU/Linux. For this reason, the idea is to make the first approach as accessible as possible: turn on the PC, open PowerShell, use Python, Git, ChatGPT and Codex CLI, and start experimenting.

Of course, a great next step is to install Linux, even inside a virtual machine, and start getting familiar with the terminal, filesystem, permissions, packages and command-line tools.

For those who want to take this step, on my YouTube channel there is an old video guide where I explain how to install Debian GNU/Linux on VirtualBox, plus other videos about basic commands.

For those who want to “move to the dark side of the Force”, you can start here:
Install Debian GNU/Linux on VirtualBox: https://youtu.be/YuQfJOKZ36E?si=seahU_agvMy5CjwK

Project Goal

We want to create a small Python program that checks some TCP ports on an authorized host.

Example:

python .\src\portscanner.py --host 127.0.0.1 --ports 22,80,443 --timeout 0.5

Expected output:

Target: 127.0.0.1
Port 22    closed
Port 80    open
Port 443   closed

Project Structure

python-port-scanner/
├── AGENTS.md
├── README.md
├── docs/
│   ├── PROJECT_DESCRIPTION.md
│   ├── SPECIFICATIONS.md
│   ├── SECURITY_RULES.md
│   └── PROMPT.md
└── src/
    └── portscanner.py

Creating the Project from PowerShell

If some commands are not clear, ask ChatGPT ;-)

mkdir python-port-scanner
cd python-port-scanner

git init

mkdir src
mkdir docs

Python environment:

python -m venv .venv
.\.venv\Scripts\Activate.ps1

python -m pip install --upgrade pip

First Git save:

git add .
git commit -m "Create initial project structure"

What Is AGENTS.md?

AGENTS.md is the instruction file that Codex CLI reads before working on the project.

It explains to the agent:

  • what kind of software we are building;
  • which files it should modify;
  • which commands it should use;
  • which technical and security rules it must follow.

In practice, it is a small “internal guide” for the project. It helps Codex avoid improvising and follow our working method.

File AGENTS.md

Copy this into AGENTS.md:

# AGENTS.md

## Context

This project is a small TCP port scanner written in Python.

The project is educational and is used to learn:

- Python programming from the terminal;
- use of the socket module;
- command-line arguments;
- input validation;
- use of Git and GitHub;
- agentic development with ChatGPT and Codex CLI.

Reference operating system: Windows 10/11.

## Goal

Create a program that can be executed from PowerShell:

python .\src\portscanner.py --host 127.0.0.1 --ports 22,80,443 --timeout 0.5

The program must show whether the requested TCP ports are open or closed.

## Security Limits

The software can be used only on:

- localhost;
- your own computers;
- lab virtual machines;
- authorized private networks;
- systems with explicit permission.

Do not implement:

- massive scans;
- subnet scans;
- stealth techniques;
- exploits;
- brute force;
- advanced fingerprinting;
- firewall/IDS evasion;
- offensive modules.

## Technical Requirements

Use the Python standard library.

Recommended modules:

- argparse;
- socket;
- logging;
- sys;
- typing.

## Structure

Main code:

src/portscanner.py

Documentation:

docs/

## Commands

Run the program:

python .\src\portscanner.py --host 127.0.0.1 --ports 22,80,443 --timeout 0.5

Check Git changes:

git status
git diff

## Working Rules

- Do not run Git commits automatically.
- Before changing files, briefly explain what you will do.
- After the change, summarize the modified files.
- Keep the code simple.
- Always validate user input.
- Handle errors and timeouts.
- Do not change the scope of the project.

File PROJECT_DESCRIPTION.md

Copy this into docs/PROJECT_DESCRIPTION.md:

# Project Description

The project consists of creating a small TCP port scanner in Python.

The software must run on Windows through PowerShell.

Learning goals:

- use Python for basic networking tasks;
- understand host, TCP port and timeout;
- use the socket module;
- validate terminal input;
- handle errors;
- use Git and GitHub;
- work with ChatGPT and Codex CLI.

The program is only for educational and authorized use.

File SPECIFICATIONS.md

Copy this into docs/SPECIFICATIONS.md:

# Technical Specifications

## Program

src/portscanner.py

## Arguments

--host

Host or IP address to check.

Examples:

127.0.0.1
localhost
192.168.1.10

--ports

Comma-separated list of TCP ports.

Example:

22,80,443,3306

--timeout

Timeout in seconds.

Default value:

1.0

## Validation

The program must check that:

- host is not empty;
- ports are integers;
- ports are between 1 and 65535;
- duplicates are removed;
- timeout is greater than zero.

## Output

Example:

Target: 127.0.0.1
Port 22 closed
Port 80 open
Port 443 closed

## Errors

If the input is wrong, show a clear message and exit with a non-zero code.

File SECURITY_RULES.md

Copy this into docs/SECURITY_RULES.md:

# Security Rules

This software is educational only.

## Allowed

Use the program on:

- localhost;
- your own PCs;
- virtual machines;
- authorized private networks;
- systems with explicit permission.

## Not Allowed

Do not use the program to:

- scan public IPs owned by others;
- run massive scans;
- search for vulnerabilities without permission;
- bypass protections;
- collect information from systems you do not own.

## Limits

The project must not include:

- subnet scanning;
- aggressive multi-thread scanning;
- stealth scans;
- exploits;
- brute force;
- offensive modules.

File PROMPT.md

Copy this into docs/PROMPT.md:

# Agentic Development Prompt

In this file we save the prompts used with ChatGPT and Codex CLI.

It is useful to:

- remember how the project was developed;
- repeat the workflow;
- improve future prompts;
- document decisions.

First Cycle: Building the Basic Version

Open Codex CLI inside the project folder:

codex

Prompt to paste:

Read AGENTS.md and all files inside the docs/ directory before modifying the project.

Implement the first working version of the educational TCP port scanner.

Requirements:

- implement src/portscanner.py;
- use argparse;
- accept --host, --ports and --timeout;
- parse --ports as a comma-separated list of TCP ports;
- validate integer ports between 1 and 65535;
- remove duplicated ports;
- use socket.create_connection with timeout;
- show whether each port is open or closed;
- handle errors clearly;
- avoid uncontrolled tracebacks;
- do not add offensive functions;
- do not add massive scans;
- do not add subnet scans;
- do not add stealth techniques.

Do not run Git commits.

At the end, summarize modified files and commands to try the program.

Checking Codex CLI Output with ChatGPT

After running Codex CLI, it is useful to do a quick review using the design chat in ChatGPT.

The flow is simple:

  1. in Codex CLI, copy the output using the /copy command;
  2. paste the log into the ChatGPT chat;
  3. ask ChatGPT to analyze what was changed;
  4. check if there are errors, unexpected file changes or useful suggestions;
  5. if the analysis is positive and the project works, save the changes with Git.

In this way, ChatGPT becomes a second control layer: Codex CLI changes the files, while ChatGPT helps us read and evaluate the result before confirming the changes.

IMPORTANT: before running the program, open the generated .py file, read the code and try to understand the general idea of how it works. Only after this check, run the Python file to try it.

python .\src\portscanner.py --host 127.0.0.1 --ports 22,80,443 --timeout 0.5

Check what the agent changed:

git status
git diff

If everything works:

git add .
git commit -m "Implement basic TCP port scanner version"
git tag v0.1.0

Publish on GitHub with GitHub CLI:

gh repo create python-port-scanner --private --source=. --remote=origin --push
git push origin v0.1.0

Or, if the repository already exists:

git remote add origin https://github.com/USERNAME/python-port-scanner.git
git branch -M main
git push -u origin main
git push origin v0.1.0

Second Cycle: Small Improvement

Create a separate branch:

git switch -c improve-cli

Prompt to paste into Codex CLI:

Read AGENTS.md and the docs/ directory before modifying the project.

Improve the port scanner without changing its scope.

You can modify only:

- src/portscanner.py
- README.md
- docs/PROMPT.md, only if needed

Required changes:

- sort ports before scanning;
- remove duplicates;
- improve error messages;
- return exit code 0 if execution is valid;
- return a non-zero exit code for invalid input;
- update README.md with PowerShell examples.

Do not add:

- multi-threading;
- subnet scanning;
- stealth;
- fingerprinting;
- vulnerability detection;
- offensive functions.

Do not run Git commits.

At the end, summarize modified files and commands to try the program.

As before, check the Codex CLI output with ChatGPT, read the code and try it:

python .\src\portscanner.py --host 127.0.0.1 --ports 443,80,80,22 --timeout 0.5

Check changes:

git status
git diff

If everything is correct:

git add .
git commit -m "Improve CLI output and input validation"
git tag v0.2.0

git push -u origin improve-cli
git push origin v0.2.0

Merge into main:

git switch main
git merge improve-cli
git push origin main

If Codex Breaks the Project

If the changes have not been saved yet:

git restore .

If you want to delete the working branch:

git switch main
git branch -D improve-cli

If you already merged and want to undo the last commit:

git revert HEAD
git push origin main

If the project is personal and you want to return to version v0.1.0:

git reset --hard v0.1.0
git push --force-with-lease origin main

Use the last command carefully because it rewrites the remote branch state.

A Note About Tests

In this guide we intentionally leave out automated tests, to keep the first approach simple.

In a real project, tests are very important: they help check that the program still works after changes, improvements or AI agent edits.

For now, we only try the program manually from PowerShell.

The Full Workflow

The method is this:

idea
→ project files
→ AGENTS.md
→ prompt
→ Codex CLI
→ check Codex CLI output with /copy in ChatGPT
→ read and study the generated code
→ manual test
→ git diff
→ commit
→ tag
→ GitHub
→ new cycle

This is a very small project, but the workflow is real.

The important thing is not the port scanner. The important thing is learning how to work with AI agents without losing control of the project.

ChatGPT helps us reason and prepare prompts.
Codex CLI works on files.
Git lets us go back.
GitHub stores the versions.

This is a starting point for programming seriously with AI, even from Windows, even with a very simple project.

Conclusion

Agentic programming does not replace the programmer. It makes the programmer stronger.

It is an accelerator, a concrete help, a way to become more productive and turn an idea into a working project faster. It can also allow a single developer to take back that project left in the drawer because there was not enough time, resources or technical support.

But the AI agent does not work well alone. Someone must guide it, correct it, limit it and verify what it produces. Agentic development requires design, method and orchestration. You must know what to ask, how to ask it, how to check the result and when to stop the agent before it makes the project unnecessarily complex.

For this reason, the real foundations of computer science are still essential:

  • problem analysis skills (computational thinking)
  • algorithms
  • data structures
  • programming
  • software design
  • cybersecurity
  • testing
  • debugging
  • version control
  • documentation

Agentic programming, or “automatic programming” as Salvatore Sanfilippo calls it, is not a shortcut to avoid studying. It is a tool to study better, experiment more and apply immediately what you learn.

My advice, for those who want to go beyond the surface, is to start from solid foundations:

  1. Follow the C course by Salvatore Sanfilippo: https://youtube.com/playlist?list=PLrEMgOSrS_3cFJpM2gdw8EGFyRBZOyAKY&si=OGz5upbMKIGCeRwn
  2. Read K&R — The C Programming Language, a true milestone in software development: https://en.wikipedia.org/wiki/The_C_Programming_Language
  3. Use the AI you prefer as a mentor, tutor and study guide.
  4. Study, try, write code, study again, …

Before, people who wanted to learn something mainly had the Internet, forums, blogs, manuals and a lot of patience. Today, they can also ask a neural network to explain a topic in a simpler way, give examples, suggest exercises, correct an error, compare solutions and support them while studying.

This is a huge advantage, but it must be used in the right way. AI can write code, suggest solutions and speed up the work. But software quality still depends on the quality of the ideas, skills and decisions of the person who designs it.

The real value of agentic programming is this: it helps you focus on the project, the architecture, the technical choices and the realization of your ideas. It lets you study, go deeper and apply things immediately.

Staying on the surface is not enough. You need to go into detail, understand how things work and keep studying.

Only in this way does agentic programming become truly useful: not a way to program without knowing, but a way to build better, learn faster and finally complete your ideas.