> ## Documentation Index
> Fetch the complete documentation index at: https://machine-path.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Use Navi with OpenCode

> Let OpenCode call Navi for a cited repository answer without modifying the repository.

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](https://opencode.ai/docs/skills)
there. OpenCode 1.17.13's
[skill scanner follows symlinks](https://github.com/anomalyco/opencode/blob/v1.17.13/packages/opencode/src/skill/index.ts#L131-L145).

You need macOS or Linux, Node.js 22.13 or newer, and
[ripgrep](https://github.com/BurntSushi/ripgrep). Git is also required for
revision-aware checks and flows that inspect a diff.

<Steps>
  <Step title="Install Navi in the project">
    ```bash theme={null}
    cd /path/to/project
    npm install --save-dev @machinepath/navi
    npx --no-install navi-cli install
    ```
  </Step>

  <Step title="Verify the connection">
    ```bash theme={null}
    ./.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.
  </Step>

  <Step title="Configure both model connections">
    OpenCode and Navi make separate model calls. Authenticate OpenCode with its
    normal setup:

    ```bash theme={null}
    opencode auth login
    ```

    Then give Navi a provider key. For example:

    ```bash theme={null}
    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.
  </Step>

  <Step title="Ask OpenCode to consult Navi">
    Use OpenCode's [non-interactive `run` command](https://opencode.ai/docs/cli):

    ```bash theme={null}
    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.
  </Step>
</Steps>

## 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.

```console theme={null}
$ 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
```

```console theme={null}
→ Skill "navi-interop"
```

```console theme={null}
$ <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.
```

```console theme={null}
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](https://github.com/machinepathindustries/navi/blob/main/docs/mintlify/recordings/opencode-1.17.13-navi-0.1.0.txt).

## Use the OpenCode TUI

Start OpenCode from the project:

```bash theme={null}
opencode
```

Then ask:

```text theme={null}
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](/connect-your-agent) for installation ownership
and removal, or [Troubleshooting](/troubleshooting) for Navi runtime failures.