Stop Treating AI Like Autocomplete: 5 Game-Changing Lessons from the OpenCode / Crush Revolution

Introduction: The Shift from Prompting to Partnering

The "one-shot" prompt is a gamble that senior engineers are tired of losing. We have all been there: you feed a complex requirement into a chat box, cross your fingers, and receive a shallow code snippet that ignores your project's architectural nuances. Treating AI like a glorified autocomplete tool is a recipe for context loss and technical debt.

The industry is moving toward Agentic Coding. This is not about passive text generation; it is a collaborative partnership where the developer guides, constrains, and questions an agent to ensure work remains grounded in real project needs. Two open-source projects define this space: OpenCode (opencode-ai/opencode, 12.8k stars) and its active successor Crush (charmbracelet/crush, 25k stars, v0.75.0). OpenCode pioneered the architecture; Crush, developed by the Charm team, carries it forward with 3,400+ commits, 124 branches, and an active community. By prioritizing transparency over "black box" automation, both offer an alternative to closed ecosystems, giving teams total control over their development environment and data.

The agentic coding architecture: from developer through Plan/Build agents and persistent context files, through the permission system and @ reference grounding, to 75+ cloud and local model providers. OpenCode (archived Sep 2025) laid the foundation; Crush (charmbracelet/crush) continues development.

Takeaway 1: The Power of "Plan" Before "Build"

Senior developers know that writing code is the last step of the process, not the first. Both OpenCode and Crush enforce this discipline by separating roles into two primary agent modes: Plan and Build.

The Build agent has full tool access for implementation. The Plan agent is a restricted mode designed for analysis-first workflows: file edits and shell commands are gated by the permission system. This is not just a safety feature -- it is a mechanism to enforce a disciplined sequence. It forces the model to reason through architectural roadmaps before it has the right to touch a single line of code. For even more surgical tasks, specialized subagents can handle multi-step research or fast, read-only codebase interrogation.

"The two built-in primary agents are Build, which has all tools enabled and is the standard mode for writing code, and Plan, a restricted mode where edits and shell commands are gated by the permission system so the model can analyze and propose changes without altering anything." -- OpenCode documentation

Takeaway 2: AGENTS.md / CLAUDE.md -- The Persistent Project Brain

A standard AI chat window is ephemeral; it forgets your conventions the moment you close the tab. Agentic coding solves this with initialization commands. Crucially, this is not git init. While Git tracks your history, init builds your agent's brain.

When you run the init command, the tool performs a deep scan of your directory. It leverages LSP (Language Server Protocol) and tools like Pyright to understand your code at a structural level. The output is a persistent context file -- AGENTS.md (OpenCode) or CLAUDE.md (Crush). This file captures frameworks, directory structures, and strict coding conventions (e.g., "Always use UUIDs for primary keys"). This serves as a "stable baseline," ensuring that every future session is grounded in the "why" of your project, effectively killing the hallucinations common in generic tools.

"Initialize first, then ask questions, then plan, and only after that begin editing." -- OpenCode documentation

Takeaway 3: Absolute Sovereignty via the Permission System

Trust in an autonomous agent must be earned through granular control. Agentic coding tools provide this sovereignty via configuration files (opencode.json for OpenCode, .crush.yaml or project configuration for Crush). Actions are governed by three levels: Allow (auto-run), Ask (prompt for approval), and Deny (blocked).

A critical technical detail is the order of precedence: the last matching rule wins. This allows you to set a restrictive catch-all (like "*": "ask") and then selectively allow trusted tools like ls or grep. For privacy-minded teams, access to .env files is explicitly denied by default. This human-in-the-loop system transforms the agent from a loose cannon into a precise, supervised tool.

Takeaway 4: Breaking the Vendor Lock-In Cycle

Most AI tools try to lock you into a single ecosystem. OpenCode and Crush break this cycle by supporting over 75 providers. You can deploy cloud leaders like OpenAI and Anthropic, or run local models via Ollama or LM Studio for total offline sovereignty.

The strategic win is the separation of the "workflow layer" (the agent framework) from the "configurable backend" (the model). Furthermore, privacy is a first-class concern: unlike proprietary platforms, agentic coding tools do not store code or context data on external servers. This is a massive advantage for enterprise teams operating under strict compliance or security requirements, where data exfiltration is a non-starter.

Takeaway 5: Surgical Precision with Fuzzy Search and @ References

Dumping an entire codebase into a prompt is a waste of tokens and a recipe for disaster. Both tools use the @ symbol for fuzzy file search, allowing you to ground prompts in specific source files.

Beyond lowering token costs, this "surgical" approach allows the agent to identify negative information. Knowing what is not in the project -- such as the absence of a service layer or a REST API -- is as valuable as knowing what exists. By referencing @accounts/views.py, you force the agent to reason from the actual source, proving what exists and what does not before it attempts to generate a single character.

"Crush can also guide you through implementation decisions instead of only generating code in one shot. That interactive style is one of the reasons it works well in real projects." -- Crush documentation

Conclusion: The Future of Controlled Automation

Deploying agentic coding marks a transition from "passive read" development to a "workshop mindset." It does not replace the need for engineering judgment; rather, it provides a credible and flexible foundation for it. By enforcing disciplined planning, persistent context, and sovereign permissions, you move from being a "prompter" to an architect of automated workflows.

The lineage from OpenCode to Crush shows the direction the industry is heading: open-source, privacy-first, multi-provider agentic coding tools that put the developer in control. Whether you use the original OpenCode (now archived but still a reference implementation) or its actively developed successor Crush (25k stars, v0.75.0, 3,400+ commits), the architectural principles are the same.

Final Thought: If your AI agent could only see what was in your AGENTS.md or CLAUDE.md file right now, would it actually understand the "why" behind your architecture, or is it just guessing at the "how"?