FAQ
Honest answers.
The real questions — why a fork, how it stays maintained, and whether it's tested — with the real answers. Pulled from the community FAQ and kept up to date in the repo.
Models & access
Can I use free models in CyxCode?
You can use a configured provider that permits free access, subject to its limits, or a local model on your hardware. Run /connect, then /models. CyxCode does not provide a hosted free model tier of its own.
Why does OpenCode Zen reject anonymous requests?
OpenCode controls access to its hosted service. Our anonymous requests from CyxCode have been rejected. Connect with your own Zen API key to check your account's access; authenticated access to Zen's free models has not yet been verified in CyxCode. Being a fork does not grant service access.
Problem & value
Aren't these one-time errors? Missing Python, etc.
One-time setup errors aren't the point. The real ROI is recurring errors across projects and context resets — git conflicts, TypeScript/ESLint failures, Docker crashes, build errors that keep coming back. Every time a model's context resets, it forgets how to fix that ESLint rule. CyxCode remembers.
Memory tools I've tried just fill context with irrelevant tokens.
Most memory implementations dump everything in. CyxCode is built differently: small indexed files (1–5 lines), tag-based relevance matching, a hard ~500–2000 token cap per session, and access tracking that prunes unused memories after 30 days. The dream system also processes patterns and memories offline on startup — no runtime tokens.
Fork vs plugin
Why not a plugin? Will you maintain all OpenCode changes forever?
Plugins extend OpenCode; CyxCode changes the runtime, memory, governance, and product boundary. The short-circuit needs control-flow ownership to stop a known error before another LLM call. Shell mode is core behavior. Pattern learning needs message and tool internals. Recall, memory, and dream are persistent state systems. CyxWatch needs enforcement near shared process/filesystem/network wrappers so library calls can't bypass policy. When a feature can be a plugin, it should be — but these boundaries can't.
What about a pre-process wrapper instead of a fork?
A wrapper can intercept input but can't stop the LLM from being called after a tool returns an error, can't reach shell-mode's direct execution path, and can't reliably control recall, compaction, or the context assembled inside the app before a model call. It's the right shape for some things, not for these.
Why not contribute upstream?
We'd be open to it. But pattern-first interception, zero-token shell mode, and an auto-learning system are architectural changes to how the tool processes commands — not bug fixes. We're not going to push architecture upstream they didn't ask for.
Maintenance & sustainability
Maintaining an OSS fork is hard. What's the longevity plan?
Internal directory structure stays opencode intentionally so git pull upstream works without merge hell — only the CLI, TUI, config, and docs are rebranded. We maintain the CyxCode runtime surface (packages/opencode/src/cyxcode/), its tests, and docs. We don't rewrite upstream. The fork surface is intentionally small: we add, we don't rewrite.
What if I run everything in Docker and block the agent from my base machine?
Patterns match error strings, not execution contexts. If your Docker workflow produces npm ERR! 404, CyxCode matches it the same way and suggests a fix — you run it inside your container. Your sandbox controls what actually executes.
Testing & quality
Where are the tests?
Under packages/opencode/test/cyxcode/. Run them with cd packages/opencode && bun test test/cyxcode/. The suite covers routing, pattern matching, capture extraction, learned-pattern generation, memory lookup, dream consolidation, and path handling. Run focused suites in an isolated test environment; see the project notes for the current validation checkpoint.
Is it production quality?
Moving that direction. The core pattern matching and learning system is tested, and integration with OpenCode's bash tool is verified via debug mode (CYXCODE_DEBUG=true). Core stabilization is ongoing, including checks of project isolation, learning persistence, and state restoration. Consult the project notes for tested behavior and remaining work.
Still have questions?
The full FAQ lives in the repo, and the usage guide covers every command.