Recovering From Errors

In our previous lesson, we set up permissions to control what the agent is allowed to do. However, even with the best permission settings, mistakes will still happen. You might give the agent vague instructions, or the agent might misunderstand your request and delete code you actually wanted to keep. This is a normal part of working with AI tools.

Because these agents operate quickly, a small misunderstanding can turn into a messy file very fast. Learning to recover from these situations is just as important as learning to give commands. OpenCode provides a built-in safety net that allows you to reverse changes, inspect the current state of your files, and even wipe the agent's memory to start fresh. In this lesson, we will treat error recovery not as a failure, but as a standard tool in your development workflow.

Before you can fix a mistake, you need to understand what just happened. Sometimes the agent says it completed a task, but the file looks unchanged — or it changed the wrong thing entirely. OpenCode provides two tools for diagnosing your situation: the /details toggle and Git's diff command.

The /details toggle switches on verbose tool output, so you can see exactly which tools the agent ran and which files it touched. Once enabled, every subsequent action will show you a full breakdown of what happened under the hood.

> /details
✓ Tool execution details enabled

Once details are on, run !git diff to inspect exactly what changed in the file. The ! prefix lets you run shell commands directly from within OpenCode:

> !git diff HEAD -- sales_data.csv

Output:

diff --git a/sales_data.csv b/sales_data.csv
--- a/sales_data.csv
+++ b/sales_data.csv
@@ -1,9 +1,9 @@
-date,product,region,customer_id,amount,test_flag
+date,product,region,amount,test_flag
-2024-01-15,Widget A,North,C001,1250.00,false
+2024-01-15,Widget A,North,1250.00,false
 ...

Lines starting with - were removed and lines starting with + were added. In this example, the customer_id column was removed from every row. This diagnostic approach helps you confirm exactly what changed before deciding whether to keep or reverse the action. It is also useful to note that if the conversation history gets too long, the agent might become confused or forget earlier instructions — a situation we will address later in this lesson.

The most common error you will encounter is a single incorrect action. Perhaps the agent deleted a function you needed, or it misunderstood a variable name. In these cases, you do not need to restart the entire session; you just need to reverse the very last step. The /undo command is designed exactly for this purpose.

When you run /undo, OpenCode reverts the state of your project to exactly how it was before the agent's last action. This includes reverting changes to files. It works very similarly to Ctrl+Z in a text editor, but it applies to the agent's actions in the terminal.

Let's look at a scenario where the agent accidentally deletes a column from a dataset (assuming /details is enabled):

> Delete the date column from sales_data.csv

● [Reading file: sales_data.csv]
● [Editing file: sales_data.csv]
  Removed column: date
● Updated sales_data.csv

You immediately realize you made a mistake — you needed that date column! Instead of trying to explain to the agent how to put it back (which might lead to more errors), you simply /undo the action:

> /undo

● Undone.

To confirm the file is restored, run !git diff HEAD -- sales_data.csv. If the output is empty, the working tree matches the last commit and the date column is back. This is much faster and safer than asking the agent to "fix it," because "fixing" often introduces new bugs.

Sometimes, you might not catch a mistake immediately. You might give the agent a series of three or four instructions — like creating a file, writing a function, and writing a test — only to realize that the initial approach was wrong. For these situations, you can run /undo multiple times in a row to step back through each action one at a time.

For example, if the last three actions led you down a wrong path, you can reverse all of them:

> /undo
● Undone. Reverted test run.

> /undo
● Undone. Reverted edit to tests.py.

> /undo
● Undone. Reverted edit to main.py.

Each /undo reverses exactly one step. After three calls, all three bad actions are gone. You can confirm the working tree is clean by running:

> !git status

Output:

On branch main
nothing to commit, working tree clean

You can now try a different approach from a clean slate, without the agent being confused by the mistakes it just made.

There are times when a session becomes too messy to save. If the conversation history is very long, the agent might start hallucinating (making things up) or confusing old instructions with new ones. When you feel like the agent is "going in circles," the best strategy is often to wipe the slate clean using the /new command (also available as /clear).

The /new command resets the conversation history but keeps your file changes. This means the agent "forgets" everything you talked about, allowing you to give fresh, focused instructions without the baggage of the previous confusion.

> /new

✓ Started new session

After running /new, you start a brand new conversation. Your files on disk remain exactly as they are — only the agent's memory is wiped. This is the right choice when the problem is not a specific code change, but an accumulation of confusing context.

Knowing which command to use can save you a lot of frustration. We can think of these commands as a toolkit ranging from "light fixes" to "heavy resets." The following guide helps you match the recovery strategy to the specific problem you are facing.

1. Single Mistake (Use /undo): Use this when you catch an error immediately. For example, if the agent edits the wrong file or runs a command you didn't intend, /undo is the quickest fix. It is precise and has no side effects.

2. Wrong Direction (Use /undo multiple times): Use this when you realize the last few steps were a waste of time. Maybe you tried to implement a feature, but after three attempts, it's clearly not working. Running /undo repeatedly lets you scrap that entire attempt and try a different strategy without restarting the whole project.

3. Confused Agent (Use /new): Use this when the agent seems to be ignoring your instructions or repeating itself. This usually happens when the context window (the agent's short-term memory) is full of irrelevant chatter. Starting a new session forces the agent to focus only on what you tell it now.

4. Inspecting Changes (Use !git diff): Use this any time you want to confirm what changed in a file — before or after an undo — so you have a clear picture of the current state before deciding on your next move.

In this lesson, we covered the essential safety tools that allow you to experiment with AI confidently. You learned how to use /details and !git diff to orient yourself after an unexpected change, /undo to fix immediate errors, and repeated /undo calls to reverse a sequence of bad decisions. We also discussed when it is better to simply use /new to start fresh and avoid confusing the agent.

These recovery skills work hand-in-hand with the permissions we set up in the previous lesson. While permissions prevent the agent from doing dangerous things, recovery tools help you fix the inevitable small mistakes — such as deleting important data columns — that happen during development.

In the upcoming practice exercises, you will purposefully guide the agent into making mistakes — such as deleting important data columns in sales_data.csv — so you can practice using these commands to save the day. You will get hands-on experience deciding when to /undo, when to run /undo multiple times, and when to start over with /new.