# vibe-local wraps Ollama and OpenCode into an offline workshop setup > vibe-local is a shell-based installer and launcher that pairs a local Ollama model with the OpenCode terminal agent so a class of students can practise agent coding without network access or paid plans. Its centre of gravity is the classroom: a teacher can serve the model on one Mac and students attach to it, and the scripts for Windows and macOS are shipped alongside the shell one. **ochyai/vibe-local** — Free AI coding environment: Ollama + Python - Repository: https://github.com/ochyai/vibe-local - Stars: 801 · Forks: 97 - Language: Python - License: MIT - Published: 2026-10-20 · Updated: 2026-10-20 · Language: en - Canonical page: https://hysenlabs.com/projects/ochyai-vibe-local ## The install is one curl command and a launcher on PATH The whole setup is documented in three steps for an audience that may never have used a terminal. Open Terminal, which on macOS means Spotlight with `Cmd+Space` and a search for Terminal. Then paste a single command: ```bash curl -fsSL https://raw.githubusercontent.com/ochyai/vibe-local/main/install.sh | bash ``` Finally, open a new terminal and run: ```bash vibe-local ``` The repository ships the scripts for more than one platform rather than assuming macOS and a POSIX shell. At the top level there are install.sh, install.cmd and install.ps1 for the three install paths, and matching vibe-local.sh, vibe-local.cmd and vibe-local.ps1 launchers. So the Windows path exists in both PowerShell and command prompt form, even though the README text is written for the Mac. The last push was on 2026-07-19 and the repository is MIT licensed. There are tagged releases, and the most recent are v1.3.2, v1.3.1 and v1.2.0, all published in February 2026, with the release names pointing at a scroll region fix, a PowerShell fix, type-ahead input and UX work. A note on the version numbers: the README describes a v2.2 release dated 2026-07 and a v2 release, while the GitHub release tags stop at 1.3.2. Those are two different numbering schemes living side by side in the same repository, and that is worth clarifying before you file an issue about a mismatch. ## The router sends small talk to a small model and coding to a big one The feature that distinguishes this from a plain Ollama plus terminal agent setup is automatic model routing, added in v2.2. The description is specific. Casual conversation and short questions are answered immediately by a small model, with the Japanese section reporting a measured change from about 30 seconds to about 3 seconds for a greeting. Coding and tool use go to a larger model. A very small path-based router, named `vibe-router`, looks at the content and decides. It can be turned off with `--no-router`. The default model display in the TUI is `vibe-auto`, meaning automatic. To pin a specific model you use `/models` inside the TUI or pass `--no-router`. Two other changes in that release are worth noticing because they address real failure modes. The first fixes small models blocking the queue by thinking for tens of seconds every time they generate a title, which the description attributes to a fix that injects thinking off and moves the operation from 15 to 29 seconds down to 0.2 seconds. The second is prompt slimming, where external imports such as Claude Code skills are blocked so the system prompt drops from 69KB to about 30KB, roughly doubling the first response time. There is also a dedicated UI binary, `vibe-tui`, generated on first launch and regenerated automatically when the engine updates, and a `--fast` mode that makes a small model the main driver. ## The classroom mode is the reason this project exists The stated purpose is narrower than an AI coding tool. The README describes it as a non-profit research and education utility, built for offline workshops where instructors support learners with AI agents, for students without paid plans who want to practise agent coding, and for beginners learning terminal operations through natural language. The same description appears in Japanese, English and Chinese. The classroom mode is experimental, and it works like this: the teacher's Mac runs the model and serves it, and students attach to that address. ```bash vibe-local --serve vibe-local --attach http://192.168.x.x:4096 ``` That is the whole multi-machine story, and it is genuinely useful in a room with poor or absent internet. One machine holds the model in memory and the others borrow it over the local network. The port in the example is 4096, and it is a plain HTTP address on the local network, which is the detail to think about before using it anywhere that is not a classroom. A separate experimental piece of the v2 release is the built-in Python engine `vibe-coder.py`, which the launcher can use directly with RAG and an XML fallback for tool calls: ```bash vibe-local --vibe-coder vibe-local --vibe-coder --rag --rag-path . ``` Earlier versions of the project also removed a self-written proxy once Ollama implemented the Anthropic Messages API natively in v0.14 and later, which the README describes as eliminating about 2000 lines of fragile code. ## Model choice is decided by RAM, and the table is explicit about it The supported environments table lists a model per memory band, which is the most immediately actionable part of the documentation. On an Apple Silicon Mac from M1 onwards, 80GB or more is paired with qwen3-coder-next at 52GB with 256K context. 32GB or more is paired with qwen3.6:35b-a3b at 24GB, and that row is marked as recommended. 16GB is paired with gpt-oss:20b at 14GB, described as practical enough. 8GB is paired with qwen3.5:4b as the minimum that runs at all. On an Intel Mac or Linux, 16GB or more with gpt-oss:20b is described as working but slow. The model list in the v2 release notes covers the 2026 generation: qwen3.6, gpt-oss, qwen3-coder-next and qwen3.5. Two adjustments happen automatically. The context length is managed for you: alias models named `vibe-coder` and `vibe-fast` are generated with a `num_ctx` baked in according to available RAM, which the notes give as the way to stop a low-memory machine from being overwhelmed. And the model is prefetched in the background at startup, with a residency of two hours, so the first response is faster. You can pin a model yourself with `--model`, and the diagnostics flag `vibe-local --doctor` reports on the environment, including the model names matching your RAM band. ## The safety guidance is written for beginners, and it is worth reading Because the intended user is a beginner, the documentation spends real effort on what to do when the agent wants to run something. The easy Japanese section makes the point that the AI is not perfect and will run wrong commands, that in normal use it asks for permission before doing something, and that when you do not understand a command you should decline. It then names three dangerous patterns in a table: a command beginning with `sudo`, because that changes important system settings, a command containing `chmod`, because it removes file protections, and a long command whose meaning you do not understand. The recommended habits follow from that. Approve nothing you cannot read, do not use the tool in a folder holding important files, and press `Ctrl+C` to stop it when you are stuck. This is more concrete than most AI coding tool documentation, and it is honest about the residual risk. The agent still runs terminal commands on the learner's machine, so the mitigation is attention rather than isolation. There is also a diagnostic command for the setup itself, `vibe-local --doctor`, and a troubleshooting section covering Ollama not starting, the model not being found, and opencode not being installed, each with the shell command that fixes it. ## Ollama, OpenCode and the model weights are the real dependencies The README describes the stack as Ollama plus a local LLM plus the OpenCode TUI, and the troubleshooting section names the concrete pieces you need present. If Ollama will not start, the fix differs by platform: `open -a Ollama` on macOS, or `ollama serve` on Linux. If the model is not found, the model name for your RAM band can be confirmed with `vibe-local --doctor` and pulled with `ollama pull` for the named tag. If opencode is missing, the fix given is `brew install opencode`. The reason OpenCode sits in the middle is visible in the v2 notes. The TUI was rebuilt on the OpenCode engine, described as a multi-provider terminal AI agent under the MIT licence, offering Plan and Build modes, themes and LSP integration. A `--classic` flag keeps the older behaviour where the Claude Code CLI provides the UI, connected directly with no proxy. The offline premise has a limit worth naming. Even with a local model, the tool talks to Ollama on the same machine, and the `--auto` mode explicitly checks the network to decide between Claude Code and the local path. The claim is that the model runs locally, not that the tool never opens a socket. For anyone weighing this against a hosted assistant, the comparison is straightforward: a hosted API needs a subscription and connectivity, while this needs roughly 8GB to 80GB of RAM and a downloaded model. For a classroom with unreliable internet and students without paid plans, that trade favours the local setup. ## Conclusion Adopt vibe-local if you teach or self-study agent coding on machines without a reliable network or a paid model subscription, since it installs a local model and drives the OpenCode TUI entirely offline. Skip it if you already have hosted API access, because the auto mode will simply use Claude Code when the network is up, and the value here is the offline path. Verify first that your machine has Ollama available and enough RAM for one of the listed models, that the listed version 1.3.2 matches what you are getting, and that the safety behaviour you rely on is in place, since the guide asks learners to decline commands they do not understand. ## FAQ ### How do I install vibe-local on my Mac? Open Terminal and run `curl -fsSL https://raw.githubusercontent.com/ochyai/vibe-local/main/install.sh | bash`, then open a new terminal and run `vibe-local`. The repository also ships install.cmd and install.ps1 for Windows and vibe-local.sh, vibe-local.cmd and vibe-local.ps1 launchers. ### Does vibe-local work without an internet connection? Yes. It runs a local model through Ollama and drives the OpenCode TUI with it, so no network is required for the local path. The `--auto` flag does check the network and will use Claude Code instead when it is online. ### What do the --serve and --attach flags do? They implement the experimental classroom mode. `vibe-local --serve` runs the model and serves it on the teacher's Mac, and students connect with `vibe-local --attach http://192.168.x.x:4096`. ### Which model should I use for my machine? The README lists a model per memory band: qwen3-coder-next at 52GB for 80GB of RAM or more, qwen3.6:35b-a3b at 24GB for 32GB or more as the recommended option, gpt-oss:20b at 14GB for 16GB, and qwen3.5:4b as the 8GB minimum. `vibe-local --doctor` reports which model names match your RAM band. ## Sources - [Issues](https://github.com/ochyai/vibe-local/issues) - [License: MIT](https://github.com/ochyai/vibe-local/blob/main/LICENSE) - [ochyai/vibe-local on GitHub](https://github.com/ochyai/vibe-local) - [README](https://github.com/ochyai/vibe-local/blob/main/README.md) - [Releases](https://github.com/ochyai/vibe-local/releases) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/ochyai-vibe-local