CyxCode

We automate the AI that automates us.

Website: code3hr.github.io/cyxcode

Sponsor: github.com/sponsors/CYXWIZ-Lab

136 built-in error patterns. Community packs and learned patterns extend coverage.

• What is CyxCode?
• Install
• Quick Start
• Providers and Free Models
  • Testing Other Models, Including Muse
• Two Modes
• ACP Editor Integration
• Pattern Learning
• Project Memory
• Semantic Recall
• Dream Consolidation
• Behavior Versioning
• Supported Categories
• Environment Variables
• Positioning
• Why Fork?
• Docs & User Guide
• Roadmap

CyxCode is a fork of OpenCode that intercepts known errors before the LLM sees them. 136 built-in regex patterns match common errors instantly, and community packs plus learned patterns extend coverage.

Traditional AI:  Every error -> LLM -> tokens burned -> response
CyxCode:         Every error -> Pattern check -> match? -> FREE fix
                                               -> no match? -> AI learns it

When no pattern matches, the AI handles it normally — but CyxCode captures the error + fix and generates a new pattern. Next time, that error is free. The pattern library grows automatically.

Grab a prebuilt binary — Linux, macOS, or Windows (via WSL/Git Bash):

curl -fsSL https://raw.githubusercontent.com/code3hr/cyxcode/HEAD/install | bash

Latest release: v3.0.1

Pin a specific version:

curl -fsSL https://raw.githubusercontent.com/code3hr/cyxcode/HEAD/install | bash -s -- --version 3.0.1

The installer drops the cyxcode binary into ~/.opencode/bin and adds it to PATH. Releases live at github.com/code3hr/cyxcode/releases. Sponsor the project at github.com/sponsors/CYXWIZ-Lab.

Inside CyxCode, /update checks the latest GitHub release and runs the installer for you.

One-time manual step for v2.2.x, v2.3.0, and v2.3.1 installs: those builds had a broken upgrade URL baked in (pointed at a domain that was never registered / wrong branch). Run the curl | bash install above once to land on v2.3.2+, and auto-upgrades will work from then on.

git clone https://github.com/code3hr/cyxcode.git
cd cyxcode
bun install
export ANTHROPIC_API_KEY=sk-ant-...   # or OPENAI_API_KEY
bun run dev

For CPUs without AVX2, see AVX2 Note.

Run /connect in CyxCode to connect a provider, then /models to select a model. You can also manage connections from the terminal with cyxcode providers login and cyxcode providers list.

OpenCode Zen requires your own API key in CyxCode. Its anonymous free tier can reject requests with:

OpenCode's free tier can only be used from within OpenCode.

CyxCode is a fork of OpenCode, but access to OpenCode's hosted model service is controlled by that service. CyxCode no longer automatically connects to Zen using the anonymous public key. Without a Zen API key, its models—including Big Pickle—do not appear as available choices in /models. If no provider is connected, CyxCode prompts you to connect one.

CyxCode previously relied on anonymous Zen access. That access used to work, but our latest request was rejected by OpenCode's servers with the message above. Forking the client does not automatically grant access to the hosted free tier.

To connect Zen and check whether its free models are available to your account:

1. Sign in to OpenCode Zen and obtain your own API key. Review its account and billing requirements before proceeding.
2. In CyxCode, run /connect, select OpenCode Zen, and enter the key in the connection prompt.
3. Run /models and select a model currently listed as free by Zen.
4. Send a short message to verify access. A model appearing in the list does not guarantee the service will accept the request.

An API key makes the provider available in CyxCode; access to individual models, including free models, still depends on the service's rules. Authenticated access to Zen's free models from CyxCode has not yet been verified. If the service still rejects the request, use another connected provider or a local model. See the Zen documentation for current model availability, account requirements, and pricing.

Free models remain supported through other configured providers that permit access, subject to their usage limits. You can also configure local models through an OpenAI-compatible endpoint such as Ollama, using your own hardware. CyxCode's local pattern matching continues to work without a model API call.

Connect the provider that hosts the model, then select it with /models. Hosted providers may require credentials and charge for usage; connecting one provider does not grant access to another.

For Meta Muse Spark through OpenRouter:

1. Obtain an OpenRouter API key and check the model's availability and pricing on the Muse Spark 1.3 page.

2. In CyxCode, run /connect, select OpenRouter, and enter your key in the connection prompt.

3. Run /models and search for Muse. The OpenRouter model ID is meta/muse-spark-1.3.

4. If the model is missing, refresh the catalog from a terminal, then restart CyxCode:

   cyxcode models --refresh

5. Select the model and send: Reply with "Muse connected." Do not use tools or modify files.

6. Once that succeeds, test a read-only task such as: Read README.md and summarize this project. Do not edit files.

A catalog refresh can expose newly listed models; it does not grant account access. If Muse is still absent, a custom provider/model entry is needed.

Direct Meta access is another option: configure a provider with the @ai-sdk/openai adapter, base URL https://api.meta.ai/v1, and model ID muse-spark-1.3, then connect it using a Meta Model API key. Meta's coding-agent setup guide provides the configuration, including reasoning options and model limits. API use is usage-billed; Muse is not automatically free in CyxCode.

Live Muse inference has not yet been verified in CyxCode. Test a short response first; a successful listing or connection alone does not verify generation or multi-step tool use.

CyxCode can derive model variants from catalog reasoning_options metadata for supported adapters. A model configuration can also declare the controls explicitly, for example:

{
  "reasoning_options": [{ "type": "effort", "values": [null, "low", "high"] }]
}

null represents the none effort. Supported adapters expose only values accepted by their installed SDK. An empty array disables automatically generated variants; explicit variants settings still apply, including disabled: true. Missing metadata keeps the existing model-specific defaults. Aliases inherit catalog metadata when they use the same adapter.

Token-budget metadata uses { "type": "budget_tokens", "min": 2048, "max": 8192 } and produces high and max choices within the model and CyxCode output limits. Cohere also supports { "type": "toggle" }. Adapter coverage and remaining work are recorded in the upstream audit.

For an OpenAI-compatible provider that expects reasoning history in a specific message field, set interleaved on the model in opencode.json. For example, under provider.custom.models.my-model:

{
  "interleaved": "reasoning_text"
}

The equivalent object form is { "interleaved": { "field": "reasoning_text" } }. Existing fields such as reasoning_content and custom field names are supported. Use the field required by your provider. Omitting this setting preserves the catalog value; false disables CyxCode's field remapping. This controls outgoing history replay and does not add support for parsing new fields in provider responses.

For a remote MCP server, set oauth.callbackPort in your opencode.json when the default port 19876 is occupied or your OAuth application requires a different port:

{
  "mcp": {
    "example": {
      "type": "remote",
      "url": "https://mcp.example.com/mcp",
      "oauth": {
        "callbackPort": 24567
      }
    }
  }
}

Run cyxcode mcp auth example to authorize, or cyxcode mcp debug example to inspect OAuth discovery. Both use the configured port. If you use a pre-registered OAuth client, register the matching redirect URL: http://127.0.0.1:24567/mcp/oauth/callback.

Ports must be integers from 1 to 65535. The listener binds only to 127.0.0.1; different MCP servers can use different ports concurrently. If another process owns the port, stop that process or choose another port and update the registered redirect URL. Changing ports may require running cyxcode mcp auth example again to register a new OAuth client.

Start cyxcode acp from an editor that supports Agent Client Protocol. Connect your model provider through CyxCode's /connect first.

ACP clients that support configuration options can select Model, Session Mode, and Effort. Effort appears only for models with reasoning variants; Default clears the explicit effort override. Selecting the same model keeps your effort choice, while switching models resets it. Older model/mode selectors remain supported.

Model, mode, and effort selections are saved immediately, including choices made before sending a prompt. Loading, resuming, or forking restores saved choices after checking that they are still available; older sessions fall back to message history. Sending a prompt updates the saved choices to match the model and agent actually used. See the ACP implementation guide for protocol details.

ACP output includes stable message identifiers during streaming and history replay. Compatible editors can use these identifiers to keep separate reasoning blocks from being merged together.

Run /cyxinit inside CyxCode to initialize your project:

/cyxinit

This creates .cyxcode/ with:

• Slash commands: bundled command files plus built-ins like /cyxinit and /update
• Directory structure: history/, memory/, patterns/, wiki/, codegraph/, agent/, and command/
• Config: project type detection, gitignore entries, and migration metadata

Or use the CLI: cyxcode init (same result, runs outside TUI).

!python3 -c 'import flask'
  -> Runs directly (no AI)
  -> CyxCode matches pattern
  -> Fix displayed instantly
  -> Tokens: ZERO

python3 -c 'import flask'
  -> AI thinks "let me run this" (LLM Call #1)
  -> CyxCode matches -> LLM Call #2 SKIPPED
  -> Tokens saved: ~800-1600 per error

CyxCode short-circuits when a known error pattern matches, so the fix is shown without spending another LLM call. You can turn this off when you want the AI to inspect the failure itself.

Per turn, say it naturally:

please no pattern matching for this run
skip cyxcode recovery now
turn off short-circuit behavior

Environment controls:

When CyxCode misses a pattern, the AI handles it. But CyxCode learns from that interaction:

1. AI handles the error (costs tokens once)
2. CyxCode captures the error output + AI's fix
3. Generates a regex pattern automatically
4. Saves to .cyxcode/patterns/learned.json as pending, with .opencode/cyxcode-learned.json still supported as the legacy path
5. Run /learn-patterns to review and approve

Run /learn-patterns to review pending patterns. Each shows the error, generated regex, fix, and source command. Approve to activate, reject to discard, or skip for later.

The screenshot shows a bun 404 error being caught by a learned pattern. This error was handled by the AI the first time (costing tokens). CyxCode captured it, generated a pattern, and after approval via /learn-patterns, it now matches automatically — the AI is short-circuited and the fix is displayed directly. 6. Next time same error occurs -> zero tokens

Every AI-handled error becomes an investment — that error never costs tokens again.

The AI forgets everything between sessions. CyxCode fixes that with indexed project memory — small files that load selectively based on what you're working on.

Run /remember to save project knowledge. The AI detects duplicates, extracts tags, and stores compact 1-5 line memories in .cyxcode/memory/ or the legacy .opencode/memory/ path. Each memory has tags for relevance matching.

Session 1: /remember "auth.ts uses JWT with bcrypt, middleware at line 50"
           -> Saved to .cyxcode/memory/auth-jwt-bcrypt-middleware.md
           -> Tagged: [auth, jwt, bcrypt, middleware]

Session 2: "what does auth.ts do?"
           -> Memory auto-loaded (keyword "auth" matches tag)
           -> AI already knows: "JWT with bcrypt, line 50"
           -> Skips reading the file -> tokens saved

Memories are also captured automatically when sessions compact. The compaction summary's "Discoveries" and "Relevant files" sections become indexed memories.

When regex patterns miss, recall finds what you've seen before — semantically, locally, still free.

Pattern matching catches 80% of known errors for free. The other 20% used to fall through to the LLM and evaporate at session end. Recall is a passive semantic index over everything CyxCode already captures — project memories and learned patterns — so similar prior errors surface automatically on pattern miss.

Shell error -> 136 built-in regex patterns checked (free, <1 ms)
               |
               +-- HIT  -> apply fix, done
               |
               +-- MISS -> Recall.similar(error.tail)          <-- THIS LAYER
                            |
                            +-- local embedding (~20 ms warm)
                            +-- dot-product scan over SQLite   (~1 ms / 1k rows)
                            |
                            +-- hit  -> "[CyxCode] similar prior errors: ..."
                            |           injected into LLM context -- zero API calls
                            |
                            +-- none -> fall through to LLM as before

• Local MiniLM embeddings. A 25 MB model runs on your CPU via WebAssembly — @xenova/transformers v2.17.2, cached once at ~/.cyxcode/models/. No network, no API key, no cloud, no tokens spent on retrieval.
• Separate SQLite database. Lives at .cyxcode/recall.db, independently prunable. Float32 vectors stored as raw BLOBs for bit-exact round-trip.
• Bus-event-driven. Subscribes to SessionCompaction.Compacted, PatternLearned, and MemoryLoaded. Zero edits to memory.ts, learned.ts, or the skills themselves.
• Temporal fact store. Alongside vector search, recall keeps a (subject, predicate, object, valid_from, valid_until) triple store so stale facts retire automatically.
• Reversible. Delete packages/opencode/src/cyxcode/recall/ and revert three files — CyxCode runs exactly as before.

Every token you spend on a novel error becomes a free hint for every similar future error — without writing a regex for it.

See docs/RECALL.md for use cases, architecture, API, and design rationale.

CyxCode accumulates state over time — memories, patterns, stats. /dream cleans it up, like sleep for AI.

• Deduplicates learned patterns (removed 2→1 duplicate on first run)
• Merges overlapping memories
• Validates file existence and regex
• Persists router stats to .opencode/cyxcode-stats.json

• All auto-dream phases plus smart merging
• Updates AGENTS.md with learnings from patterns and memories
• Reports: matches, misses, hit rate, tokens saved, sessions tracked

Track every pattern match, correction, and drift event. Generate token savings reports.

# Show recent audit events
cyxcode audit --last 1d

# Filter by event type
cyxcode audit --type cyxcode.pattern.match

# Generate token savings report (default: last 7 days)
cyxcode report

# Different time periods
cyxcode report --period 30d

# Different output formats
cyxcode report --format json
cyxcode report --format markdown
cyxcode report --format text

+-------------------------------------------------------------+
|        CyxCode Token Report: 03-21 to 03-28                 |
+-------------------------------------------------------------+
|                                                             |
|  TOKEN SAVINGS                                              |
|  +-- Saved:     187,200 tokens ($0.37)                     |
|  +-- Used:       48,600 tokens ($0.10)                     |
|  +-- Efficiency: 79.4%                                      |
|                                                             |
|  PATTERNS                    CORRECTIONS                    |
|  +-- Matches: 847            +-- Added:    12               |
|  +-- Misses:  203            +-- Promoted: 4                |
|  +-- Hit Rate: 80.7%         +-- Drift:    7                |
|  +-- Learned: 12             +-- Compliance: 94%            |
|                                                             |
+-------------------------------------------------------------+

All audit entries are automatically scrubbed of secrets:

• API keys (OpenAI, Anthropic, AWS, GitHub)
• JWTs and bearer tokens
• URL credentials
• High-entropy hex strings

Git for AI state — no other AI coding tool has this.

AI forgets after compaction. Corrections are temporary. The same reminder gets repeated 5 times across sessions. CyxCode is building a behavior versioning system that tracks AI state the way git tracks code.

Session 1:  "Use /commit skill"      -> AI follows
Session 5:  Context compacted         -> Instruction lost
Session 6:  AI uses raw git           -> User corrects again
Session 10: Same correction, 5th time -> User frustrated

User corrects AI -> strength: 1
Corrects again   -> strength: 2
Third time       -> strength: 3 -> AUTO-PROMOTED to system prompt
/dream runs      -> Adds to AGENTS.md permanently
                 -> AI never forgets this again

We researched every major AI coding tool. None have behavior versioning:

What existing tools do:

• OpenCode snapshots track files, not what the AI learned
• OpenCode compaction generates summaries but throws away corrections
• Claude Code's AutoDream consolidates memory files but doesn't track corrections or drift
• No tool persists why the AI was corrected or how many times

What CyxCode already built (that others don't have):

• Pattern learning — AI pays once, error is free forever
• Indexed memory — only relevant knowledge loaded (~500 tokens vs full file dump)
• Dream consolidation — auto-dedup, validate, persist stats on startup
• Router stats persistence — matches, misses, hit rate tracked across sessions

What we're building next (entirely new territory):

• Correction tracking with strength scoring
• Auto-commit before compaction (nothing lost)
• Resume from HEAD commit (AI picks up where it left off)
• Drift detection (AI stops following learned behavior → auto-remind)
• Auto-promotion (corrected 3x → permanent instruction)
• Content-hashed commits (~500 bytes each, like git)

Full design: State Versioning Design

4 pattern groups, 16 categories, 136 built-in patterns:

Community packs are bundled and auto-installed to ~/.cyxcode/community/ on first use. Manage with cyxcode community list|install|remove.

Full pattern breakdown: docs/ADDING-PATTERNS.md

CyxCode is a CLI coding agent built on OpenCode, but specialized for deterministic error recovery, reusable project memory, and lower token spend.

Plugins can't do what CyxCode does:

1. Short-circuit requires modifying the core loop — plugins can't break the LLM loop
2. Shell mode (!) has no plugin hook — SessionPrompt.shell() is a core function
3. Tool result metadata — cyxcodeMatched flag requires bash tool internals
4. Module initialization timing — Bun's --conditions=browser needs imports in core files

Plugins decorate. CyxCode changes control flow. That requires a fork.

CyxCode is a fork of OpenCode. You'll see opencode in some internal files — directory names (.opencode/, packages/opencode/) and internal code references. This is intentional.

A full rebrand of every internal reference would make it impossible to pull upstream improvements from OpenCode. We regularly sync with upstream to get new features, bug fixes, and TUI improvements. Renaming thousands of internal references would turn every git pull into a merge conflict nightmare.

What's been rebranded: the CLI (cyxcode), the TUI logo, the package scope (@cyxcode/*), feature flags (CYXCODE_*), config files (cyxcode.jsonc), database (cyxcode.db), and all documentation. The directory structure stays opencode internally for upstream compatibility.

If you see opencode in a directory path or source file, that's normal. If you see it in the UI or docs, that's a bug — please report it.

Available at http://localhost:4096/dashboard when running in web/server mode. See docs/PENTEST.md for full API reference.

MIT License — See LICENSE

Tokens are the new currency. CyxCode makes sure you don't waste them.

CyxCode — We automate the AI that automates us.