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.
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. The pentest module alone has 232+ passing tests.
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). A few regex-escaping edge cases remain skipped.
Still have questions?
The full FAQ lives in the repo, and the usage guide covers every command.