Use Bwat
Tips for better results
Keep the conversation focused, bring in only the context that matters, and use Bwat’s built-in controls instead of repeating yourself.
On this page
Keep conversations short and focused
Use one session for one durable goal. Closely related follow-ups benefit from shared history; an unrelated task usually gets a clearer answer in a fresh conversation.
- Run
/clearwhen the objective changes, not merely when you want Bwat to try again. - Run
/compactat a natural phase boundary in a long task. Bwat keeps the decisions and current state while shortening the history it must carry forward. - Run
/historyto continue an earlier goal instead of retelling the whole story in a new session. - When a session has wandered, start fresh and provide a five-line handoff: goal, current state, important files, constraints, and next check.
A short conversation with the right files and a clear goal is usually more useful than a long conversation containing every thought you had along the way.
Mention the files that matter
In VS Code, Bwat can start from the active file and your current selection. Type @ in VS Code or the CLI to attach another workspace file by path. This is the quickest way to remove ambiguity without pasting an entire file into the message.
@src/auth/session.ts The refresh path sometimes signs a user out. Trace the failure from this file, reproduce it, and add a regression test. Keep the public session shape unchanged.
Mention the starting point, not every file you think Bwat should edit. Let it search for callers, tests, and related behavior so a guessed file list does not hide the real path.
Learn the small set of slash commands
| Command | When to use it |
|---|---|
/help | Open this documentation from VS Code or the CLI |
/skills | See the skills currently available to this agent |
/mode | Change how often Bwat pauses for approval |
/effort | Choose how deeply Bwat should work through a request |
/init | Propose a BWAT.md for the current repository |
/history | Resume an earlier session |
/compact | Shorten a long conversation while keeping its important state |
/clear | Start a new conversation |
Type / to browse the commands available in your current client. The CLI also accepts unique prefixes, so /cl resolves to /clear.
Use skills for specialized work
A skill gives Bwat a tested workflow for a specific kind of task. Bwat can choose a matching skill automatically, or you can run one directly as /<skill-name> with any requested argument. Use /skills to see the live list, then read Use skills for the catalog and examples.
/code-review Review my current changes against main. /frontend-design Redesign the empty state in @app/projects/page.tsx. Preserve the existing component library and verify the production build.
Know what Bwat remembers
| Place | Use it for |
|---|---|
| Session history | The decisions and work for one goal; reopen it with /history |
| Project memory | Small private facts Bwat learned while working in this project on this machine |
BWAT.md | Stable repository commands, architecture, and rules the team should share |
BWAT.local.md | Personal instructions for one checkout; keep it out of version control |
If you have corrected the same command, boundary, or convention twice, put it in BWAT.md. Read Instructions and memory and Manage sessions for the details.
Describe success, not just activity
A strong request says what should be true when the task is finished. Include the user-visible outcome, important constraints, and how the result can be checked.
| Instead of | Try |
|---|---|
| “Fix auth” | “Fix the blank screen after an expired session. Reproduce it, preserve the redirect target, and run the auth route tests.” |
| “Add tests” | “Add tests for PaymentClient retry behavior, including timeout and final-failure cases, using the existing test style.” |
| “Make this cleaner” | “Remove the duplicate parsing paths without changing the public API. Keep the diff focused and run the parser suite.” |
Give evidence with bug reports
- Paste the exact error and the command that produced it.
- List the shortest reliable reproduction steps.
- State the expected behavior and what happened instead.
- Mention whether the bug is consistent, platform-specific, or tied to particular data.
- Attach a screenshot when the problem is visual.
Match the mode to the risk
Use Plan mode when the change crosses several systems or the wrong architecture would create rework. Begin in Manual while learning how Bwat acts in a project. Use Auto only when the task is bounded, version control protects the work, and no production system is in reach.
Ask for verification explicitly
Name the check when you know it: a focused test file, typecheck, linter, build, or reproduction command. For interface work, ask Bwat to verify the interaction as well as compilation. If no automated check exists, ask for a short manual test plan.
Steer early and directly
Interrupt a run with Escape and explain what should change. Short corrections such as “keep the public type unchanged” or “the source of truth is the server” are more useful than waiting for an entire wrong approach to finish.