npm package: @iwahbi/opencode-claude-stack
Description: Primary OpenCode Claude stack with a thin plugin, local daemon, and one-line installer.
Latest version: 1.1.8

# opencode-claude-stack

`opencode-claude-stack` connects OpenCode to Claude Code through a local daemon.

It is designed for people who want Claude models inside OpenCode without hand-editing request headers, auth wiring, or OpenCode plugin internals.

## What This Does

After setup, OpenCode Anthropic requests go through this path:

```text
OpenCode
-> opencode-claude-stack plugin
-> local Claude Stack daemon
-> certified Claude compatibility profile
-> direct Anthropic backend
```

The stack:

1. reads your Claude Code login from your machine
2. installs the OpenCode plugin entry for you
3. writes the OpenCode Anthropic bridge record for you
4. starts the local daemon for you
5. verifies the setup with a real OpenCode smoke test

## Before You Start

You need these tools installed first:

1. `node`
2. `pnpm`
3. `opencode`
4. `claude`

You must also already be logged into Claude Code.

If you have never used Claude Code on this machine, do this first:

```bash
claude
```

Important:

1. `claude` opens the Claude Code interface
2. sign in there if Claude Code asks you to log in
3. once login is complete, quit Claude Code and return to your terminal
4. do **not** do a separate real Anthropic login inside OpenCode for this stack
5. the installer handles the OpenCode side for you

## Choose An Install Path

There are two install paths.

### Option 1: Install From GitHub

Use this if you are installing from this repository directly.

This is the best path when:

1. you want the latest code from GitHub
2. the npm package is not live yet
3. you are helping test the latest release

Commands:

```bash
git clone https://github.com/ihabwahbi/opencode-claude-stack.git
cd opencode-claude-stack
pnpm install
pnpm bootstrap
```

That works on:

1. macOS Terminal
2. Linux shells and WSL2
3. Windows PowerShell or Windows Terminal

### Option 2: Install From npm

Use this after the package is available on npm.

```bash
npx @iwahbi/opencode-claude-stack install
```

If npm install is not live yet, use the GitHub install path above.

## Beginner Quick Start

If you want the shortest working setup, do exactly this.

First, make sure Claude Code is already signed in on this machine.

If it is not signed in yet:

1. run `claude`
2. finish login in the Claude Code interface
3. quit Claude Code and return to your terminal

Then run:

```bash
git clone https://github.com/ihabwahbi/opencode-claude-stack.git
cd opencode-claude-stack
pnpm install
pnpm bootstrap
```

Then test it:

```bash
opencode run -m anthropic/claude-haiku-4-5 "Reply with HELLO_STACK and nothing else."
```

If the stack is working, OpenCode should reply with `HELLO_STACK`.

## What The Installer Changes

The installer is intentionally small and predictable.

It does all of the following:

1. checks that `opencode` is installed
2. checks that `claude` is installed
3. checks that Claude credentials exist on your machine
4. backs up your OpenCode config and auth files
5. adds the `opencode-claude-stack` plugin to OpenCode config
6. writes the managed Anthropic bridge auth entry into OpenCode
7. starts the Claude Stack daemon
8. runs a real OpenCode smoke test

Plugin conflict handling:

1. known older Claude auth plugins are removed automatically during install
2. unrelated plugins are kept
3. unknown Claude or Anthropic auth-like plugins are not removed silently
4. if one of those unknown plugins is found, the installer stops and tells the user what to remove

It does **not**:

1. replace your Claude Code login
2. ask you to manually edit OpenCode request headers
3. require you to keep a custom daemon command running by hand in normal use

## Platform Support

`opencode-claude-stack` is intended to support every platform where OpenCode and Claude Code both work.

### macOS

Supported.

Behavior:

1. prefers Claude credentials from macOS Keychain
2. falls back to `~/.claude/.credentials.json` if needed
3. prefers the same OpenCode paths that already exist on the machine
4. defaults to `~/.config/opencode` and `~/.local/share/opencode` for fresh installs
5. still respects an existing `~/Library/Application Support/opencode` install if that is already what OpenCode uses

### Linux

Supported.

Behavior:

1. reads Claude credentials from `~/.claude/.credentials.json`
2. uses standard XDG-style OpenCode paths
3. typical config path: `~/.config/opencode`
4. typical data path: `~/.local/share/opencode`
5. WSL2 uses the same Linux paths inside the distro

### Windows

Supported.

Behavior:

1. reads Claude credentials from `%USERPROFILE%\.claude\.credentials.json`
2. uses OpenCode config/data locations under `%USERPROFILE%\.config\opencode` and `%USERPROFILE%\.local\share\opencode`
3. works through PowerShell or Windows Terminal
4. detects common Git for Windows installs, persists `CLAUDE_CODE_GIT_BASH_PATH`, and updates the standard PowerShell profile when needed

## Daily Use

After installation, use OpenCode normally with an Anthropic model.

Example:

```bash
opencode run -m anthropic/claude-haiku-4-5 "Reply with STACK_OK and nothing else."
```

## Commands

If you installed from npm:

```bash
npx @iwahbi/opencode-claude-stack reset
npx @iwahbi/opencode-claude-stack doctor
npx @iwahbi/opencode-claude-stack status
npx @iwahbi/opencode-claude-stack daemon status
```

The npm installer also refreshes OpenCode's cached copy of this plugin so rerunning `npx @iwahbi/opencode-claude-stack install` picks up the published version you just installed.

If you installed from a GitHub checkout:

```bash
node dist/cli.js doctor
node dist/cli.js status
node dist/cli.js daemon status
```

Available commands:

1. `install`
2. `reset`
3. `doctor`
4. `status`
5. `daemon start`
6. `daemon stop`
7. `daemon status`

Useful install flag:

1. `--plugin self`
   This tells the installer to register the current checkout as the OpenCode plugin.

## What OpenCode Config Looks Like

Most users do not need to edit `opencode.json` manually.

After install, OpenCode will have a plugin entry like this:

```json
{
  "plugin": ["/absolute/path/to/opencode-claude-stack"]
}
```

The installer writes that automatically.

## Troubleshooting

### `Claude Code credentials were not found`

Run:

```bash
claude
```

Then:

1. complete login in the Claude Code interface if prompted
2. quit Claude Code
3. rerun the Claude Stack installer

and complete Claude Code login first.

### `OpenCode smoke test failed`

Run:

```bash
node dist/cli.js doctor
```

or, if you installed from npm:

```bash
npx @iwahbi/opencode-claude-stack doctor
```

If you want to remove only Claude Stack managed state before retrying the install:

```bash
npx @iwahbi/opencode-claude-stack reset
```

### `daemon: null` in `doctor`

That means the daemon is not currently running.

It does **not** automatically mean the install failed.

Check status:

```bash
node dist/cli.js status
```

Start the daemon manually if needed:

```bash
node dist/cli.js daemon start
```

### npm install returns `404`

The npm package may not be published yet.

Use the GitHub install path instead:

```bash
git clone https://github.com/ihabwahbi/opencode-claude-stack.git
cd opencode-claude-stack
pnpm install
pnpm bootstrap
```

## Maintainer Commands

These are maintainer workflows, not normal user install steps:

```bash
pnpm compat:release
pnpm compat:monitor
pnpm compat:status
```

Package publishing from GitHub Actions is described in `docs/trusted-publishing.md`.

## License

MIT