Project paths

OpenCode V2 terminal plugin for starting sessions in saved project folders. No additional dependencies are required.

Usage

Press Ctrl+x, then p to open the folder picker. Select Add project folder and enter an existing absolute path, such as /Users/mokrucky/Documents/rpms. Select a saved folder to open the empty OpenCode start page in that folder. No session or title is created yet. OpenCode creates the session when you send your first prompt and generates its title normally.

The connected OpenCode server validates folders before saving them. Paths must exist on that server. Relative paths and home shortcuts such as ~/project are not accepted. This plugin does not create directories.

Folders persist across restarts and are shared across terminal instances through OpenCode plugin storage. Existing sessions and the normal Ctrl+x, then n shortcut are unchanged. Escape cancels without creating a session.

The command palette also provides New session in project folder, Add project folder, and Remove saved project folder. Their slash commands are /projectnew, /projectadd, and /projectremove. Removing a saved folder only forgets its path. It never deletes folders, files, or sessions.

Press Ctrl+x, then o to open a new tab in the Apple Terminal window running OpenCode, like Cmd+T. The tab starts in the current session folder, or the current start page folder before a session exists. This opens a plain shell, not another OpenCode instance. The command palette also provides Open current folder in Terminal tab. The existing OpenCode tab is left unchanged.

Opening a tab requires macOS, OpenCode running directly in Apple Terminal, and an existing local folder. Remote folders are not downloaded or opened over SSH. Other terminal apps and terminal multiplexers are not supported. macOS may ask for permission to control Terminal and System Events. Allow Accessibility access for Terminal in System Settings, Privacy & Security, Accessibility. If the window cannot be found or the new tab cannot be created, the shortcut reports an error rather than opening a separate window.

Shortcut

To change the shortcut, merge this entry into keybinds in ~/.config/opencode/cli.json, preserving existing entries:

{
  "keybinds": {
    "project.paths.new": "<leader>p",
    "project.paths.terminal": "<leader>o"
  }
}

The leader key defaults to Ctrl+x. For a single chord, use a binding such as ctrl+alt+p instead.

Loading

Install the published plugin and add it to your global OpenCode configuration:

opencode plugin add opencodefolders

For manual setup, add opencodefolders to the plugins array in ~/.config/opencode/cli.json, preserving existing entries. If XDG_CONFIG_HOME is set, use $XDG_CONFIG_HOME/opencode/cli.json instead.

{
  "$schema": "https://opencode.ai/v2/cli.json",
  "plugins": [
    "opencodefolders"
  ]
}

Merge this into your existing configuration rather than replacing the file.

Restart the terminal client if the new commands are not visible. The OpenCode service does not need a restart.

Tests

Run npm test from this folder with a current Node version that supports TypeScript type stripping.