Install and troubleshoot | INEMA Agent Runtime

Check what you need to have

The list is short. The kit’s README asks for three things: Node 18 or later, o Claude Code and/or Codex logged in with their subscriptions, and a computer with Linux or Mac. On Windows, use WSL.

Either agent is enough to get started. With both, you can use all the recipes, including R1, where Claude asks Codex for help.

🆕 New here? Four terms from this module

Terminal — the text window where you type commands and press Enter. On Mac, the app is called Terminal; on Linux, too.
Node — the program that runs the kit’s scripts (the files .mjs). It also includes the npm, which installs tools.
WSL — Linux running inside Windows. It's how Windows users follow this course.
Login through your subscription — sign in to Claude Code or Codex with the same account as your monthly plan. No API key.

✓ You need to

✓ Node 18 or newer
✓ Claude Code or Codex (or both), signed in
✓ Linux, Mac, or Windows with WSL
✓ A folder where the kit will live

✗ You don’t need to

✗ Paid API key
✗ Server, cloud, or web dashboard
✗ Knowing how to code
✗ Ollama (optional: free local models)

⌨️

Terminal

where everything happens

🟩

Node 18+

run the scripts

🐧

WSL

Linux on Windows

💳

Subscription

Clone the kit on your machine

The kit lives on GitHub. One command copies everything to a new folder on your computer. The name meu-projeto is a suggestion from the README: replace it with the name of your work, if you want.

The cloned folder becomes your project. The rules, bridges, and recipes are already in the right place. You don’t install anything beyond that.

🆕 New here? Git, repository, and clone

Git is the program that keeps a history of changes to a folder. Repository it’s this folder with its history, published on a site like GitHub. Clone it’s downloading a complete copy of it to your computer, ready to use and edit.

🎯 Objective: have the kit in a folder of your own

In the terminal, in the folder where you keep your projects (run the two lines, one at a time):

git clone https://github.com/inematds/inema-agent-runtime meu-projeto
cd meu-projeto

How to verify: open the folder meu-projeto in the file manager. The folder must contain the folder runtime/ and the files README.md, AGENTS.md e CLAUDE.md.

How to read the diagram: the gray box is the public copy, which you don't change. The green box is your copy: everything the course asks you to edit goes in it. The cd of the command is the step for "entering" that box.

💡 Every course command runs from here

The recipe paths start in runtime/…. They only work if the terminal is inside the kit folder. Opened a new terminal? Go into it again with cd meu-projeto.

🗂️

Git

folder history

☁️

Repository

the published folder

📥

Clone

full copy

📁

meu-projeto

the kit folder

Run the diagnostic

O doctor.mjs é o diagnosis from the kit. It checks four programs (Node, Claude Code, Codex, and Ollama) and ends with one word: READY or MISSING.

It only asks for each program’s version and whether Codex is logged in. It doesn’t call any models, so doesn’t use quota. You can run it as many times as you want.

🎯 Objective: find out what’s installed and logged in

In the terminal, from inside the kit folder:

node runtime/scripts/doctor.mjs

Real output (10/05/2026, Linux):

node    ok        24.13.0
claude  ok        2.1.289   login: abra `claude` uma vez; R2 usa ele
codex   ok        0.159.2   Logged in using ChatGPT
ollama  ok        0.33.2    opcional: modelos locais grátis

PRONTO: siga para runtime/receitas/R1-claude-usa-codex.md

How to verify: the last line starts with PRONTO. If you see FALTA, see topic 4. The versions on your machine may differ; what matters is the second column.

How to read the diagram: the blue boxes determine the result; the dashed gray box (Ollama) only provides information. Just one agent is enough to mark it READY: Claude Code alone is enough, and Codex alone works too.

🆕 New here? "Exit 0" and "exit 1"

Every command returns a number to the system when it finishes. Output 0 means "it worked"; any other number means "something is missing." You don't see this number on the screen, but the kit's agents and scripts read it. That's how the agent knows, without guessing, whether the diagnosis passed.

🩺

Diagnosis

check without spending

0️⃣

Output 0

worked

✅

READY

go to R1

⛔

MISSING

install what's missing

Read each line of the doctor

Each line has four columns: the program, the state, the version and a note. When something is missing, the note already includes the command that fixes it. You don’t have to guess.

The table below brings together all the states that the doctor.mjs can show and what to do in each one.

Line	State	That means	What to do
node	`velho`	version below 18	update Node (the note says "needs 18+")
claude	`ausente`	Claude Code not installed	`npm i -g @anthropic-ai/claude-code`
codex	`ausente`	Codex not installed	`npm i -g @openai/codex`
codex	`sem login`	installed, but without an account	`codex login`
ollama	`ausente`	without local models	nothing: it’s optional and doesn’t change the READY status
any	`ok`	installed (and, in Codex, logged in)	go ahead

What to look for in the table: only the Codex line checks the login. The Claude one checks the installation and reminds you, in the note, to open the claude once to sign in to the account.

Read the last line

READY: skip to topic 5. MISSING: continue at step 2.

Find the line that isn't "ok"

Copy the command from the note on this line and run it in the terminal.

Run doctor again

Repeat until the last line says READY. Since it doesn’t use up any quota, repeating is free.

💡 Even the doctor has made a mistake, and it became a record

The first line of the runtime/FALHAS.md from the kit tells a real story: the doctor said "Codex without login" while Codex was logged in. The cause: Codex reports login status through a channel the script wasn't reading. The smallest fix was to read both channels. One line, no drama. You'll do the same in module 4.2.

✅

everything is in order

📦

missing

install with npm

🔑

without logging in

codex login

🕰️

old

Node older than 18

See how both agents read the same rules

When opened, each agent looks for an instruction file with a different name. Codex reads AGENTS.md. Claude Code reads the CLAUDE.md.

The kit writes the rules just once, in the AGENTS.md. O CLAUDE.md starts with @AGENTS.md, which tells Claude to include that file. Result: one rule, two readers.

How to read the diagram: the two blue arrows lead to the same green box. A rule changed in the AGENTS.md? Both agents will follow them in the next session. The settings.json is set aside because it's specific to Claude Code.

📄 The entire CLAUDE.md (actual kit content)

@AGENTS.md

## Self-learning

When the human corrects you, or you notice a mistake you made: propose the lesson as a row in the “Learning” table in `runtime/POLITICA.md`. Once approved, it goes into `## Lessons` in `AGENTS.md`.

Notice: the first line pulls the AGENTS.md. The rest is the rule of learning without changing the rules themselves, which you'll see in module 4.2.

✓ AGENTS.md directs the agent

✓ Read the POLITICA.md before acting
✓ Use only systems listed in the CAPACIDADES.md
✓ Use the smallest model that gets the job done (ROTEAMENTO.md)
✓ Climb the ladder of options before saying “impossible”

✗ settings.json blocks it in Claude Code

✗ rm -rf
✗ git push --force e git push -f
✗ git reset --hard
✗ MCP server outside the list (only ponte-modelo is enabled)

💡 The guard is already enabled

The same .claude/settings.json turn on the kit’s guard: before editing a file another session changed, or deleting files, Claude Code asks. You don’t need to configure anything now. The details are in module 4.3.

📘

AGENTS.md

rules for both

📗

CLAUDE.md

points to AGENTS

🔗

@AGENTS.md

include the other file

⚙️

settings.json

blocks and guard

Make your first request to the agent

With READY on screen, open the agent inside the kit folder: type claude (or codex) and press Enter. It opens a conversation right in the terminal.

The first request is what the README suggests: the agent reads the kit’s rules before doing anything and starts mapping your tools with you.

🆕 New here? Interactive session and trusted folder

Interactive session it’s the conversation that opens when you type claude: you type, it responds and acts, until you exit. Trusted folder it’s the folder you authorized Claude Code to use. The first time, it asks whether you trust the folder: choose “Yes, I trust this folder.” Read the selected option before pressing Enter; the kit’s CHANGELOG 0.2.0 records that, for background sessions (claude --bg), this warning opens with “No, exit” selected.

🎯 Objective: have the agent read the kit rules and start the map with you

Open claude in the kit folder and paste:

Read runtime/LEIA-ME.md and help me fill out CAPACIDADES.md for my work.

How to verify: the agent shows that it opened the runtime/LEIA-ME.md and starts asking about the systems you use at work. If it starts writing in the CAPACIDADES.md without asking anything, stop and ask to go system by system (module 1.4).

He reads the rules

O CLAUDE.md (and through it the AGENTS.md) is added automatically. The request adds the LEIA-ME.md, with the cycle and the ladder.

You report your work

Clara would talk about the appointment spreadsheet. Sônia, about the ERP that only exports CSV. Describe your systems in your own words.

Don't accept anything yet

For now, it’s a conversation. In modules 1.3 and 1.4, you’ll learn what a good map line needs before you approve it.

⚠️ Always open in the kit folder

Open in another folder, the agent can't find the CLAUDE.md, o AGENTS.md nor the .claude/settings.json. It works, but without the kit's rules and safeguards. Before typing claude, check that the terminal is inside meu-projeto.

Quick test (optional): the doctor finished with FALTA. What's the next step?

💬

Session

terminal conversation

🔓

Trusted folder

"Yes, I trust"

📖

README

read before acting

🗺️

CAPACIDADES

the map starts

🎓 Module summary

✓

Three requirements — Node 18+, one logged-in agent, Linux/Mac or WSL.

✓

A clone becomes the project — everything runs from inside the folder.

✓

The doctor doesn't use any quota — ends with READY or MISSING.

✓

Each line includes the fix — run the note and repeat the doctor.

✓

One rule, two agents — CLAUDE.md pulls in AGENTS.md.

Next module:

1.3 — The ladder of options

← Back to the track Module 1.3 →