Skip to content
Hands-on Coding Assistants

Part 1 — Start from a Repository Chapter 2

Setup & Practical Integration

In this chapter

Start with a known project

From the root of your Task API fork, check Git and Node, then install the CLI used in the exercises.

git --version
node --version
npm install -g @opencode/cli@2.3.2
opencode --version
npm test

Expect Node 24 or later, OpenCode v2.3.2, and three passing tests. If your shell finds OpenCode 1, use the installation instructions for your platform and check which binary your shell is running before continuing. The two releases share the command name.

Choose between a local and a hosted model

When OpenCode reads a file, it can send the contents and tool output with its next model request. Ollama can serve downloaded weights on your machine. A hosted provider does the processing remotely. Use the lab’s fictional data on the hosted path and check the provider’s terms and limits. Pick one path and verify it with the same exercise below.

Run a local model with Ollama

Install Ollama for your operating system. The examples use Ollama 0.40.16. The qwen3.5:9b catalog entry lists tool support. Check the exact download size for your variant and whether it fits your machine first. Running the model also needs memory for its working state and context.

Set the context to 65536 in the Ollama app, or start the CLI server with that setting. The environment variable must be present when the server starts. If Ollama already owns the port, use its app settings or restart that server before starting another one. Ollama’s integration guide recommends 64k or more for local models in OpenCode.

The following command starts the Ollama server with a context length of 65536. Run it in a terminal separate from the lab.

OLLAMA_CONTEXT_LENGTH=65536 ollama serve

In a second terminal, download the model we’ll use for the exercises, confirm it is installed, then start OpenCode from the lab folder.

ollama pull qwen3.5:9b
ollama list
opencode

On the OpenCode interface, open the models selection by running the command /models and select ollama/qwen3.5:9b. OpenCode discovers models at Ollama’s default local address. If the model is missing, check ollama list and the port before changing the prompt. After the first model request, run ollama ps in your terminal to inspect the allocated context and where the model is running. If it is slow or the machine runs out of memory, choose a smaller tool-capable model and run the same checks, or continue with the hosted option. We’ll talk about the hosted model following.

Run a free hosted model

Run opencode in the lab, open /models and select a free, tool-capable model from the catalog. As of November 20, 2026, the free list includes opencode/deepseek-v4.1-flash-free, which is an excellent choice. The free Console entries work through OpenCode. Availability and quotas can change. If the model is missing or the first call is rejected, check the Console model catalog for another free entry. The model appendix gives a separate provider option that requires its own key.

You can also check model IDs from a shell with opencode models. Record the ID you actually select.

Check file and shell tools

Now we can start the lab exercises. The first exercise checks that the model can read a file and run a shell command. It also verifies that the model is using the same tool version as your own terminal. The exercise uses the package.json file and the npm test command.

In the lab folder, open opencode and run the command /agents. Select Plan, and give it this request.

Read package.json and report the test script exactly as written.
Run npm test as a single shell command. Read the tool result and report
the number of passing tests and the exit status. Leave files unchanged.

Look for a completed read of package.json and a completed shell call for npm test. The starter’s script is node --test test/*.test.ts. Expect three passing tests and exit zero. Run git status --short in your own terminal and check that the tree is clean.

If the model only describes the command, the shell check is still open. If it appends a command such as echo $?, retry with the exact allowlisted command. A permission denial and a failing test leave different tool events. If the model repeatedly skips a tool after a clean retry, verify another model before continuing.

Check an edit in a separate worktree

From the root of the lab, start a disposable checkout of lab-start.

git worktree add --detach ../task-api-setup-check lab-start
cd ../task-api-setup-check
opencode

Select the same model and switch to Build.

Append one line containing "Setup edit check." to README.md.
Use the file editing tool. Leave the other files alone.

Exit the session. Inspect the actual diff and restore the known scratch change.

git status --short
git diff -- README.md
git restore -- README.md
git status --short
cd -
git worktree remove ../task-api-setup-check

Run the restore and worktree removal only after checking the diff. The exercise should add one line to README.md and touch no other tracked file. Record the model, version and three observations. You’ll use the same working model to the chapter explore the application.

Read the permission prompts

The starter allows exact test commands and asks about other shell commands. Review the command and its working directory when OpenCode asks. You can check unfamiliar commands yourself from a separate terminal.

With all the checks complete, you can continue to the next chapter. The exercises will use the same model and tool versions you just verified.

References