Support for using additional npm packages in custom tools

Environment

Installed as npm install opencode-ai --save-dev, using version 0.11.3
Node.js: v22.19.0
macOS: Tahoe 26.0

Issue
When creating custom tools, is it possible to use additional npm packages? I didn’t find any mention of this in the docs: https://opencode.ai/docs/custom-tools/

What I Tried

Added serialport to the main project package.json (devDependencies) → no effect
Added dependencies under .opencode/tool/ → caused Opencode to crash

Feature Request
It would be great if custom tools could use additional libraries without needing to build a separate MCP server.

Yes it is possible

For example if I create a global tool: ~/.config/opencode/tool/test.ts:

import { tool } from "@opencode-ai/plugin";
import axios from "axios";

export default tool({
  description: "run when I ask you to run search query",
  args: {
    url: tool.schema.string(),
  },
  async execute(args) {
    return `Status code: ${await axios.get(args.url).then((res) => res.status)}`;
  },
});

I would create a package.json at ~/.config/opencode/package.json and install axios (not that i recommend using axios since fetch does what I need but I just figured it makes a good example)

Using ~/.config/opencode/tool/ won’t work for my use case. I want project-specific tools so they’re wired up automatically on clone, not configured globally.

I tried .opencode/tool/, but small mistakes there crashed opencode. Instead, I followed this guide to build a stdio MCP server in TypeScript, then pointed opencode.json to node .opencode/mcp/myscript.ts. It’s a bit heavier, but flexible—I can use any language/stack, keep complexity as needed, and avoid crashes since it runs as a separate process.

Request: Can you reserve .opencode/mcp/ and ~/.config/opencode/mcp/ for storing custom local MCP server code? No code changes needed—just update the docs and reserve the path to avoid future conflicts.

@sigonzal3

@sigonzal3 this should work for any dir tho like in your project you could do:

mkdir -p .opencode/tool
cd .opencode/tool
bun init
bun i
< create your .ts or .js and import package >

And it should just work

you could also do the package.json in the .opencode/ dir

With the new update today:

❯ opencode 
Error: Config file at [redacted]/.opencode is invalid: Unexpected directory "node_modules" found in "[redacted]/.opencode". Only agent, command, mode, plugin, tool directories are allowed.

70310a3

This introduced the restriction, is there any more guidance as to do tools with dependencies?

@jfyne

@jfyne I think this was fixed on latest can you try again?

Yup all good, thanks!

Going to close since issues seem resolved and I provided guides above^^

Probably worth updating the docs too tho

also soon opencode will automatically resolve deps for u if u dont have package json

also soon opencode will automatically resolve deps for u if u dont have package json

I keep coming across quirks which, after lots of head scratching digging, end up being known issues. Would it be reasonable/viable to maintain some kind of SSoT of these "known issues" for users who aren't part of internal development?

If not, perhaps even just more strict "duplicate issue" closing, with the master issue labelled, would help everyone keep track of things?

Yeah this will be easier once I start working on opencode full time and opentui version of opencode ships (since it will resolve a lot of open issues), there are soooo many issues and it can be difficult to parse through everything between github, discord, and x.

Totally makes sense. If you ever have any problems tho feel free to drop a message in our discord, you can dm me on any platform really and I will respond

Yeah this will be easier once I start working on opencode full time and opentui version of opencode ships (since it will resolve a lot of open issues), there are soooo many issues and it can be difficult to parse through everything between github, discord, and x.

Totally makes sense. If you ever have any problems tho feel free to drop a message in our discord, you can dm me on any platform really and I will respond

Thanks! Coincidentally I DMed you on Discord before seeing this.

also soon opencode will automatically resolve deps for u if u dont have package json

Has this been implemented or is there an issue to track this?

Navigation Menu

Repository navigation

Support for using additional npm packages in custom tools #2768

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Support for using additional npm packages in custom tools #2768

Description

Activity

rekram1-node commented on Sep 25, 2025

sigonzal3 commented on Sep 25, 2025

rekram1-node commented on Sep 25, 2025

jfyne commented on Sep 26, 2025

jfyne commented on Sep 26, 2025

rekram1-node commented on Sep 26, 2025

jfyne commented on Sep 26, 2025

rekram1-node commented on Sep 26, 2025

rekram1-node commented on Sep 26, 2025

kierr commented on Oct 9, 2025

rekram1-node commented on Oct 9, 2025

kierr commented on Oct 9, 2025

c1moore commented on Mar 29, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions