global-install

name	global-install
origin	fajar-dev
description	Global installation strategy for opencode-agent-kit: cross-platform config paths, symlink-based per-project setup, environment variable overrides, and upgrade workflow.

Global Install — opencode-agent-kit

Install opencode-agent-kit once globally and use it across all your projects without re-running npx opencode-agent-kit init in each one.

The Problem

The agent kit currently requires npx opencode-agent-kit init in every project, which copies 200+ skill files, 34 agent prompts, 47 commands, and MCP configs into .opencode/. This means:

• Every project gets a full copy — wasted disk space
• Updates require re-init or manual migration in each project
• No single source of truth for your agent config
• opencode.json with skill paths locked to per-project .opencode/

The Solution

Install the kit once to a platform-appropriate global directory, then link each project to it.

┌──────────────────────────────────────────────────┐
│         OpenCode Global Config Directory          │
│  ~/.config/opencode/        (macOS/Linux)        │
│  %USERPROFILE%\.config\opencode\  (Windows)       │
│                                                   │
│  The template's .opencode/ contents are copied    │
│  FLAT into this directory (no .opencode wrapper): │
│                                                   │
│  ├── opencode.jsonc          ← merged config      │
│  ├── instructions/                                │
│  ├── skills/                 ← 200+ skills        │
│  ├── prompts/agents/         ← 34 agents          │
│  ├── commands/               ← 47 commands        │
│  ├── hooks/                  ← automation hooks   │
│  ├── rules/                  ← scoped rules       │
│  ├── docs/                   ← reference docs     │
│  ├── contexts/               ← dev/review modes   │
│  ├── plugins/                ← agent plugins      │
│  └── package.json            ← dependencies       │
└──────────────────────────────────────────────────┘
         │
         │ OpenCode auto-detects this config
         ▼
┌──────────────────────┐    ┌──────────────────────┐
│   Project A          │    │   Project B          │
│                      │    │                      │
│  (no .opencode/      │    │  (no .opencode/      │
│   needed — global    │    │   needed — global    │
│   config is used)    │    │   config is used)    │
└──────────────────────┘    └──────────────────────┘

Advantages

• Single update — upgrade once, all projects use the new version
• Zero copy — no file duplication across projects
• Disk efficient — 200+ skills stored once
• Project isolation — opencode.json per project can still have overrides
• Git-clean — .opencode/ is symlinked and gitignored
• Offline capable — once installed globally, no network needed per project

Cross-Platform Path Resolution

Platform	Default Path	Env Override	Config Format
macOS	~/.config/opencode/	OPENCODE_HOME	opencode.jsonc
Linux	$XDG_CONFIG_HOME/opencode/ (default: ~/.config/...)	OPENCODE_HOME	opencode.jsonc
Windows	%USERPROFILE%\.config\opencode\	OPENCODE_HOME	opencode.jsonc

Implementation (Node.js)

import { homedir, platform } from 'os';
import { join } from 'path';

function getOpenCodeHome() {
  if (process.env.OPENCODE_HOME) {
    return process.env.OPENCODE_HOME;
  }

  if (platform() === 'win32') {
    // Windows: %USERPROFILE%\.config\opencode\ (NOT %APPDATA%)
    const userProfile = process.env.USERPROFILE || join(homedir(), 'AppData', 'Roaming');
    return join(userProfile, '.config', 'opencode');
  }

  const xdgConfig = process.env.XDG_CONFIG_HOME || join(homedir(), '.config');
  return join(xdgConfig, 'opencode');
}

Commands

opencode-agent-kit init --global

Installs the full kit to the global config directory.

$ opencode-agent-kit init --global

  opencode-agent-kit init --global

  → OpenCode home: ~/.config/opencode/
  → Copying skills, prompts, commands, instructions...
  → Merging configuration into opencode.jsonc...
  → Installing OpenCode dependencies...
  ✓ Dependencies installed
  ✓ agentmemory already installed
  ✓ portless already installed

  ✅ opencode-agent-kit v1.3.5 installed globally!

  Location: ~/.config/opencode/

  Installed:
    • skills/              — 200+ skill playbooks
    • prompts/agents/      — 34 agent prompt files
    • commands/            — 47 slash commands
    • instructions/        — Core rules
    • hooks/               — Automation hooks
    • rules/               — Scoped coding rules
    • opencode.jsonc       — Merged configuration
    • agentmemory (global) — Persistent memory
    • portless (global)    — Dev server URLs

  Next: OpenCode will automatically use this config.

opencode-agent-kit link (macOS/Linux)

On macOS and Linux, OpenCode auto-detects the global config at ~/.config/opencode/. No per-project setup is needed.

$ cd my-project
$ opencode-agent-kit link

  opencode-agent-kit link
  ──────────────────────────────────────────────────

  → OpenCode on this platform auto-detects the global config.
  → Global config at: ~/.config/opencode/
  ✓ No per-project setup needed — OpenCode reads global config automatically.

  Next: run `opencode` to start.

opencode-agent-kit link (Windows)

On Windows, creates a junction from .opencode/ → global config.

$ opencode-agent-kit link

  → Global install found at %USERPROFILE%\.config\opencode\
  → Creating .opencode/ junction...
  → Creating opencode.json...
  → Updating .gitignore...

  ✅ Project linked!

opencode-agent-kit global path

Prints the global install path.

$ opencode-agent-kit global path
~/.config/opencode/

opencode-agent-kit global update

Updates the global install to the latest version.

$ opencode-agent-kit global update

  → Checking latest version...
  → Current: v1.3.4 → Latest: v1.3.5
  → Updating global install...
  → Updating agentmemory and portless...

  ✅ Global install updated to v1.3.5!

opencode-agent-kit init --local

Explicitly copies everything locally (traditional behavior). Use when:

• You want the config committed to the project repo
• You need custom overrides without affecting other projects
• No global install exists

How the Global Config Works

On macOS and Linux, OpenCode automatically reads ~/.config/opencode/opencode.jsonc. All skills, prompts, commands, and instructions are stored flat in that directory. When you run opencode in any project, OpenCode finds this global config and loads everything.

During global install, all .opencode/ references in the config are rewritten to absolute paths, in these locations:

Config Section	Template Reference	Global Config (absolute)
instructions[]	.opencode/instructions/INSTRUCTIONS.md	/Users/user/.config/opencode/instructions/INSTRUCTIONS.md
agent.*.prompt	{file:.opencode/prompts/agents/...}	{file:/Users/user/.config/opencode/prompts/agents/...}
mcp.*.command[]	.opencode/hooks/agentmemory-start.mjs	/Users/user/.config/opencode/hooks/agentmemory-start.mjs
plugin[]	.opencode/plugins/agentmemory-capture.ts	/Users/user/.config/opencode/plugins/agentmemory-capture.ts

Why absolute? OpenCode resolves paths in opencode.jsonc relative to the current project directory, not relative to ~/.config/opencode/. Relative paths would fail in every project. Absolute paths guarantee the files are found regardless of where you run opencode.

Note: prose .opencode/ references inside skill .md files, agent prompts, and documentation files are informational text for the LLM and are not resolved by OpenCode — these are left as-is.

Per-Project Setup

On macOS and Linux, no per-project setup is needed. OpenCode auto-detects the global config. Just start opencode in any project directory.

On Windows, opencode-agent-kit link creates a junction from .opencode/ → global config.

Project-Specific Overrides

When you need custom skills or commands for a specific project:

Option A: Local-only extras

Create a .opencode.local/ directory in your project with additional skill files. The op encode.json instructions array can reference both the global and local paths.

Option B: Detach to full copy

Run opencode-agent-kit init --local to copy everything into the project, breaking the link to the global install. You can then freely modify it.

Option C: Layered AGENTS.md

Use AGENTS.md in the project root for project-specific rules. The global kit handles the generic agent behavior.

Migration from Per-Project to Global

# 1. Install globally
npx opencode-agent-kit init --global

# 2. Remove old per-project copies (optional)
rm -rf project-a/.opencode project-a/opencode.json

# 3. Link projects
cd project-a && npx opencode-agent-kit link
cd project-b && npx opencode-agent-kit link

# 4. Verify
npx opencode-agent-kit doctor

Windows-Specific Notes

• On Windows, OpenCode reads from %USERPROFILE%\.config\opencode\opencode.jsonc
• Directory junctions (fs.symlinkSync with 'junction' type) work without admin on NTFS
• If junction creation fails, falls back to copying a minimal reference config

Edge Cases

Scenario	Behaviour
No global install exists	init falls back to local copy (traditional)
Global install is outdated	doctor warns and suggests global update
OPENCODE_HOME set	Uses that path instead of OS default
opencode.jsonc exists with provider config	Merges kit entries, preserves existing provider/MCP config
Files already exist at destination (skills/, prompts/)	Copied with merge (existing package.json preserved)
Global install deleted	doctor detects missing opencode.jsonc, suggests init --global

Design Rationale

Why install into ~/.config/opencode/ instead of a separate directory?

On macOS and Linux, OpenCode reads its configuration from ~/.config/opencode/opencode.jsonc automatically. By installing the agent kit directly into this directory, OpenCode picks it up without any per-project setup, symlinks, or config file modifications.

Why OpenCode config at ~/.config/opencode/ instead of project-level .opencode/?

OpenCode supports both levels. The global config at ~/.config/opencode/ provides base configuration (agents, skills, MCP servers). Project-level .opencode/ can override or extend it. The agent kit focuses on the global level so all projects benefit.

Why flat structure instead of kit/ subdirectory?

OpenCode expects skills at ~/.config/opencode/skills/, prompts at ~/.config/opencode/prompts/agents/, etc. A kit/ subdirectory would break auto-discovery. The flat structure matches OpenCode's expectations.

Why merge into opencode.jsonc instead of overwriting it?

Most users already have custom OpenCode configuration (providers, API keys, model selections). Overwriting would break their setup. Merging preserves their existing config while adding the agent kit's instructions, agents, and MCP servers.

Why opencode.jsonc (JSONC) instead of opencode.json?

OpenCode uses JSONC format which supports comments — important for provider configurations with commented-out models, API key notes, etc. The merge writes standard JSON (which OpenCode also reads) to avoid complexity. Users can reformat to JSONC if desired.