OpenCode Agent Mode - Automate Complex Coding Tasks

##What is Agent Mode?

Agent Mode is OpenCode's autonomous execution feature that allows the AI to:

Execute multiple steps without manual confirmation
Read, write, and modify files independently
Run shell commands and analyze output
Make decisions based on context and results

This mode is perfect for complex tasks that require multiple operations.

##Enabling Agent Mode

###Per-Session Activation

Start OpenCode with agent mode enabled:

bash

opencode --agent

Or enable it during a session:

bash

> /agent on
Agent mode enabled. I can now execute multi-step tasks autonomously.

###Configuration File

Enable agent mode by default in your config:

bash

# ~/.config/opencode/config.yaml
agent:
  enabled: true
  require_confirmation: false
  max_steps: 50

##How Agent Mode Works

###Step-by-Step Execution

When you give Agent Mode a task, OpenCode:

Plans - Creates a strategy for completing the task
Executes - Runs each step autonomously
Adapts - Adjusts the plan based on results
Reports - Summarizes what was done

###Example: Setting Up a Project

bash

> Create a new React project with TypeScript, ESLint, and Prettier

Agent Mode will:

bash

Step 1/6: Creating React project with Vite...
> npm create vite@latest my-app -- --template react-ts
✓ Project created

Step 2/6: Installing dependencies...
> cd my-app && npm install
✓ Dependencies installed

Step 3/6: Adding ESLint...
> npm install -D eslint @typescript-eslint/parser
✓ ESLint installed

Step 4/6: Configuring ESLint...
Creating: .eslintrc.cjs
✓ ESLint configured

Step 5/6: Adding Prettier...
> npm install -D prettier eslint-config-prettier
✓ Prettier installed

Step 6/6: Creating Prettier config...
Creating: .prettierrc
✓ Setup complete!

Summary:
- Created React + TypeScript project
- Configured ESLint with TypeScript support
- Added Prettier with ESLint integration

##Safety Features

###Confirmation Prompts

For potentially dangerous operations, Agent Mode asks for confirmation:

bash

Agent wants to execute:
> rm -rf node_modules && npm install

This will delete and reinstall all dependencies.
Proceed? [y/N]

###Sandboxing

Agent Mode operates within safety boundaries:

Cannot modify files outside the project directory
Cannot execute commands that require root access
Limits on network operations
Maximum execution steps to prevent infinite loops

###Undo Support

All changes can be reverted:

bash

> /undo
Reverting last agent operation...
✓ 5 files restored to previous state

##Best Use Cases

###Project Setup

bash

> Set up a Node.js API project with Express, TypeScript, Jest, and Docker

###Refactoring

bash

> Convert all class components in src/components to functional components with hooks

###Debugging

bash

> Find and fix the memory leak in the application

###Testing

bash

> Write comprehensive tests for the auth module, aiming for 90% coverage

###Code Migration

bash

> Migrate from JavaScript to TypeScript in the utils/ directory

##Agent Mode Commands

| Command | Description | |---------|-------------| | /agent on | Enable agent mode | | /agent off | Disable agent mode | | /agent status | Show current agent settings | | /agent pause | Pause execution | | /agent resume | Resume execution | | /agent stop | Stop current operation |

##Configuration Options

bash

agent:
  # Enable/disable agent mode
  enabled: true

  # Require confirmation for file modifications
  require_confirmation: false

  # Require confirmation for shell commands
  require_shell_confirmation: true

  # Maximum steps per task
  max_steps: 50

  # Timeout per step (seconds)
  step_timeout: 60

  # Allowed directories (relative to project root)
  allowed_paths:
    - src/
    - tests/
    - config/

  # Blocked commands
  blocked_commands:
    - rm -rf /
    - sudo
    - shutdown

##Tips for Agent Mode

###Clear Instructions

Be specific about what you want:

❌ "Set up testing" ✅ "Set up Jest with TypeScript support, add coverage reporting, and create a sample test file"

###Set Boundaries

Define the scope of changes:

bash

> Refactor only the files in src/services/ to use async/await instead of promises

###Review Results

After agent operations, review the changes:

bash

> /diff

This shows all modifications made during the agent session.

###Use Checkpoints

For large operations, use checkpoints:

bash

> Create a git commit after each major step

##Troubleshooting

###Agent Gets Stuck

If the agent seems to be looping:

bash

> /agent stop

Then provide more specific instructions.

###Unexpected Changes

If agent made unwanted changes:

bash

> /undo

Or use git to revert:

bash

git checkout -- .

###Permission Errors

Ensure the agent has appropriate permissions:

bash

> /agent paths add ./new-directory

##Next Steps

Learn more about:

Model Configuration - Choose models best suited for agent tasks
Tips & Tricks - Advanced agent mode patterns