diff --git a/packages/opencode/src/flag/flag.ts b/packages/opencode/src/flag/flag.ts index 64ae801d18f..006844d05f0 100644 --- a/packages/opencode/src/flag/flag.ts +++ b/packages/opencode/src/flag/flag.ts @@ -9,6 +9,10 @@ export namespace Flag { export const OPENCODE_CONFIG = process.env["OPENCODE_CONFIG"] export declare const OPENCODE_CONFIG_DIR: string | undefined export const OPENCODE_CONFIG_CONTENT = process.env["OPENCODE_CONFIG_CONTENT"] + export const OPENCODE_DATA_DIR = process.env["OPENCODE_DATA_DIR"] + export const OPENCODE_CACHE_DIR = process.env["OPENCODE_CACHE_DIR"] + export const OPENCODE_LOG_DIR = process.env["OPENCODE_LOG_DIR"] + export const OPENCODE_STATE_DIR = process.env["OPENCODE_STATE_DIR"] export const OPENCODE_DISABLE_AUTOUPDATE = truthy("OPENCODE_DISABLE_AUTOUPDATE") export const OPENCODE_DISABLE_PRUNE = truthy("OPENCODE_DISABLE_PRUNE") export const OPENCODE_DISABLE_TERMINAL_TITLE = truthy("OPENCODE_DISABLE_TERMINAL_TITLE") diff --git a/packages/opencode/src/global/index.ts b/packages/opencode/src/global/index.ts index 10b6125a6a9..e96a13b82c7 100644 --- a/packages/opencode/src/global/index.ts +++ b/packages/opencode/src/global/index.ts @@ -2,13 +2,15 @@ import fs from "fs/promises" import { xdgData, xdgCache, xdgConfig, xdgState } from "xdg-basedir" import path from "path" import os from "os" +import { Flag } from "../flag/flag" const app = "opencode" -const data = path.join(xdgData!, app) -const cache = path.join(xdgCache!, app) +const data = Flag.OPENCODE_DATA_DIR || path.join(xdgData!, app) +const cache = Flag.OPENCODE_CACHE_DIR || path.join(xdgCache!, app) +const log = Flag.OPENCODE_LOG_DIR || path.join(data, "log") const config = path.join(xdgConfig!, app) -const state = path.join(xdgState!, app) +const state = Flag.OPENCODE_STATE_DIR || path.join(xdgState!, app) export namespace Global { export const Path = { @@ -18,7 +20,7 @@ export namespace Global { }, data, bin: path.join(data, "bin"), - log: path.join(data, "log"), + log, cache, config, state, diff --git a/packages/web/src/content/docs/cli.mdx b/packages/web/src/content/docs/cli.mdx index 7fb948f5054..724b4dfa2f7 100644 --- a/packages/web/src/content/docs/cli.mdx +++ b/packages/web/src/content/docs/cli.mdx @@ -558,6 +558,10 @@ OpenCode can be configured using environment variables. | `OPENCODE_CONFIG` | string | Path to config file | | `OPENCODE_CONFIG_DIR` | string | Path to config directory | | `OPENCODE_CONFIG_CONTENT` | string | Inline json config content | +| `OPENCODE_DATA_DIR` | string | Path to data directory | +| `OPENCODE_CACHE_DIR` | string | Path to cache directory | +| `OPENCODE_LOG_DIR` | string | Path to log directory | +| `OPENCODE_STATE_DIR` | string | Path to state directory | | `OPENCODE_DISABLE_AUTOUPDATE` | boolean | Disable automatic update checks | | `OPENCODE_DISABLE_PRUNE` | boolean | Disable pruning of old data | | `OPENCODE_DISABLE_TERMINAL_TITLE` | boolean | Disable automatic terminal title updates | diff --git a/packages/web/src/content/docs/config.mdx b/packages/web/src/content/docs/config.mdx index 1474cb91558..3e9b7d2a125 100644 --- a/packages/web/src/content/docs/config.mdx +++ b/packages/web/src/content/docs/config.mdx @@ -142,6 +142,67 @@ opencode run "Hello world" The custom directory is loaded after the global config and `.opencode` directories, so it **can override** their settings. +### Custom data directory + +Specify a custom data directory using the `OPENCODE_DATA_DIR` +environment variable. This controls where OpenCode stores runtime data +like authentication tokens, logs, cached files, and LSP binaries. + +```bash +export OPENCODE_DATA_DIR=/path/to/my/data-directory +opencode run "Hello world" +``` + +By default, OpenCode stores data in `~/.local/share/opencode` on Linux/macOS +or `%LOCALAPPDATA%\opencode` on Windows. + +--- + +### Custom cache directory + +Specify a custom cache directory using the `OPENCODE_CACHE_DIR` +environment variable. This controls where OpenCode stores cached data +like npm plugins and their dependencies. + +```bash +export OPENCODE_CACHE_DIR=/path/to/my/cache-directory +opencode run "Hello world" +``` + +By default, OpenCode stores cache in `~/.cache/opencode` on Linux/macOS +or `%LOCALAPPDATA%\opencode` on Windows. + +--- + +### Custom log directory + +Specify a custom log directory using the `OPENCODE_LOG_DIR` +environment variable. This controls where OpenCode stores log files. + +```bash +export OPENCODE_LOG_DIR=/path/to/my/log-directory +opencode run "Hello world" +``` + +By default, OpenCode stores logs in the data directory at `$OPENCODE_DATA_DIR/log` +(or `~/.local/share/opencode/log` if `OPENCODE_DATA_DIR` is not set). + +--- + +### Custom state directory + +Specify a custom state directory using the `OPENCODE_STATE_DIR` +environment variable. This controls where OpenCode stores UI state +like model selection, prompt history, stashed prompts, and frecency data. + +```bash +export OPENCODE_STATE_DIR=/path/to/my/state-directory +opencode run "Hello world" +``` + +By default, OpenCode stores state in `~/.local/state/opencode` on Linux/macOS +or `%LOCALAPPDATA%\opencode` on Windows. + --- ## Schema diff --git a/packages/web/src/content/docs/plugins.mdx b/packages/web/src/content/docs/plugins.mdx index ba530a6d9ba..a2b3f99a970 100644 --- a/packages/web/src/content/docs/plugins.mdx +++ b/packages/web/src/content/docs/plugins.mdx @@ -45,7 +45,7 @@ Browse available plugins in the [ecosystem](/docs/ecosystem#plugins). ### How plugins are installed -**npm plugins** are installed automatically using Bun at startup. Packages and their dependencies are cached in `~/.cache/opencode/node_modules/`. +**npm plugins** are installed automatically using Bun at startup. Packages and their dependencies are cached in the cache directory (`~/.cache/opencode/node_modules/` by default, or `$OPENCODE_CACHE_DIR/node_modules/` if set). **Local plugins** are loaded directly from the plugin directory. To use external packages, you must create a `package.json` within your config directory (see [Dependencies](#dependencies)), or publish the plugin to npm and [add it to your config](/docs/config#plugins). diff --git a/packages/web/src/content/docs/troubleshooting.mdx b/packages/web/src/content/docs/troubleshooting.mdx index 40ac70b9eb7..0ac7fa592bf 100644 --- a/packages/web/src/content/docs/troubleshooting.mdx +++ b/packages/web/src/content/docs/troubleshooting.mdx @@ -259,7 +259,7 @@ To resolve provider package issues: 1. Clear the provider package cache: ```bash - rm -rf ~/.cache/opencode + rm -rf ${OPENCODE_CACHE_DIR:-${HOME}/.cache/opencode} ``` On Windows, press `WIN+R` and delete: `%USERPROFILE%\.cache\opencode`