What the agent can do

The agent in the chat is not answering from a description of your project. It reads it, searches it, edits it and runs commands in it — using a fixed set of tools that it must ask for by name, and that Semantix executes on your machine.

Knowing that list is most of knowing what the agent is capable of.

The tools#

Reading and searching — these run without asking you.

Tool	What it does
read_file	Reads one file, optionally just a line range
read_files	Reads several files in one call
list_dir	Lists what's directly inside a folder — one level, not recursive
code_search	Fuzzy, relevance-ranked search across the indexed project
code_grep	Exact regex or literal search, with file:line:col and the enclosing symbol
symbols	Finds where a function, class or type is defined
references	Finds everything that calls or imports a symbol
check_errors	Runs your real type-checker — tsc --noEmit, cargo check — and returns the diagnostics

The last five are the index doing work the model would otherwise pay for with tokens. code_grep returning the enclosing function for every match is the part no plain search gives you.

Changing things — these ask first.

Tool	What it does
write_file	Creates or fully replaces one file
write_files	Creates up to two files in one call
edit_file	Find/replace, insert or delete lines inside an existing file
create_dirs	Creates folders
move_path	Moves or renames
copy_path	Copies, recursively
delete	Deletes files or folders
run_command	Runs one shell command in a real terminal

The notebook#

If you turn on Semantic notebook in Settings → Privacy, the agent also gets three memory tools — notebook_write, notebook_search and notebook_recent — that let it keep notes about your project across conversations.

Which lane you're on#

This matters more than anything else on the page, so it gets its own section.

On a custom OpenAI-compatible model, Semantix executes the tools above itself. That's the path the permission gate and the automatic checkpoint live on.

On a Claude Code model — the default — the Claude Agent SDK runs its own tools (Read, Write, Edit, Bash and the rest) plus the Semantix search and notebook tools, and Semantix renders what it did rather than executing it.

Asking permission#

Before the agent runs anything in the second table, the conversation stops and asks. The whole transcript frosts over and an approval card pins itself to the bottom of the panel so you can't scroll past it.

The card shows Permission required, a class badge — WRITE in amber, DELETE in red, SHELL in violet — and the tool name. Below that, one line describing the target: $ npm run build for a command, or the path for a file operation. A move or a copy currently falls through to a compact JSON summary rather than a tidy source → destination line; the information is there, it's just raw.

Three buttons: Once, For session, and Deny.

Once runs it and asks again next time. Deny refuses; the agent is told plainly that you declined and instructed not to retry, so the turn ends cleanly instead of hanging or nagging.

For session is the one to understand properly:

Two more things worth knowing. The card shows paths, never content — approving a write_files means approving the destinations sight-unseen; read the diff afterwards.

The undo point#

The first approved change in a turn triggers an automatic workspace checkpoint, labelled before write_file or similar. That's what the restore control on a message rolls back to — see Conversations and history.

It's best-effort. If taking the checkpoint fails, the tool still runs; you lose the undo point, not the work.

Watching a tool run#

Each call renders as a card in the transcript: an icon, a friendly name, and the filename it's working on — clickable, it opens that file in a tab. The icon pulses amber while the tool is running and stops when it settles. A failure isn't a red pulse; it shows as a red accent along the card's edge.

The card appears before the arguments finish arriving, and fills in as they stream. A file write shows a live progress bar counting lines against the model's own estimate, then resolves into a syntax-highlighted diff. An edit shows +added / -removed before it lands. Deletes, moves and copies resolve into a list of paths, each marked ok or failed.

run_command is a real terminal. While it runs, an xterm session is embedded in the chat showing live output, with a Stop button that kills the child process. You can click into it and type — if a command asks a question, that terminal is where you answer it. Detected URLs are clickable.

Commands run in the background#

run_command can be told to run in the background. It returns immediately, the turn ends, and the job keeps going on its own.

It reports back on whichever comes first: the process exits, or its output goes quiet for 4 seconds. That second condition is what lets a dev server say "I'm up" instead of hanging the conversation forever. The report arrives as a new message in the conversation, carrying the last 8000 characters of output.

MCP servers#

Settings → MCP Servers adds tool servers — remote HTTP/SSE endpoints or local stdio commands. Their tools are offered to every model, namespaced mcp__<server>__<tool>, and the catalogue is re-read on every message you send, so changes apply without a restart.

MCP tools execute on your machine, in Semantix's own MCP host. What reaches the model provider is the tool's name, description, schema, and the arguments a call uses.

If the MCP host doesn't answer within 5 seconds, your message is sent anyway with no MCP tools attached, and nothing tells you it happened.

The limits#

Shell commands allowed	git, node, npm, npx, pnpm, yarn, cargo, rustc, python, python3, pip, pip3, tsc
Pipes, &&, ;, globs	Not supported — each step is a separate call
Working directory	Must stay inside the project
Command timeout	60 seconds default, 600 maximum
Output returned to the model	64KB, then truncated
Terminal scrollback	2000 lines
write_files per call	2 files, stopping at the first failure
read_file default	2000 lines
list_dir	One level, truncated past 500 entries
code_grep / code_search	50 results default (200 max) / 20 (50 max)

Tools need an open project. With no project open the agent is told No active project — open a project before running tools.