Understand the official version of parallel sessions
In videos about mods, several Claude sessions worked together, with a panel showing who was active and who had stalled. It was reverse-engineered and broke with every update.
Today, Claude Code itself does this through the official method: claude --bg release a session that works on its own, without tying up your terminal. Under the hood, Claude lists these sessions with claude agents. The kit wraps reading this list in a short script, the observar.mjs.
🆕 New here? Three words from this module
- Session — a Claude Code conversation with its own memory. Each time you open
claude, a session starts. - Second plan — the session runs without a screen in front of you. You let it run, return to the terminal, and check later, like leaving the washing machine running.
- id — the short code, such as
d6816239, which identifies the session. You use the ID to read, join, or stop it.
How to read the diagram: the purple arrows are the commands you give. The blue boxes are the sessions working independently, side by side. The observar.mjs only looks: it neither stops nor changes any session.
✓ Official method (R4)
- ✓ Documented command:
claude --bg - ✓ Each session has its own name, model, and mode
- ✓ Follows the same POLICY as the kit
- ✓ Keeps working when Claude updates
✗ The “Threads” of videos
- ✗ Improvised wire inside the app
- ✗ Disappears in the next update
- ✗ No one guarantees what it can do
- ✗ Only the person who built it knows how to fix it
release the session
the role of each one
one place
each session uses
Mark the folder as trusted
A background session works without you watching. That's why Claude only lets you launch one in a folder you've already said you trust. It's a one-time step for each folder.
Without this step, the --bg responds Workspace not trusted and does nothing. The R4 recipe starts right here.
Open Claude in the kit folder
In the terminal, from inside the folder, type claude. The first time you open a new folder, a trust notice appears.
Notice the option that's already selected
The notice opens with "No, exit" marked. If you press Enter right away, Claude closes and the folder remains untrusted.
Change to "Yes, I trust this folder"
Change the selection to "Yes, I trust this folder" and press Enter. Done: the folder is marked.
Exit and return to the terminal
You can close the session. The marker is saved, and background sessions can now start in this folder.
In the terminal, from inside the kit folder:
claude
In the notice that appears:
"No, exit" ← vem selecionado: NÃO aperte Enter aqui "Yes, I trust this folder" ← escolha esta
⚠️ Trust only folders you know
Trusting a folder lets Claude read the instructions and mods in it. Mark the kit folder and your work folders as trusted. For a folder downloaded from a third party, read it first (module 4.3 covers this).
by folder
is marked
the right choice
the error if you forget
Let background sessions go
Recipe R4 starts two sessions. One reviewer that only reads and answers a question about the POLICY. And one executor, in a lighter model that creates a file.
Each line returns control to the terminal immediately. Both sessions keep working on their own, at the same time.
In the terminal, from inside the kit folder (already marked as trusted), one line at a time:
claude --bg --permission-mode plan --name revisor "Read runtime/POLITICA.md and reply in one line with the 'Send' limit." claude --bg --model sonnet --name executor "Create resumo.md with 3 lines about what this kit is."
Result confirmed in CHANGELOG 0.2.0:
sessão listada como background … done; respondeu "N2" lendo a POLITICA
background. The reviewer’s correct answer is N2, which is the cap for “Send” in the POLITICA table.| Command fragment | What it does | Why here |
|---|---|---|
--bg | release the session in the background | the terminal is free right away |
--permission-mode plan | the session only reads and plans; it doesn't change anything | the reviewer doesn't need to edit files |
--model sonnet | chooses a lighter model | three summary lines don’t require the top level |
--name | names the session | is the name shown in the Observe table |
What to look for in the table: the mode and model follow the rules of the ROTEAMENTO.md and of the POLITICA.md what you saw in module 3.1. The one that only reads runs in plan mode. The one that does a little runs the smallest model that gets the job done.
⛔ Don't combine them -p with --bg
O -p (which you used in R2) responds and exits. The --bg release it and leave it running. Claude refuses to do both together, with the message --bg and --print conflict. This was learned in the test of kit version 0.2.0.
plan mode
sonnet, creates a file
the right answer
conflicts with --bg
Monitor with observar
O runtime/scripts/observar.mjs shows a table of the background sessions in this folder. It only reads the list Claude returns in claude agents --json. It doesn't stop or change any session.
Run it as many times as you like: it doesn’t call a model or use up any quota.
In the terminal, from inside the kit folder:
node runtime/scripts/observar.mjs
Real output (10/05/2026, Linux). In the kit test, the session was called r4-revisor; with --name revisor, yours appears as revisor:
id tipo nome estado iniciada há d6816239 background r4-revisor done 7 min ver saída: claude logs <id> · entrar: claude attach <id> · parar: claude stop <id>
tipo = background and the name you gave it. To see sessions from all folders, run node runtime/scripts/observar.mjs --todas.How to read the diagram: the good path goes from left to right until done. The red dashed lines show the detours: a session may get stuck waiting for permission (blocked) or fail (failed). In both cases, it’s up to you.
💡 Why "blocked" happens
Each session follows POLITICA. If the executor needs something with an N2 limit, such as a command that changes the system, it stops and asks. In the background, no one sees the request right away: that’s why observe exists.
doesn’t stop anything
short code
5 values
all folders
Enter, read, and stop a session
The footer of observar itself lists the three commands. They all use id from the first column of the table, for example d6816239.
Reading is always safe. Logging in helps unblock a session blocked. Stopping is the way out when it uses quota without getting anywhere.
| Command | Does | Use when |
|---|---|---|
claude logs <id> | shows the session screen | see the response from a done or the error from a failed |
claude attach <id> | joins the session to chat | respond to a request from a blocked |
claude stop <id> | for the session | session going in circles or wrong request |
What to look for in the table: switch <id> using the code shown by observar. Without the less-than and greater-than signs.
In the terminal, replacing <id> using the reviewer ID in the observar table:
claude logs <id>
Result confirmed in CHANGELOG 0.2.0:
o revisor respondeu "N2" lendo a POLITICA
runtime/POLITICA.md: the "Send" line says N2.✓ Stop without hesitation when
- ✓ The request went wrong and you want to redo it
- ✓ The session repeats the same attempt
- ✓ It continues
workingfar beyond expectations - ✓ You started too many sessions at once
✗ Don’t do it
- ✗ Approve everything when entering a
blockedwithout reading the request - ✗ Leave
failedwithout opening the log - ✗ Stop a session from another project through the option
--todas - ✗ Launch the same task again without stopping the previous one
💡 Prefer buttons?
The kit includes an optional mod, the runtime-painel. Inside Claude Code, the command /painel shows the same sessions with buttons Update e Stop. Only your click for a session. You'll set this up in module 4.3.
read the screen
join and chat
stop the session
the version with buttons
Combine the results without exceeding the quota
Each session writes the result to a file, such as resumo.md of the executor. At the end, a "chief" session (or the R2 team) reads these files and consolidates them into a single response.
The safeguard is the quota: each session uses quota from your subscription. R4 itself warns you: start with R2, which runs in a single session, and launch parallel sessions when the time savings make it worthwhile.
Open claude in the kit folder and paste:
Use o time (planejador, executor, revisor) para ler resumo.md, conferir se ele tem 3 linhas sobre o que é este kit e me dizer APROVADO ou o que falta. Não altere outros arquivos.
APROVADO or with FALTA: and the list of things to fix, which is the reviewer's format in .claude/agents/revisor.md.| Situation | Use | Why |
|---|---|---|
| Clara wants the week’s available times checked | R2, one session | short task: the team fits in one conversation |
| Sônia closes out the month for several clients, each with their own CSV | R4, one session per client | independent parts that work together |
| One question about the POLICY only | one session on the smallest model | the team there just uses up quota |
What to look for in the table: it’s rule 2 of the ROTEAMENTO.md in practice. Use an agent team only when the work is worth more than the cost of assembling the team.
💡 Two sessions, one file: be careful
If two sessions edit the same file, one can undo the other's changes. Give each session its own output file. The kit's collision guard asks before that damage happens (module 4.3).
Quick test (optional): you ran claude --bg and received Workspace not trusted. What should you do?
by session
consolidate at the end
just one session
the guard asks
🎓 Module summary
Next module:
3.4 — Long-running agent with verification