We automate the AI that automates us.

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: install bun baseline build to ~/.bun/bin/.

cyxcode init           # Create .cyxcode/ in project root
cyxcode init --global  # Create ~/.cyxcode/ for cross-project state

Or use the slash command inside the TUI:

/cyxinit               # Initialize .cyxcode/ without leaving TUI

This creates a .cyxcode/ directory (like git init for AI state). Without init, CyxCode falls back to .opencode/ — init upgrades to the full three-tier system with automatic migration.

Type ! to enter shell mode, then type a command. The command runs directly without AI — zero tokens.

If the command fails, CyxCode checks its built-in patterns for a match. If matched, the fix is displayed instantly. No AI involved at all.

! python3 -c 'import flask'
  -> Runs directly (no AI)
  -> CyxCode pattern matches: python-module-not-found
  -> Fix: pip install flask
  -> Tokens: ZERO

Switch agents with Tab:

Use @general in messages to invoke the subagent for complex searches.

Type / followed by the command name:

CyxCode intercepts errors before the AI processes them. 136+ built-in patterns across 16 categories, plus bundled community packs for Bun, Rust, Go, and Ruby:

When a command fails:

1. CyxCode checks all patterns against the error output
2. Match found → Fix displayed, LLM skipped ([CyxCode] label visible)
3. No match → AI handles it, CyxCode learns from the interaction

• [CyxCode] in output = pattern matched, free fix
• No [CyxCode] = AI handled it (costs tokens)

When CyxCode misses a pattern, the AI handles it. But CyxCode captures the interaction:

1. Error output + AI's fix are saved (.cyxcode/patterns/learned.json or .opencode/cyxcode-learned.json)
2. A regex pattern is auto-generated
3. Run /learn-patterns to review and approve
4. Approved patterns are active on next restart
5. Same error = zero tokens forever

CyxCode remembers project knowledge across sessions via indexed memory files.

/remember auth.ts uses JWT with bcrypt, middleware at line 50
/remember --global this machine uses ~/.bun/bin baseline

• Memories stored in .cyxcode/memory/ (or .opencode/memory/) as small .md files (1-5 lines)
• Each memory has tags for keyword matching
• On new sessions, only relevant memories load (max ~500 tokens)
• Memories auto-captured from session compaction summaries
• Global memories in ~/.cyxcode/memory/ apply to all projects on the machine
• Project memories take priority over global when both match

Check .cyxcode/memory/index.json (or .opencode/memory/index.json) for all stored entries.

CyxCode also keeps markdown notes as a local wiki.

• Create notes in .cyxcode/wiki/ or .opencode/wiki/
• Link related notes with [[wikilinks]]
• Use cyxcode wiki create <title> to add a new note
• Use cyxcode wiki rename <id> <title> to retitle a note
• Use cyxcode wiki delete <id> to remove a wiki note
• Use cyxcode wiki query [terms..] to search the current wiki index
• Open the web knowledge page at /:dir/knowledge to browse the wiki and graph
• Run cyxcode init to create the wiki directory in a fresh project
• Rebuild the wiki index when you want backlinks and graph data refreshed immediately

• CyxCode scans markdown files and builds a local note index
• Each [[wikilink]] becomes a backlink and graph edge
• Relevant wiki pages can be injected into the session prompt alongside memories
• Wiki pages are also indexed into recall, so similar docs can surface automatically
• The unified graph now feeds prompt context too, including nearby wiki, code, memory, learned, and fact nodes
• Wiki notes can reference code files or symbols with backticked paths, and the graph records those cross-links

• GET /experimental/wiki
• GET /experimental/wiki/graph
• GET /experimental/wiki/page?id=...
• POST /experimental/wiki/rebuild
• GET /experimental/codegraph
• GET /experimental/codegraph/graph
• GET /experimental/codegraph/page?id=...
• POST /experimental/codegraph/rebuild
• GET /experimental/graph
• GET /experimental/memory
• GET /experimental/memory/page?id=...

CyxCode also exposes a unified graph over wiki notes, code files, memories, learned patterns, semantic facts, and CyxWatch security signals.

• Open the graph tab on /:dir/knowledge
• Use the filters to focus on wiki, code, memory, learned, concept, or CyxWatch nodes
• Use the hop controls to expand the graph one, two, three, or four steps out from the selected node
• Click a node to inspect incoming and outgoing relationships
• Jump into the linked wiki note or source detail view from a node
• Refresh the graph after updating wiki notes, code, memory, or learned patterns

• wiki pages and [[wikilinks]]
• code files, imported modules, and declared symbols
• memory entries and their tags
• approved learned patterns and their categories
• semantic facts from the recall store
• CyxWatch events and alerts linked to sessions, prompt turns, files, commands, and outbound hosts
• graph context from nearby linked nodes when the AI builds its prompt

• GET /experimental/graph

CyxCode also scans project source files into a lightweight code graph.

• file-to-file imports
• file-to-symbol links for named and default imports
• top-level symbols declared in each code file

The code graph index is stored in:

• .cyxcode/codegraph/
• .opencode/codegraph/ when legacy state is still in use

• GET /experimental/codegraph
• GET /experimental/codegraph/graph
• GET /experimental/codegraph/page?id=...
• POST /experimental/codegraph/rebuild

1. Let CyxCode scan the repo, or call POST /experimental/codegraph/rebuild.
2. Open the dashboard or query the API to inspect files and relationships.
3. Use the graph to see which files import which modules and symbols.

When the built-in regex patterns miss, recall searches your indexed project memories and learned patterns for semantically similar prior errors — using local MiniLM embeddings, zero API calls.

1. Shell command fails and pattern matching finds no hit.
2. Recall embeds the last ~2000 chars of the error output with a local 25 MB model (WebAssembly, CPU-only).
3. Dot-product similarity scan against everything in .cyxcode/recall.db.
4. Top-3 hits above a confidence threshold get injected into the shell output as [CyxCode] hints.
5. The LLM's next turn sees the prior-error context automatically and usually produces the right fix immediately.

No network, no API key, no tokens spent on retrieval — ever.

Recall builds its index from three Bus events you already emit:

On first run, recall walks your existing memory/index.json and learned.json files and batch-embeds everything retroactively.

• First boot after install: recall kicks off a background warmup. Nothing user-visible until the first pattern miss.
• First pattern miss: instant, because warmup already loaded the model.
• Initial model download: ~15 seconds once, cached forever.

Delete .cyxcode/recall.db to wipe the index. Recall will recreate an empty DB on next boot; similar() returns [] until something gets indexed again.

For a full rebuild: the internal Recall.reindex() API forces a wipe + retro-walk of all sources. No slash command yet — planned.

See RECALL.md for architecture, API reference, performance numbers, and design rationale.

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

• Deduplicates learned patterns
• Merges overlapping memories
• Validates file existence and regex
• Persists router stats

• All auto-dream phases plus:
• Smart merging of related memories
• Updates AGENTS.md with new learnings
• Reports stats: matches, misses, hit rate, tokens saved

Persisted to .cyxcode/stats.json (or .opencode/cyxcode-stats.json):

• Pattern matches/misses across sessions
• Hit rate
• Lifetime tokens saved
• Sessions tracked

CyxCode tracks AI state across sessions — corrections, context, working files. Like git for AI behavior.

Save behavioral rules the AI should always follow. Corrections persist across sessions and get stronger with reinforcement.

/correct always use bun, not npm
/correct --global keep responses under 3 lines

Project corrections override global ones. Global corrections (saved to ~/.cyxcode/corrections/) apply across all projects.

The AI will follow the correction in future sessions:

Before correction — AI would use npm by default.

After correction — AI recognizes the rule and self-corrects:

The AI's thinking shows: "According to the instructions, I should always use bun, not npm." It overrides the user's npm request and uses bun add instead.

Even when explicitly asked to use npm, the correction takes priority:

If a coding session stops in the middle of work, CyxCode does not rely on the model's memory. It persists a compact project state outside the model, then reloads that state when you continue.

Use the existing session when you want the full conversation back:

cyxcode --continue

Or open the TUI and choose the prior session:

/sessions

For cross-session recovery, CyxCode also writes a compact HEAD snapshot under .cyxcode/history/ (or legacy .opencode/history/). To view the latest recovery state directly in the TUI:

/resume

On the next prompt, the system prompt includes the same state as a <cyxcode-resume> block with the previous goal, in-progress request, active files, and useful discoveries.

That means you can ask:

What were we working on before the terminal closed?

The AI should answer from the saved CyxCode state instead of starting blank.

This is a recovery summary, not a full transcript. Use cyxcode --continue, cyxcode -s <sessionID>, or /sessions for the full stored conversation. Hard kills can still lose the last few seconds if the process cannot finish writing the snapshot.

cyxcode init
cyxcode

In the TUI, ask CyxCode to start a concrete task that reads or edits files. For example:

Inspect the TUI command autocomplete and explain how CyxCode slash commands are shown.

After it begins working, exit cleanly with Ctrl+C. Then verify that a state snapshot exists:

cat .cyxcode/history/HEAD.json
ls .cyxcode/history/commits

Reopen CyxCode:

cyxcode --continue

View the saved recovery state:

/resume

Ask:

What were we working on before the terminal closed?

Expected result: /resume and the answer should mention the previous goal, in-progress task, or active files from the saved state. If .cyxcode/ has not been initialized, check the legacy paths instead:

cat .opencode/history/HEAD.json
ls .opencode/history/commits

Behavioral corrections are versioned rules that load into future prompts.

/correct always use bun, not npm

Verify that CyxCode saved the correction:

ls .cyxcode/history/corrections
cat .cyxcode/history/corrections/*.json

Run the same /correct rule again to reinforce it. The matching JSON file should keep the same id and increment strength.

Start a new session and ask for something that conflicts with the rule:

install a package with npm

Expected result: the AI should see the correction in the system prompt and prefer Bun. After a correction reaches strength 3, /dream can promote it into AGENTS.md.

1. Session storage: Existing conversations can be reopened with cyxcode --continue, cyxcode -s <sessionID>, or /sessions.
2. Activity commits: CyxCode saves a compact snapshot after the user prompt starts and debounces saves while messages and tool results update.
3. Auto-commit: CyxCode saves compact state snapshots on session end and after compaction. Ctrl+C, SIGTERM, and terminal hangup also try to commit before exit.
4. HEAD snapshot: .cyxcode/history/HEAD.json points to the latest state commit in .cyxcode/history/commits/.
5. Resume command: /resume shows the latest HEAD recovery summary in the TUI.
6. History command: /history shows recent versioning events from .cyxcode/history/changelog.json.
7. Resume prompt: The latest HEAD commit is loaded into the next prompt as <cyxcode-resume>.
8. Corrections: Saved via /correct, loaded into the system prompt sorted by strength.
9. Drift detection: If AI stops following a correction, its strength increases automatically.
10. Dream integration: Corrections with strength >= 3 auto-promoted to AGENTS.md. Unused corrections decay over time.

When you spawn subagents (@general, Task tool), each gets an isolated state branch — like git branches for AI state.

1. Branch creation: When a subagent spawns, CyxCode creates a branch from the current HEAD
2. Isolated commits: Subagent's state commits go to its branch, not main
3. Auto-merge: When subagent completes, branch merges back via three-way merge
4. Discovery propagation: New discoveries from subagents automatically merge to main

Main session: HEAD = commit_abc
  |
  +-- @general "find all API endpoints"
        |
        Branch: session_xyz (base: commit_abc)
        Commits to branch HEAD
        Discovers: "API uses Express router at /api/*"
        |
        Subagent completes
        |
        Three-way merge -> main HEAD updated
        Discovery added to main state

.cyxcode/history/
  branches/{sessionID}.json   # Branch refs (status, HEAD, base)
  merges/{mergeHash}.json     # Merge records (conflicts, discoveries)

• active: Subagent running, accepting commits
• merged: Subagent completed, state merged to main
• abandoned: Subagent crashed or cancelled

Old merged/abandoned branches are garbage collected after 7 days.

CyxCode tracks every pattern match, correction, and drift event. Generate reports to see token savings and efficiency.

# 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

# CyxWatch runtime observability
cyxcode watch recent
cyxcode watch report
cyxcode watch alerts
cyxcode watch policy
cyxcode watch policy --effective
cyxcode watch report --period 30d
cyxcode watch report --json
cyxcode watch policy --json

+-------------------------------------------------------------+
|        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%            |
|                                                             |
+-------------------------------------------------------------+

For an installed CLI, launch web mode:

cyxcode web

The installed CLI serves the main web app and dashboard locally from the same CyxCode server. By default it opens http://127.0.0.1:4096/app/ or the configured server port.

http://127.0.0.1:4096/app/
http://127.0.0.1:4096/dashboard/

Global server settings live in the CyxCode config directory. On Windows this is usually:

%USERPROFILE%\.config\cyxcode\config.json

Project settings live in:

<project>\.cyxcode\config.json

CyxCode discovers project config by walking up from the current directory. It prefers .cyxcode first, then .opencode for legacy compatibility. Global config is loaded first, then project config overrides it. Environment variables override matching runtime values when supported.

Example:

{
  "$schema": "https://cyxcode.ai/config.json",
  "server": {
    "hostname": "127.0.0.1",
    "port": 4096,
    "username": "cyxcode",
    "password": "change-this-password",
    "mdns": false
  }
}

CYXCODE_SERVER_USERNAME and CYXCODE_SERVER_PASSWORD override these config values when set in the environment.

Common config settings:

Local model example with Ollama:

{
  "$schema": "https://cyxcode.ai/config.json",
  "model": "ollama/qwen2.5-coder:7b",
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Ollama Local",
      "options": {
        "baseURL": "http://localhost:11434/v1",
        "apiKey": "ollama"
      },
      "models": {
        "qwen2.5-coder:7b": {
          "name": "Qwen2.5 Coder 7B"
        }
      }
    }
  }
}

For local development from this repository, start the backend, main web app, and dashboard dev app separately:

# Terminal 1: backend/API
cd D:\Dev\Failed\cyxcode\packages\opencode
bun run --conditions=browser ./src/index.ts serve --hostname 127.0.0.1 --port 4096

# Terminal 2: main CyxCode web app
cd D:\Dev\Failed\cyxcode\packages\app
bun run dev -- --host 127.0.0.1 --port 3000

# Terminal 3: dashboard graph/wiki UI
cd D:\Dev\Failed\cyxcode\packages\opencode\src\dashboard
npm run dev -- --host 127.0.0.1 --port 3002

Open the local dashboard:

http://127.0.0.1:4096/app/
http://127.0.0.1:4096/dashboard/
http://127.0.0.1:4096/dashboard/security
http://127.0.0.1:4096/dashboard/reports

The dashboard dev app is also directly available at http://127.0.0.1:3002/dashboard/. The backend/API is available at http://127.0.0.1:4096/.

The app dashboard pages at /dashboard/reports and /dashboard/security show:

• report generation and previews
• runtime observability metrics
• alert history
• recent audit events

The CyxWatch layer records runtime telemetry locally and is surfaced through:

• cyxcode watch recent
• cyxcode watch report
• cyxcode watch alerts
• GET /cyxwatch/query?session=...&path=...&host=...&flag=...&decision=...
• cyxcode watch policy for saved project policy rules, or --effective to include defaults
• the dashboard page at /dashboard/security

It currently tracks:

• prompt turns with session/message correlation
• shell commands
• file reads and writes
• basic risk flags for sensitive paths and risky shell strings
• basic policy decisions: allow, warn, require-approval, block

When governance is enabled in config, policy decisions are enforced through the tool permission gate:

• auto-approve allows the matching operation without a prompt
• require-approval uses the normal permission prompt
• blocked stops the tool call before it executes

CyxWatch also guards shared lower-level wrappers for hard block decisions. This catches destructive process-wrapper commands before spawn and checks filesystem writes before writing. Interactive approval remains in the normal tool permission path.

All audit entries are automatically scrubbed of secrets (API keys, JWTs, passwords) before storage.

By default, CyxCode runs quietly with minimal console output. Enable debug mode to see internal details:

CYXCODE_DEBUG=true cyxcode

Debug mode shows:

• Pattern matching attempts and results
• Database operations and migrations
• Bus subscription events
• Startup initialization timing

Run cyxcode init to create .cyxcode/ — a dedicated directory for AI state, separate from .opencode/ config.

$ cyxcode init

Initializing CyxCode...
  Created .cyxcode/
  Created .cyxcode/config.json
  Created .cyxcode/history/
  Created .cyxcode/memory/
  Created .cyxcode/patterns/
  Added .cyxcode/history/ to .gitignore
  Detected project type: node

CyxCode initialized. Ready to track AI state.

Options:

• --global — Initialize ~/.cyxcode/ for cross-project state
• --no-migrate — Skip automatic migration from .opencode/

If .opencode/ exists, cyxcode init automatically copies cyxcode-specific files to .cyxcode/:

Originals are kept (copy, not move). A .cyxcode-migrated marker prevents re-migration.

CyxCode ships with bundled community packs for Bun, Rust, Go, and Ruby. These are automatically installed to ~/.cyxcode/community/ on first use.

Manage community packs with CLI:

# List installed packs
cyxcode community list

# Install from file or URL
cyxcode community install ./my-patterns.json
cyxcode community install https://example.com/patterns/elixir.json

# Remove a pack
cyxcode community remove bun-errors

# Validate pack format before sharing
cyxcode community validate ./my-patterns.json

Pack format:

{
  "name": "bun-errors",
  "version": "1.0.0",
  "patterns": [
    {
      "id": "bun-registry-404",
      "regex": "error: GET https://registry\\.npmjs\\.org/\\S+ - 404",
      "category": "bun",
      "description": "Package not found in npm registry",
      "fixes": [{ "id": "check-name", "description": "Check package name for typos", "priority": 1 }]
    }
  ]
}

1. Built-in patterns (136, from source code)
2. Community patterns (~/.cyxcode/community/)
3. Global learned patterns (~/.cyxcode/patterns/learned.json)
4. Global corrections (~/.cyxcode/corrections/)
5. Global memories (~/.cyxcode/memory/)
6. Project learned patterns (.cyxcode/patterns/learned.json)
7. Project corrections (.cyxcode/history/corrections/)
8. Project memories (.cyxcode/memory/)

Project overrides global. Global overrides community.

CyxCode works without init — all state saves to .opencode/ (backward compatible). init upgrades to the structured .cyxcode/ layout with global and community tiers.

.cyxcode/
  config.json               # Project config (type, created date)
  history/
    HEAD.json               # Latest commit pointer
    commits/                # State snapshots
    corrections/            # Behavioral rules
    changelog.json          # Event log
  memory/
    index.json              # Memory index (tags, summaries)
    *.md                    # Individual memories
  patterns/
    learned.json            # Learned error patterns (pending + approved)
  stats.json                # Persisted router stats
  agent/                    # Agent configs
  command/                  # Custom slash commands

~/.cyxcode/                 # Global tier (cyxcode init --global)
  config.json
  corrections/              # Global behavioral rules
  memory/                   # Global memories
  patterns/
    learned.json            # Global learned patterns
  community/                # Community pattern packs (*.json)
  stats.json

.opencode/
  memory/
    index.json              # Memory index (tags, summaries)
    *.md                    # Individual memories (1-5 lines each)
  cyxcode-learned.json      # Learned error patterns (pending + approved)
  cyxcode-stats.json        # Persisted router stats
  cyxcode.jsonc             # Project config
  command/                  # Custom slash commands
  agent/                    # Agent configs

See Adding Patterns for a step-by-step guide.

See Contributing Patterns to add patterns for new tools/languages.

See Performance for benchmarks and token savings estimates.