Skip to content
BwatDocs

Core concepts

How Bwat works

Bwat works in a visible loop: understand the project, use a tool, read the result, and keep going until the outcome is verified.

On this page

The agent loop

Bwat does more than return an answer. For a coding task, it repeatedly decides what it needs next, uses a tool, reads the result, and continues until it can deliver the outcome or needs your decision.

  1. Understand: read your request, BWAT.md, the workspace, and the current conversation.
  2. Investigate: search for relevant files, trace the existing behavior, and inspect tests or errors.
  3. Act: edit files, run a command, fetch a page, or call a connected tool.
  4. Observe: read the result and adjust the approach when reality differs from the plan.
  5. Verify: run the checks that show whether the requested outcome now works.
  6. Report: summarize the result, the important files, and anything you still need to know.

Your project is the boundary

Bwat begins at the folder or VS Code workspace you opened. It can freely read inside that boundary. Access to a path outside it requires an explicit folder grant, and writes stay scoped to paths you approved.

The CLI adds a folder-trust check before the first interactive session in a new directory. The check happens before the agent reads project instructions or files.

Tools turn reasoning into work

Tools let Bwat search and read files, edit code, run shell commands, inspect Git state, search the web, and use connected services. The available set changes with the surface and the task. For example, VS Code can provide editor diagnostics while the CLI can work naturally over SSH.

Connected MCP tools are discovered only when a task needs them. This keeps an installation with many integrations responsive while still making every connected tool available.

Permissions stay in the loop

A permission mode decides which actions run immediately and which pause for review. Manual asks before edits and commands. Edit automatically writes files but still asks before commands. Plan mode researches without changing the project. Auto keeps moving without action-by-action prompts.

Auto mode removes the action review step. Use it only in a repository protected by version control and away from production systems, secrets, or work that is expensive to undo.

Bwat can split up larger work

For a large or unfamiliar task, Bwat can delegate focused investigation, planning, or review to additional agents. The main session coordinates them and combines their findings. This is useful when several independent parts of a codebase need to be examined without mixing every detail into one thread.

Long sessions stay usable

As a conversation grows, Bwat condenses older work into a durable summary and keeps the recent turns available. Important project rules come from BWAT.md again on every run, and the complete local transcript remains available if an exact earlier detail is needed.

Use /compact when you finish one phase of a long task and want to free room before the next. Add a short instruction after it if there is something the summary must preserve.

Verification is part of the task

A change is not complete because files were edited. Ask Bwat to run the narrowest useful checks first, then the project build or wider test suite when the risk justifies it. If a check cannot run, Bwat should say exactly what prevented it rather than presenting an unverified change as finished.