🛠️ How to use this module
This is the module where the prototype becomes a product. You don't need to write code: the person writing the TypeScript é o Claude Code. Your role is to understand both places—where the code is stored (GitHub) and where it runs on its own (Trigger.dev) — and knowing how to give the right commands. The “copy and run” blocks are ready to paste into the terminal or the AI chat.
Before the seven topics, get the big picture. The agent runs on your machine—but only while your computer is on. In production, the code lives on GitHub (with history) and runs in Trigger.dev (in the cloud, at the scheduled time), with AI writing and you supervising through the dashboard.
Illustrative diagram — the production cycle: you iterate in Claude Code, the code goes up to GitHub, and from there to Trigger.dev, which runs it reliably in the cloud. The latest files from GitHub are always live.
🐙 GitHub as code storage
What it is
O GitHub it’s code storage in the cloud. Instead of your project living only in a folder on your computer, it lives on a server you can access from anywhere. The practical impact is significant: when it’s time to deploy, the hosting platform pulls the code from the cloud, not on your machine—so your PC can be turned off and the automation will keep running.
What is it?Repository (repo) — your project folder, versioned, in GitHub. Commit — a saved “snapshot” with a description of what changed. Push — the act of sending your commits from your local machine to GitHub.
Each commit saves a point in time. This gives you a complete history: if a change breaks everything, you can revert to an earlier commit and get back to what worked. For automations that handle data or money, this safety net isn’t a luxury—it’s what lets you make changes without fear. Create the repo as private and initialize it with a README.
Why learn
GitHub is a prerequisite for hosting. Deploy platforms (including Trigger.dev) integrate directly with the repo: you push the code and they take care of the rest. Without a repo, there’s no pipeline.
- •Accessible from anywhere: the code isn’t tied to one computer.
- •History for reverting: go back to any earlier commit in seconds.
- •Integrates with deploy: the source of truth that the cloud pulls the code from.
Key concepts
Project folder in the cloud.
Snapshot with description.
Send to the cloud.
Revert when it breaks.
🚫 gh CLI & .gitignore — .env never gets uploaded
What it is
A GitHub CLI (the command gh) is the command-line tool that authenticates you with GitHub and connects the project to the repo — all from the terminal, without opening the website. The .gitignore is a text file that lists what should never be uploaded. And the golden rule for this entire module: the .env (which stores your API keys) never can go to GitHub.
What is it?.env — local file with secrets (API keys, tokens). .gitignore — a list of files/folders that Git ignores and never sends. Claude Code adds the .env when .gitignore automatically — but it's your responsibility to check.
Why learn
A .env leaked is a leaked secret. Repositories are monitored constantly; an exposed key can be used within minutes — and you pay the bill. The .gitignore it’s your first line of defense. Use a professional username (it appears in public links), keep the repo private and don’t be surprised if the terminal asks for command permission several times — that’s the normal approval behavior.
✓ Secret hygiene
- ✓Confirm that the
.envappears in the.gitignore. - ✓Create the repository as private.
- ✓Initialize with a README to open the repo “empty but alive.”
✗ Recipe for a leak
- ✗Push before checking the
.gitignore. - ✗Create the public repo “just to test.”
- ✗Pasting the API key directly into the code (hard-coding).
🎯 Goal: authenticate with GitHub and connect the project to the repo through the terminal.
# 1) instalar a GitHub CLI (escolha o seu gerenciador) brew install gh # macOS (Homebrew) winget install GitHub.cli # Windows (WinGet) # 2) autenticar — responda: GitHub.com / HTTPS / login via web browser gh auth login # o terminal mostra um código de uso único; cole no navegador # 3) no Claude Code, em plan mode, peça (descreva o resultado): > conecte este projeto a um repositório PRIVADO no GitHub chamado <meu-repo>, inicialize com README e garanta que o .env esteja listado no .gitignore antes de qualquer push
✅ How to verify: open the repo on GitHub and check the .gitignore + the README are present — and none .env in the file list.
🎯 Goal: make sure the secret is never uploaded — the .env listed in the .gitignore.
# .gitignore — o que o Git deve IGNORAR .env # ← a regra de ouro: segredos nunca sobem .env.local node_modules/ # dependências (pesadas, reinstaláveis) .trigger/ # artefatos locais do Trigger.dev
✅ How to verify: run git status — o .env no should appear among the files to be committed.
Key concepts
Authenticates via browser.
List what doesn't get pushed.
Standard for automations.
Never put .env in the repo.
⚙️ Trigger.dev — no timeout, retries, traces, alerts
What it is
O Trigger.dev is the cloud execution engine. Think about the difference between a sticky note stuck to the monitor (which you might forget, which disappears when the PC shuts down) and a reliable assistant that runs the task, retries if it fails, and notifies you of the result. Trigger.dev is the assistant. It runs tasks without timeouts, with automatic retries, trace complete for each step and alerts of failure.
What is it?Retry — when a task fails (e.g., the internet goes down), it is retried automatically. Trace — the step-by-step record of what happened during execution. Webhook — an address that triggers the task when an external event occurs.
Illustrative diagram — Trigger.dev closes the “agentic gap”: it provides visibility and reliability precisely when the AI is no longer watching the execution.
Why learn
In production, no one is watching the execution in real time. When the agent runs at 7 a.m. and something goes wrong, you need retries, logs, and alerts—or the error goes unnoticed. Trigger.dev handles this "agentic gap": the bridge between "it ran in my chat" and "it runs on its own and notifies me." It runs TypeScript (not Python)—but that doesn’t change anything for you: Claude Code writes the TypeScript, and your vibe-coding approach stays the same.
🎯 Practical tip
Don't be intimidated by “it's TypeScript.” You never type TypeScript by hand: you describe the result in Portuguese, and Claude Code writes the code. Trigger.dev is AI-friendly via a official MCP server, so AI manages tasks, views runs, and adjusts everything by talking with you.
Key concepts
Long-running tasks run.
Try again; record everything.
AI writes for you.
Keep testing and production separate.
🔌 Initialize project + Trigger.dev MCP
What it is
Initializing the project is the sequence that connects your code to Trigger.dev. You sign up with the GitHub account, create an organization and a project (use the same name as the repo, so you don’t get lost), copy the Project ID and install the Official MCP from Trigger.dev in Claude Code. Then, two commands: the init creates the structure, and the dev starts the local worker that listens on your machine.
What is it?Project ID — your project’s unique identifier in Trigger.dev (in Project Settings > General). MCP — the protocol that gives AI tools; here, Trigger.dev’s MCP lets Claude Code manage tasks and runs. Local worker — the process that runs tasks on your machine during development.
⚠️ The most common error
After installing any MCP, restart Claude Code. If you don’t restart, the AI won’t see the new tools, and it may seem like "MCP isn’t working." Restarting fixes the vast majority of cases.
Why learn
With the MCP installed, you manage the project talking — “create a task that does X,” “show the latest run”—without memorizing commands. Without MCP, you end up in the terminal and lose the vibe-coding flow. Always open the project folder in VS Code, so Claude Code can read and edit the files while you talk. The init é interactive and sometimes needs to be run directly in the terminal.
🎯 Goal: initialize Trigger.dev in the project and start the local worker.
# 1) cria trigger.config.ts + a pasta de tasks (interativo: # cole o Project ID quando pedir <seu-project-id>) npx trigger.dev@latest init # 2) sobe o worker local — deixe rodando enquanto desenvolve npx trigger.dev@latest dev # (depois de instalar o MCP do Trigger.dev: REINICIE o Claude Code)
✅ How to verify: open the Trigger.dev dashboard in the dev — your task should appear in the list as soon as the worker connects.
🎯 Goal: in Claude Code (plan mode), prepare the project folder and connect everything.
> crie uma pasta de projeto, conecte ao repo <meu-repo> no GitHub e prepare para Trigger.dev (gerenciador npm). Use o Project ID <seu-project-id>, rode o init e confirme que o .env está no .gitignore. Antes de executar, me mostre o plano.
✅ How to verify: the local folder stays in sync with the repo, the trigger.config.ts exists, and Claude Code can list its tasks through MCP.
Key concepts
In Settings > General.
Creates structure, starts a worker.
After installing any MCP.
Open the folder for AI to manage.
⏰ Cron (5 fields)
What it is
O cron is the automation “alarm clock”: a pattern of five fields that defines when the task runs. The fields are, in order: minute, hour, day-of-month, month e day-of-week. The classic example is 0 7 * * * = minute 0, hour 7, every day — in other words, every day at 7 a.m.. The asterisk * means "any value".
What is it?Cron — standard scheduling syntax, used on servers for decades. * = any; */5 = "every 5". Some node settings only accept specific modes: asking for "every 5 minutes" may turn into the cron */5 * * * * behind the scenes.
Illustrative diagram — read the cron from left to right: minute, hour, day of the month, month, day of the week. The first two fields set the time; the three asterisks mean “any day.”
Why learn
Cron is what makes the automation run without you present — the shift from “show up and trigger it manually” to “run on its own at the right time.” Knowing how to read the five fields gives you control: you can check whether the agent will actually run when it should, instead of just hoping.
🎯 Goal: read and vary the 5-field cron pattern.
# ordem dos campos: minuto hora dia-do-mês mês dia-da-semana 0 7 * * * # todo dia às 7h da manhã (o clássico) */5 * * * * # a cada 5 minutos 0 */2 * * * # a cada 2 horas, no minuto 0 30 8 * * 1 # toda segunda-feira às 8h30 0 <hora> * * * # todo dia na <hora> que você escolher (0–23)
✅ How to verify: ask Claude Code "explain in English what this cron does" and check that it matches your intent before scheduling it.
Key concepts
min · hour · day · month · week.
Every day at 7 a.m.
No field restrictions.
Regular interval.
📊 Dashboard anatomy
What it is
The Trigger.dev dashboard is your window for production. There you’ll see: the task overview, the list of Runs (each run), the traces for each run (each row = one step), the timeline, the dashboards for payload (what went in), and output (what came out), and the Schedules, Queues e Alerts. All of this across two environments: dev (test) and prod (actually live).
What is it?Run — one individual execution of the task. Payload — the input data for that run. Output — the result produced. Trace — the step-by-step record, useful for finding out where failed.
From testing to production (timeline)
1. dev — you test
The local worker connects; you trigger the task manually and read the traces until it’s solid.
2. deploy — deploy to prod
The code goes from GitHub to Trigger.dev; the prod environment starts running for real.
3. schedule fires — runs appear
At the cron schedule time, new runs appear in the list; each with its own payload and output.
4. you supervise — traces & alerts
If something fails, you get an alert and the trace shows which step caused it. The dashboard is your observation post.
Why learn
In production, Claude Code is no longer watching the execution—the dashboard is where you see what happened. Knowing how to read runs and traces turns “I think it ran” into “I know exactly what ran and where it got stuck.” Since the model is interpretive, the output can vary from one run to another: check the result (did it achieve the goal?), not the exact wording.
🎯 Practical tip
Always test in dev before releasing to prod. And remember Trilha 1’s “trust but verify”: green ≠ correct. A run can finish "green" (without errors) and still have produced the wrong output—read the output, not just the status.
Key concepts
Each listed execution.
Row = one step.
What went in and came out.
Test, then release.
🎬 Deploy from the first prompt
What it is
The final discipline: build with deployment in mind from the first prompt — the “one initial prompt to rule them all.” In production, the AI isn’t there to fix things on the spot, so what you no what you asked for in the prompt doesn’t come free. That’s why every build meant to run on its own needs four new requirements in the way you make requests.
What is it?Repository Secret — a secret stored on GitHub itself (in Settings > Secrets and Variables > Actions) that the deploy uses without exposing the key. The TRIGGER_ACCESS_TOKEN is what authorizes GitHub to publish to Trigger.dev.
The 4 requirements for unattended builds
✓ Include in the prompt
- ✓Fixed inputs: the task receives predictable data and doesn't improvise where it comes from.
- ✓Structured output: predictable format (defined fields), easy to consume.
- ✓Error handling: what to do when something fails, built in from the start.
- ✓Log at every step: so the trace can tell the story later.
✗ Don’t leave it for later
- ✗"I'll add error handling later" — in production, "later" is too late.
- ✗Loose, free-form output that changes shape with every run.
- ✗Zero log — the trace goes silent and you don't know what happened.
- ✗Wait for the schedule to test—trigger it manually first.
Why learn
The complete pipeline ties together everything you’ve seen: you iterate in Claude Code → it does push to GitHub → o GitHub deploys to Trigger.dev. This way, the latest files are always live, with no manual steps. Add the TRIGGER_ACCESS_TOKEN as a Repository Secret on GitHub so the automatic deploy works — and, after publishing, trigger the task manually to test, instead of waiting for the next cron window.
🎯 Practical tip
On GitHub, go to Settings > Secrets and Variables > Actions and register the TRIGGER_ACCESS_TOKEN how Repository Secret. That’s what lets a push turn into a deploy without you pasting the token anywhere in the code.
Key concepts
Think about production from the start in the prompt.
Input, output, error, log.
GitHub publishes to Trigger.dev.
Test without waiting for cron.
Setting the cron: which expression means "every day at 7 a.m."?
📌 Module Summary
gh auth login; the golden rule is .env never upload.init e dev.0 7 * * * = every day at 7 a.m.Next Module:
6.2 — Secrets & Security