Working with agents, step by step

1. Before you start

• A coding agent that reads AGENTS.md or CLAUDE.md: Claude Code, Codex, and others.
• idetea on your PATH (the installer does it). Agents use the idetea commands when they find them, and fall back to writing the files themselves.
• A project open in IDE TEA.

2. Teach the project's agents

1. Open the command palette (Ctrl+Shift+P).
2. Run Interfaces: teach this project's agents.
3. The IDE writes a short block of instructions into the AGENTS.md and CLAUDE.md you already have, leaving the rest of each file alone. With neither, it creates an AGENTS.md and a CLAUDE.md that imports it. Commit them with the project, or keep them to yourself: your choice.

3. Run your agent inside the IDE

Open the terminal (Ctrl+Shift+T) and start your agent there, as you would anywhere else:

claude        # or codex, or your agent of choice

Ask for what you want as usual. When the agent needs a decision, it uses the panel instead of the chat. You can also say it outright: "ask me in the IDE panel".

4. Answer a question

When the agent asks something, the Interfaces panel opens with a real form, and the status bar says a new question arrived.

1. Fill in the form: choices, checkboxes, text fields. A button that needs something first says what is missing.
2. Optional: write a comment for the agent (a caveat, a question back). It goes with the button you click.
3. Click a button. The answer goes back to the agent, which carries on.

Every question and your answer are kept. Open Interfaces history (palette, or the History link at the top of the panel) to see the open questions first and the answered ones by day, with search. An entry opens read-only, as you answered it, with when the agent read it.

Agents can also show you images, galleries to pick from, animated sprites, sounds with their waveform, files to edit (a commit message, a PR description), and step lists for a manual test, with an approve button that waits until you have done the steps. Select text, at the top of an interface, lets you copy its text.

5. Approve a terminal

To run something you should be able to watch (tests, a dev server, another agent), the agent asks the IDE for a terminal. A Terminal request tab shows exactly what would run, and where.

1. Read the command. It runs exactly that, with your permissions, as if you typed it.
2. Click Allow and run, or Refuse. The agent learns which one you chose.
3. The command runs in its own tab. When it ends, the tab keeps the output and the exit code until you press Enter; the agent gets the code (and, if the command wrote one, an answer file).

Closing the tab before the end stops the command, and the agent is told.

6. Skip the question for commands you trust

Put them in your config, ~/.config/idetea/config.toml:

[agents]
allow = ["npm run dev", "cargo test", "claude *"]

An entry is the exact command, or a start followed by *: that start plus plain arguments, with no ; & | $, backticks or redirections.

7. Hand work to a helper agent

Your agent can start another one, for a review or a fix on the side, in its own git worktree, so the two never edit the same files:

idetea run --title "Reviewer" --worktree agent/review -- \
  claude -p 'Review the last commit. Write your findings to the file in $IDETEA_ANSWER.'

1. You approve the request, as in step 5. The tab shows the branch it will use.
2. The IDE creates .idetea/worktrees/<name> on that branch and runs the helper there.
3. The helper writes its answer to $IDETEA_ANSWER; your main agent reads it and brings code in from the branch the usual way (with your test and approval).
4. When it is done, the worktree is removed if it has nothing uncommitted. The branch always stays.

8. The idetea commands

Agents use these when idetea is on the PATH. Each does the whole round trip in one call. You can try them yourself in the IDE terminal.

Run any of them alone to see all the options.

9. Start a new project with an agent

Project: new… in the palette (or idetea new) creates the folder, runs git init, installs the agent skills of a template (empty, Rust, website, Python, FastAPI), writes an initial request into AGENTS.md, and can open your agent in an IDE terminal for you to approve:

idetea new my-app --modelo rust --descricao "a unit converter" --agente claude

10. Under the hood

Everything is plain files in the project's .idetea/ folder. These ones stay out of git:

• .idetea/ui/<name>.json: a question; your answer lands in .idetea/ui/responses/.
• .idetea/agents/<name>.json: a terminal request; its progress in <name>.status.json.
• .idetea/state.json: what you have open, for idetea status.
• .idetea/history/: every question and answer, until you clear it.

So any agent that can read and write files can use it, and you can read every message yourself. The full formats (in Portuguese for now): the Interfaces format and agent terminals.