pt-freelancer-ops

Your AI agent runs your freelancer admin in Portugal. You press submit and you pay.

A freelancer in Portugal files with Finanças, Segurança Social and AIMA. The deadlines look alike, and some of them move. The Q2 recapitulativa is due on 20 July, but the Q2 IVA return is due in September.

pt-freelancer-ops gives your AI agent the calendar, the rules and the click paths for each portal. A routine fires about a week before each deadline. Your agent builds the figures from your recibos verdes, checks them and tells you what to press. It saves the proof in one folder.

This is not tax or legal advice. It is a working notebook for an operator. Rules change with every Orçamento do Estado. Each playbook has a last verified date. Each fact has a tag: (official source), (verified in practice) or (unverified). Check the portal before you rely on a number.

AI agents: read AGENTS.md. It holds the operating rules.

See it run

Before and after

A plain AI chat agrees that férias fiscais move every deadline to September. With this repo, your agent catches the 20 July deadline, says that the filing is late, and names the file that sets the rule.

How it works

The agent prepares and checks. You press Entregar and you pay.

What you get

Your agent answers in a status table like this one. This example uses invented data.

You also get:

• a draft for each filing, marked DRAFT, with each amount taken from a document
• the click path for the portal, with the traps on the way
• a calendar file (.ics) with each reminder, as a second layer if your scheduler stops
• the proof for each filing, saved under records/<year>/ with a fixed name

Built for

It covers recibos verdes, IVA, Segurança Social, IRS, certidões and residency paperwork.

Lived and tested: a trabalhador independente on regime simplificado, IVA regime normal trimestral, who bills EU business clients (reverse charge and recapitulativa).

Researched, not lived. Check the confidence tags for:

• the IVA-exempt (art. 53.º) setup
• Portuguese clients with retenção na fonte, and non-EU clients
• life events: a salaried job and freelance work at the same time, married or unido de facto filing, leaving Portugal
• foreign accounts and investments, crypto, and Portuguese property

Not covered: contabilidade organizada bookkeeping, companies (Lda or Unipessoal), and staff that you hire.

Install

Setup takes about 15 minutes.

git clone https://github.com/4arkin/pt-freelancer-ops.git ~/pt-freelancer-ops
cd ~/pt-freelancer-ops
cp profile.example.md profile.md        # fill it in with your agent, or by hand
scripts/init-records.sh 2026            # creates records/2026/
python3 scripts/make-ics.py             # calendar file with each reminder (name routines to include only those)

Open the folder in your agent and send:

Read AGENTS.md and help me fill in profile.md.

Claude Code reads CLAUDE.md, Gemini CLI reads GEMINI.md, and Codex reads AGENTS.md. All three files point to the same instructions. To schedule the routines with cron, a desktop agent app or a calendar, read routines/README.md.

Works with

The tests used Claude Code. Codex and Gemini CLI read the same AGENTS.md, but nobody tested them yet. Reports are welcome.

Cloud schedules cannot see your local profile.md and records/. Run the routines on your own machine.

FAQ

Does the agent file or pay for me?
No. It prepares and checks each filing, then tells you what to press. AGENTS.md forbids it to submit, pay or send anything for you.

Does it need my passwords?
No. You log in to each portal yourself, with Chave Móvel Digital or your password. The agent never stores or asks for a password, a PIN or a 2FA code.

Where does my data go?
Your data is in profile.md and records/. Git ignores both, so they stay on your machine. A chat app sees only the files that you upload.

I am IVA-exempt under art. 53.º. Does it work for me?
Yes. Each routine checks your profile.md and skips what does not apply. A monthly routine watches your turnover against the €15,000 and €18,750 limits. This path comes from research, not from use.

What happens when a rule changes?
Each playbook has a last verified date, and MAINTAINING.md holds the January update checklist. When your agent finds a change, it tells you and offers to update the right file.

Inside

Contributing

Did a portal flow change? Did you find a trap that is not on the list, or a rule that is wrong? Open a pull request. The format is in CONTRIBUTING.md. Each fix teaches the next freelancer's agent.

License

MIT. See LICENSE.