OpenCode: AI Agent That Reads and Edits Code in Terminal

I spend most of my day in the terminal, whether I’m debugging a systemd service on a RHEL server or writing Bash scripts for the Pro TecMint courses. So when I first tried OpenCode, I didn’t expect much. I had already used a few AI coding tools that felt like add-ons to an IDE and could only guess what was happening based on the file that was open.

OpenCode was different from the start. I pointed it to a messy Node.js project with around 40 files and asked why a background job kept failing silently. It traced the dependencies on its own, opened the right three files, and showed me that the retry logic was swallowing an exception. The whole process took about 90 seconds of typing and a few minutes of waiting.

What made me continue using it was its terminal-first design. It isn’t a browser wrapper or a plugin competing with your editor’s shortcuts. It’s a proper terminal user interface (TUI) with a client-server architecture underneath, so the agent process can keep running even if your terminal session disconnects.

Since it’s not tied to a single AI provider, I can use Claude, OpenAI, or even a local model, depending on the task and how much I want to spend that day.

What OpenCode Actually Does

OpenCode is an open-source AI coding agent that runs inside your terminal and uses a language model to read, write, and modify code in a real project. Instead of copying and pasting code snippets into a chat window, you simply point OpenCode to a project directory, explain what you want to do, and it works directly with your files, runs commands, and applies changes when needed.

Two things make it different from a basic AI chatbot wrapper.

First, it comes with built-in agent modes that you can switch between by pressing the Tab key. The build mode can edit files and run commands, making it useful when you want the agent to implement changes. The plan mode is read-only and is meant for analysis, helping you explore and understand a codebase before allowing it to modify anything.

Second, OpenCode is provider-agnostic, which means you’re not tied to a single AI service. You can connect it to Claude, OpenAI, Google, GitHub Copilot, or even a self-hosted model. You can also switch providers whenever needed, which is useful if one service is rate-limited or becomes too expensive for a particular task.

Prerequisites

Before installing OpenCode, make sure you have the following:

• A 64-bit Linux system. Ubuntu, Debian, RHEL, and Rocky Linux all work fine.
• curl installed, as the official installation script downloads the OpenCode binary over HTTPS.
• A terminal emulator that supports modern terminal user interfaces (TUIs), such as GNOME Terminal, Alacritty, Kitty, or a terminal running inside tmux.
• An account with at least one supported AI provider, such as Claude, OpenAI, Google, or GitHub Copilot.
• You can also use a self-hosted local model if that’s what you prefer.
• A regular user account with sudo privileges if you want to install OpenCode system-wide.

You do not need Node.js installed if you use the official installation script. Node.js is only required if you choose to install OpenCode using npm. In the next sections, I’ll show both installation methods.

Step 1: Install curl and Basic Prerequisites

Most Linux distributions already include curl, but it’s a good idea to verify that it’s installed before continuing. The official OpenCode installer uses curl to download the binary, so the installation cannot proceed without it.

On Ubuntu and Debian:

sudo apt update && sudo apt install curl -y

On RHEL and Rocky Linux:

sudo dnf install curl -y

The sudo command runs the package manager with administrative privileges because installing software requires write access to system directories. If curl is already installed, both commands will simply report that the package is already present and exit without making any changes.

Step 2: Install OpenCode

The easiest way to install OpenCode is by using the official installation script. It automatically detects your Linux distribution and system architecture, downloads the correct binary, and installs it into a directory that’s already in your PATH.

curl -fsSL https://opencode.ai/install | bash

You should see output similar to this:

Installing opencode version: 1.17.18
■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■ 100%
Successfully added opencode to $PATH in /home/ravi/.bashrc

                                 ▄     
█▀▀█ █▀▀█ █▀▀█ █▀▀▄ █▀▀▀ █▀▀█ █▀▀█ █▀▀█
█░░█ █░░█ █▀▀▀ █░░█ █░░░ █░░█ █░░█ █▀▀▀
▀▀▀▀ █▀▀▀ ▀▀▀▀ ▀  ▀ ▀▀▀▀ ▀▀▀▀ ▀▀▀▀ ▀▀▀▀


OpenCode includes free models, to start:

cd   # Open directory
opencode      # Run command

For more information visit https://opencode.ai/docs

Here’s what the command does:

• curl -f makes curl fail if the server returns an error instead of downloading an error page.
• -s runs curl in silent mode and hides the progress meter.
• -S displays an error message if something goes wrong while still keeping silent mode enabled.
• -L tells curl to follow redirects automatically.
• | bash sends the downloaded script directly to Bash, which executes it immediately instead of saving it to a file first.

By default, OpenCode installs into a directory under your home folder. If you want to install it somewhere else, such as/usr/local/bin, set the OPENCODE_INSTALL_DIR environment variable before running the installer:

OPENCODE_INSTALL_DIR=/usr/local/bin curl -fsSL https://opencode.ai/install | bash

If you prefer not to execute a remote script directly, you can install OpenCode using npm instead. This method requires Node.js and npm to be installed on your system.

npm install -g opencode-ai

Arch Linux users can install OpenCode directly from the package repositories:

sudo pacman -S opencode

Step 3: Verify the Installation

After installing OpenCode, make sure the binary is available on your PATH and check which version is installed.

opencode --version

Example output:

opencode version 1.17.18

If you see a command not found error, the OpenCode binary was installed into a directory that your shell does not currently search for commands. In that case, add the installation directory to your PATH.

For Bash or Zsh users, add the following line to your ~/.bashrc or ~/.zshrc file:

export PATH="$HOME/.opencode/bin:$PATH"

Then reload your shell configuration:

source ~/.bashrc

If you’re using Zsh, run:

source ~/.zshrc

Once the shell is reloaded, run opencode --version again to confirm that everything is working properly.

Step 4: Connect a Model Provider

OpenCode needs access to a language model before it can analyze projects, answer questions, or modify code. It doesn’t include a built-in model, so the next step is to connect it to a supported provider.

Start the authentication process with:

opencode auth login

You should see a menu similar to this:

┌  Add credential
│
◆  Select provider

│  Search: _
│  ● OpenCode Zen (recommended
│  ○ Claude
│  ○ OpenAI
│  ○ GitHub Copilot
│  ○ Google
│  ○ Vercel AI Gateway
│  ...
│  ↑/↓ to select • Enter: confirm • Type: to search

Use the arrow keys to select your preferred provider and press Enter.

For Claude and most hosted providers, OpenCode opens a browser-based login page. After you sign in and approve the request, you’ll see a confirmation message in the terminal:

Authenticated successfully with Claude
Credentials saved to ~/.opencode/auth.json

If you prefer not to use the browser-based login, OpenCode can also read API keys from environment variables or a .env file in your project directory. This approach is especially useful on headless servers or in CI/CD pipelines where opening a browser is not practical.

Step 5: Initialize a Project

Move into the project directory that you want OpenCode to work with and start it from there.

cd ~/projects/my-app
opencode

The first time you run OpenCode in a new project, it checks whether a AGENTS.md file already exists. If it doesn’t find one, you’ll see a prompt like this:

No AGENTS.md found in this project.
Generate one now? (Y/n)

Type y and press Enter.

OpenCode then scans the project directory, looks at the file structure, dependencies, and existing project conventions, and generates a AGENTS.md file that summarizes what it finds. This file gives the agent a shared understanding of your project, so it doesn’t have to figure everything out again every time you start a new session.

Example output:

Analyzing project...
Found: package.json, 47 source files, 3 test suites
Created AGENTS.md

Step 6: Run a Real Task

Now that OpenCode is authenticated and understands your project structure, you can start giving it real work.

Launch OpenCode from inside your project directory:

opencode

This opens an interactive terminal interface with a chat-style input box at the bottom and a file and diff view above it. You can describe tasks in plain English, just as you would explain them to another developer.

For example:

> Find why the /api/upload endpoint returns a 500 error on files over 5MB

OpenCode reads the relevant files, traces dependencies, and usually explains the problem before making any changes, especially if you’re in plan mode.

Example output:

Plan mode: read-only analysis
Found the issue in middleware/upload.js:
  The multer limit is set to 5MB but the error handler
  doesn't catch LIMIT_FILE_SIZE, so it falls through to
  a generic 500 instead of returning 413.

At any time, you can press Tab to switch between the two modes:

• Plan mode – Read-only and useful for exploring or analyzing a project safely.
• Build mode – Allows OpenCode to edit files and run commands.

Once you’re happy with the diagnosis, switch to build mode and ask it to apply the fix:

> Switch to build mode and fix that

OpenCode updates the file and shows you a diff before writing anything to disk.

Example:

Editing middleware/upload.js
+ if (err.code === 'LIMIT_FILE_SIZE') {
+   return res.status(413).json({ error: 'File too large' });
+ }
Apply this change? (Y/n)

Here’s what’s happening:

• middleware/upload.js is the file that OpenCode identified as the source of the problem.
• The lines starting with + are the new code that will be added.
• Apply this change? (Y/n) is a confirmation prompt. Nothing is written to your filesystem until you approve it.

That confirmation step is important. AI models can sometimes suggest changes that aren’t quite right for your project. Being able to review the diff before anything is modified gives you control and makes OpenCode practical for real-world development instead of just experimentation.

Step 7: Run OpenCode Non-Interactively

You don’t always need the full terminal interface to use OpenCode. For scripts, CI/CD pipelines, or quick one-off tasks, you can pass a prompt directly on the command line.

For example:

opencode run "Add a .gitignore entry for node_modules and .env"

Example output:

Applying change to .gitignore
node_modules/
.env
Done in 3.2s

In this mode, OpenCode performs the requested task and exits when it’s finished. This is useful when you want to automate repetitive tasks or integrate OpenCode into scripts and workflows without opening the interactive interface.

For example, you could run OpenCode from a shell script, a systemd timer, or a CI/CD pipeline to make simple changes automatically.

It’s also worth knowing that mentioning /opencode or /oc in a GitHub issue or pull request comment can trigger OpenCode to run inside a GitHub Actions runner. This can be useful for automated code analysis or small maintenance tasks directly from the GitHub discussion thread.

Keeping OpenCode Updated

OpenCode receives regular updates with bug fixes, improvements, and new features. If you installed it using the official installation script, the easiest way to update it is to run the same command again:

curl -fsSL https://opencode.ai/install | bash

The installer automatically downloads and installs the latest available version.

If you installed OpenCode using npm, update it with:

npm update -g opencode-ai

Example output:

changed 1 package in 4s
[email protected]

You can check the version currently installed on your system at any time by running:

opencode --version

If you want to see what’s new before upgrading, compare your installed version with the release notes available in the OpenCode changelog at opencode.ai/changelog. This is especially useful if you’re using OpenCode as part of a production workflow and want to understand what has changed before updating.

Conclusion

At this point, you have OpenCode installed, connected to an AI provider, and working with a real project instead of a simple demo. You have also seen the difference between plan mode for safe, read-only analysis and build mode for making actual changes, and you know how to run OpenCode non-interactively for scripts and automated workflows.

The best way to get comfortable with OpenCode is to use it on a project you’re already familiar with. Instead of asking it to build a new feature, start with a bug that you’ve been investigating.

Run it in plan mode first and see whether its analysis matches your understanding of the problem. That’s usually the quickest way to learn what the tool does well and where you still need to be cautious.

Like any AI coding tool, OpenCode works best when you stay involved in the process. It can save time by exploring a codebase, tracing dependencies, and suggesting fixes, but reviewing the proposed changes is still important, especially for production systems.

Taking a moment to read the generated diffs before approving them helps ensure that the changes are correct and align with how you want your project to evolve.