working with the agent

The AI agent is twig's core feature. This page covers how to interact with it effectively, review its work, and get the best results.

starting a conversation

Type your request in the chat input at the bottom of the agent panel. Be specific about what you want to accomplish:

add input validation to the email field in the signup form.
reject invalid email formats and show an error message.

Press enter or click send. The agent will begin working on your request.

how the agent works

When you send a message, the agent:

1. understands your request - parses what you're asking for
2. gathers context - reads relevant files, searches code
3. plans an approach - decides how to accomplish the task
4. takes action - makes edits, runs commands
5. reports back - shows you what it did and asks for approval

You'll see each step in the conversation as it happens.

reviewing changes

Before any code changes are applied, the agent shows you what it proposes:

• file path - which file will be modified
• diff view - what will change (deletions in red, additions in green)
• explanation - why the change is being made

You can:

• approve - apply the change
• reject - skip this change
• modify - edit the proposed change before applying
• ask questions - request clarification before deciding

agent capabilities

Before sending requests, it helps to know what the agent can do:

• read files - examines code to understand structure and patterns
• search code - finds functions, classes, or patterns across your project
• edit files - proposes changes with diffs for your review
• run commands - executes terminal commands after your approval

See agent tools for detailed capabilities and limitations.

prompting examples

how you ask makes a big difference. compare vague vs specific requests:

vague → specific

❌ vague: "make the form better" ✅ specific: "add client-side validation to the email field. reject invalid formats and show an error message below the input."

❌ vague: "fix the bug" ✅ specific: "the signup API returns 500 when email is missing. add input validation to check required fields before the API call."

❌ vague: "optimize this" ✅ specific: "this function runs on every keystroke and causes lag. debounce it to only run 300ms after the user stops typing."

❌ vague: "update the styles" ✅ specific: "change the button color to match our design system. use the primary-blue variable and add a hover state."

providing context

help the agent understand your codebase:

we use tailwind for styling throughout this project.
add a loading spinner to the submit button using tailwind classes.

specifying constraints

Tell the agent about requirements:

add error handling to this function.
use our existing errorLogger utility instead of console.log.
keep the function under 50 lines.

breaking down complex tasks

For large tasks, work incrementally:

let's add user authentication to this app.
first, explain the current auth-related code so i understand the starting point.

Then:

now add a login endpoint that validates credentials against the database.

conversation management

when to continue the conversation

Keep the same conversation when:

• The agent has relevant context from earlier messages
• You're iterating on the same feature or fix
• Follow-up questions relate to the current topic

The agent remembers your conversation history and can reference earlier decisions.

when to start fresh

Start a new conversation when:

• Switching to an unrelated task
• The conversation has become long and unfocused
• You want the agent to forget previous context
• The agent seems confused by accumulated context

Fresh starts help the agent focus without distraction from unrelated history.

clearing context

If a conversation feels cluttered:

let's start fresh on this. ignore previous context.
the goal is: [clear description of what you want now]

when to use the agent vs manual editing

Understanding when to use which approach saves time.

use the agent when:

• multi-file changes - updating patterns across several files
• exploring unfamiliar code - understanding how something works
• complex refactoring - changes requiring understanding of relationships
• generating boilerplate - repetitive code with consistent patterns
• context-heavy tasks - modifications that depend on existing code

edit manually when:

• single-line changes - you know exactly what to type
• simple typos - faster to fix directly
• rapid experimentation - trying multiple small variations quickly
• you're faster - explaining would take longer than doing

Neither is better - choose based on efficiency for the specific task.

when things go wrong

agent misunderstands

If the agent does something different from what you wanted:

that's not quite right. i meant the email validation should happen
on form submit, not on every keystroke. please update the approach.

agent gets stuck

If the agent seems confused or loops:

let's start fresh. forget the previous approach.
the goal is: [clear statement of what you want]

errors in generated code

If code doesn't work:

this gives an error: [paste the error].
please fix the issue.

best practices summary

• be specific - detailed requests get better results than vague ones
• one thing at a time - focused requests avoid confusion
• provide examples - show what you want when possible
• let it explore - ask about existing code before requesting changes
• use context - explain project conventions or constraints
• break down complexity - tackle large tasks incrementally

related pages

• agent tools - what the agent can do
• rules - persistent instructions for the agent
• glossary - key terms explained