Use Navi with OpenCode

Navi fits OpenCode’s existing Agent Skills layout. navi install links the interop skill under .agents/skills/ and adds a project-local launcher under .agents/bin/; OpenCode already discovers project skills there. OpenCode 1.17.13’s skill scanner follows symlinks. You need macOS or Linux, Node.js 22.13 or newer, and ripgrep. Git is also required for revision-aware checks and flows that inspect a diff.

Install Navi in the project

cd /path/to/project
npm install --save-dev @machinepath/navi
npx --no-install navi-cli install

Verify the connection

./.agents/bin/navi --version
test -r .agents/skills/navi-interop/SKILL.md \
  && test -x .agents/bin/navi \
  && echo "Navi interop: ready"

Start or restart OpenCode after installing the skill. Run OpenCode from the project root or one of its subdirectories.

Configure both model connections

OpenCode and Navi make separate model calls. Authenticate OpenCode with its normal setup:

opencode auth login

Then give Navi a provider key. For example:

export DEEPSEEK_API_KEY="<your-key>"
export NAVI_MODEL="deepseek/deepseek-v4-flash"

Navi also reads these values from the project’s .env file. Keep .env ignored, never paste a credential into an OpenCode or Navi prompt, and load keys without echoing them before recording a terminal.

Ask OpenCode to consult Navi

Use OpenCode’s non-interactive run command:

opencode run \
  'Use the navi-interop skill to ask Navi: "What command runs the test suite in this repository? Cite the exact file and line." Do not modify files. Show the exact Navi command and return its cited answer.'

OpenCode loads the skill, calls the project-local .agents/bin/navi launcher, and returns Navi’s answer. If Navi asks for a deeper read, OpenCode can run the continuation command and keep the evidence in the same session.

A verified interop result

This run used OpenCode 1.17.13 and the public @machinepath/navi@0.1.0 package in a clean repository. DeepSeek was the only model provider passed to the isolated process. OpenCode loaded the skill, Navi settled the question in one pass, and Git stayed clean.

$ opencode --version
1.17.13
$ node -p "<installed package name and version>"
@machinepath/navi@0.1.0
$ ./.agents/bin/navi --version
navi 0.1.0
git status before: clean

→ Skill "navi-interop"

$ <project>/.agents/bin/navi "What command runs the test suite in this repository? Cite the exact file and line." -w <project>
navi: scanned the repo — 3 hits across 2 files (<timing>)
navi: quick pass — answering from what I found (I'll grade my own answer below)
**Answer:**
The command `npm test` runs the test suite, which executes the script
`node --test` as defined in the repository’s `package.json`.

**Sources**
- `package.json:9-11` — The `"scripts"` block contains `"test": "node --test"`.
- `README.md:3` — "Run the test suite with `npm test`."

**Confidence:** High

── grounding check ───────────────────────────────────────────
VERDICT: COMPLETE
WEAK/MISSING: None
ESCALATE: no

── next ──────────────────────────────────────────────────────
✓ Grounding grade passed — the answer stands.

OpenCode exit: 0
git status after: clean
git status unchanged: yes

The terminal was captured with /usr/bin/script. Normalization removed terminal control bytes, replaced the temporary repository path with <project>, and replaced the elapsed milliseconds with <timing>; it did not change model wording. Read the complete normalized recording.

Use the OpenCode TUI

Start OpenCode from the project:

opencode

Then ask:

Use the navi-interop skill to ask Navi where this repository configures retries.
Cite the exact file and line. Do not modify files.

If OpenCode does not call Navi

Restart OpenCode after navi install.
Run ./.agents/bin/navi --version to verify the project launcher.
Check that your OpenCode permissions allow both the skill and bash tools.
Keep OpenCode authentication and Navi’s provider key separate.

See Connect your coding agent for installation ownership and removal, or Troubleshooting for Navi runtime failures.

Get started

Use Navi

Customize

Reference

Help

Use Navi with OpenCode

A verified interop result

Use the OpenCode TUI

If OpenCode does not call Navi

​A verified interop result

​Use the OpenCode TUI

​If OpenCode does not call Navi

A verified interop result

Use the OpenCode TUI

If OpenCode does not call Navi