How agents work in stagewise - Docs - stagewise: The Agentic IDE for Open-Source Models

An AI coding agent in stagewise is a model-powered assistant that reads, reasons about, and modifies your codebase through a structured loop. It’s not autocomplete — it’s an agent that thinks, acts, observes, and repeats until your task is done.

The agent loop

Each message goes through a cycle of reasoning and action: The loop continues until the agent completes your request or needs your input. Say you type: “Add input validation to the signup form.”

Receive context — The agent reads your message along with WORKSPACE.md, open files, any @mentions, and DOM context you’ve attached
Reason — The model identifies the signup form component, checks what validation patterns the project uses, and plans what to change
Act — The agent uses tools: reads the form component file, searches for existing validation patterns, edits the file with the new logic
Observe — Tool results (the file contents, search matches, edit confirmation) are fed back to the agent
Repeat or respond — If more changes are needed (e.g., adding error messages, updating styles), the agent loops again. Otherwise, it responds: “Added input validation to the signup form. The form now checks…”

Tools the agent can use

Agents have direct filesystem access through a set of built-in tools:

Tool	What it does
File reading	Read any file in connected workspaces
File editing	Create, modify, or delete files with tracked changes
Code search	Search across your codebase with glob patterns and regex
Shell access	Run shell commands, scripts, and package managers
Browser access	Inspect pages, take screenshots, and interact with web content

How the agent understands your project

The agent builds understanding from several sources before reasoning:

WORKSPACE.md — Auto-generated project analysis in .stagewise/ that maps your codebase structure, dependencies, and architecture
Skills — Custom SKILL.md files you create to teach the agent project-specific patterns and constraints
AGENTS.md — Optional project instruction file (disabled by default)
@mentions — Files and tabs you explicitly reference in your message
DOM context — Web elements you select from the browser viewport

All of these feed into a single reasoning pass. Learn how context assembly works →

Multiple agents

stagewise supports multiple agent instances running in parallel. Each agent has its own chat session and can use a different model. Switch between agents with Ctrl+Tab. Typical multi-agent setups:

One agent on frontend changes, another on backend logic
A fast model for simple refactors, a powerful model for complex architecture work
Separate chats for separate tasks — keeps each conversation focused

What agents can’t do

Agents operate within the boundaries of your workspace access and tool permissions:

Cannot access files outside your connected workspaces
Cannot install system-level software without your explicit shell confirmation
Cannot browse to external URLs without your direction
Every file edit is tracked and reviewable — nothing happens silently

What’s next

Workspaces

Learn how to connect multiple folders and let agents work across your stack.

Models & providers

Choose which AI models power your agents — or bring your own.

Diff review

Understand how agent changes are tracked and how to accept, reject, or undo them.

​The agent loop

​Tools the agent can use

​How the agent understands your project

​Multiple agents

​What agents can’t do

​What’s next