@controlvector/cv-code

cv-code — Control Vector's fork of opencode with cv-hub knowledge graph integration. v0.1.0 consolidates the v0.0.4 → v0.0.11 sprint sequence into a release that closes every finding from the v0.0.4 dormancy audit and ships a graph-aware coding agent that works against both indexed and non-indexed repositories.

cv-code preserves opencode's chat mode and CLI surface; cvc-specific additions are designed to retrieve from cv-hub's code intelligence graph (with a local- scan fallback when graph data is missing), surface a learned permission recommendation overlay (Sprint 3 LinUCB bandit + policy-tier safety floor), and enable Recursive Language Models sessions (cvc rlm).

What v0.1.0 ships

| Capability | What it does | Sprint | |---|---|---| | First-run cv-hub UX | Detects git remote, prompts to configure cv-hub on first session in a fresh workspace, writes cvhub.owner/repo to opencode.json. | Sprint 7 (v0.0.5/.6) | | Bandit auto-allow learning | Auto-allowed permission decisions feed the LinUCB bandit as synthetic-yes outcomes — closes the v0.0.4 finding that permissive rulesets produced empty bandit_arms rows. | Sprint 8 (v0.0.7) | | cv_search / cv_subgraph / cv_neighbors chat tools | Three chat-mode tools that query cv-hub's graph (with provenance: "graph") or fall back to ripgrep + recency-weighted ranking (provenance: "local-scan") when the repo isn't indexed. Tools are elided entirely when cvhub isn't configured. | Sprint 9 (v0.0.8) | | Working-set system-prompt block | Token-budgeted ranked symbols injected into the system prompt; replaces the legacy <env> block when populated. | Sprint 9 (v0.0.8) | | TUI status line | Persistent line above the chat: cvhub: configured \| graph: ready \| working-set: 6 symbols \| phase: explore. Transient [bridge: querying...] flash when a cv_* tool fires. | Sprint 10 (v0.0.9) | | cvc auth login cv-hub | Interactive PAT-paste flow with browser open + 5s validation + secure-store at auth.json (mode 0600). Replaces the v0.0.4 friction of manually exporting CV_HUB_PAT. | Sprint 11 (v0.0.10) | | RLM Provider parity + permission modes | cvc rlm --model <provider/model> works with every provider opencode supports (anthropic, openai, bedrock, ...). New --permissions {refuse,prompt,auto-allow} flag with the Sprint 3 ask-user safety floor preserved across all modes. | Sprint 12 (v0.0.11) |

Details and per-sprint architectural decisions live in docs/cv-hub-integration.md and docs/upstream-deviations.md (per-touch markers).

v0.1.0 release status — what's verified vs. soft signal

This section is intentionally explicit: users installing v0.1.0 should know what the release-readiness gates actually pinned and what was deferred.

Indexed eval set

v0.1.0 was evaluated against three indexed repositories:

| Repo | Files | Symbols | Functions | Classes | Relationships | |------|-------|---------|-----------|---------|---------------| | controlvector/cv-git | 398 | 2349 | 1803 | 86 | 6532 | | controlvector/cv-prd | 149 | 396 | 275 | 84 | 1196 | | controlvector/cv-code | 4644 | 4148 | 3471 | 208 | 15371 |

This satisfies the design doc's "≥3 indexed repos for v0.1.0" soft requirement.

v0.0.4 finding closure (5/5)

The v0.0.4 dormancy audit raised five findings. v0.1.0's release-readiness criterion was that all five be closed and pinned by automated evidence:

| # | Finding | Closed in | Smoke gate covers | |---|---------|-----------|-------------------| | 1 | First-run UX gap (no auto-prompt for cvhub config) | v0.0.5/.6 (Sprint 7) | first-run-flow assertions | | 2 | cv_search/cv_subgraph/cv_neighbors not registered as chat tools | v0.0.8 (Sprint 9) | chat-tool / system-prompt assertions | | 3 | No working-set block in system prompt | v0.0.8 (Sprint 9) | WorkingSet log fired + no-doubled-blocks | | 4 | No user-visible cvhub status surface | v0.0.9 (Sprint 10) | status-line assertions | | 5 | No path to provide CV_HUB_PAT without env var | v0.0.10 (Sprint 11) | auth-flow assertions |

What's verified at v0.1.0

• Cumulative pre-publish smoke gate (scripts/smoke-runtime.sh): all assertions pass — version sync, working-set log, on-disk state.db, cvhub bridge reachable, chat-tool registration, status-line content for configured / unconfigured workspaces, auth login → status → status-line PAT pickup → logout, RLM permission-mode flag parsing + Provider.Service parity.
• 361-test cvhub regression suite: pass (no skips on cvhub-critical paths; 4 skips are pre-existing platform-conditional).
• Both BANDIT_LEARNING_CANARY (asked path) and BANDIT_LEARNING_CANARY_AUTOALLOW (synthetic-yes path) at 114.4pp yes/no gap (threshold ≥30pp).
• RLM_PROVIDER_SERVICE_PARITY source-string regression: pinned (no @ai-sdk/anthropic import; Provider.Service used; AI SDK's generateText preserved as call mechanism).
• Direct cv-hub MCP probes (graph_stats, search_symbols) return correctly for all three indexed repos.
• Status-line shape cvhub: configured | graph: ready | working-set: ... | phase: ... verified for cv-git, cv-prd, cv-code.
• Three per-repo eval reports + aggregate findings at ~/cvc-evals/cvc-eval-v0.1.0-*.

What's soft signal (deferred)

The v0.0.4 cv-prd evaluation ran multi-turn LLM-driven sessions against a local vLLM endpoint and demonstrated the model picking cv_search of its own accord across realistic queries. That fresh multi-turn capture was not re-run for v0.1.0 — the eval-environment provider was unavailable when the per-repo probes ran. v0.1.0 closure rests on:

• The Sprint-9 mock-model integration test (deterministic, no live LLM provider needed) — passes in regression.
• The cumulative smoke gate's working-set + chat-tool assertions — pass.
• The original v0.0.4 cv-prd multi-turn artifacts (one-time, against this same indexed graph).

This is sufficient for v0.1.0 publish but is a softer signal than a fresh multi-turn capture against the v0.1.0 build. Procedure for users (or the cvc team) to run a multi-turn dogfood capture is documented at docs/testing.md.

What cv-code becomes (v0.2.0 preview)

v0.1.0 is the platform we said we'd build at v0.0.4: dormancy fixed, cvhub bridge reachable, working-set populated, status-line visible, auth ergonomic, RLM provider-agnostic.

v0.2.0 (CV-ARCH-CVCODE-002) is the architectural inversion that comes next: anchor architecture — instead of the agent assembling context per-turn from the graph, the agent maintains a small set of anchor symbols across a session, and graph queries are deltas relative to those anchors. Working-set rotation becomes a navigation problem rather than a retrieval problem. Bandit learning extends from per-decision to per-anchor-shift. Cross-session anchor handoff opens up the path to durable agent memory.

Don't conflate v0.2.0 with v0.1.0. v0.1.0 is what ships now; v0.2.0 is the architecture spec, not yet the implementation.

Installation

npm install -g @controlvector/cv-code

Requires Node ≥ 20.19 and Bun ≥ 1.3.

Usage

# Chat mode (preserved from upstream opencode)
cvc

# Run a single command
cvc run "Refactor this function to be tail-recursive"

# RLM session — paper-faithful Recursive Language Models (arXiv:2512.24601)
cvc rlm "Summarize the architecture of this repo"
cvc rlm --model anthropic/claude-sonnet-4-5 --permissions prompt "Inspect tools"
cvc rlm --file input.md --max-cost 0.10 "What's the main entry point?"

# cv-hub config & visibility
cvc cvhub init           # one-time interactive configure
cvc cvhub status         # show resolved cv-hub config + detected remote
cvc cvhub status-line    # print the persistent status-line content
cvc cvhub inspect-prompt # print chat-mode tool list + system prompt as JSON

# cv-hub auth
cvc auth login cv-hub
cvc auth status
cvc auth logout cv-hub

# Help
cvc --help

The CLI is a drop-in superset of upstream opencode: every existing opencode subcommand works under cvc. RLM and the cvhub/auth subcommands are the cv-code additions.

Configuration

cvc reads config from XDG paths under cv-code/ (e.g. ~/.config/cv-code/config.json on Linux, ~/Library/Application Support/cv-code/ on macOS). Project-local config still uses the upstream opencode.json convention for compatibility.

Available chat tools

cvc inherits opencode's chat tools (Read, Edit, Bash, Grep, Glob, etc.) and adds three cvhub-specific tools when the workspace is configured for cv-hub graph integration:

• cv_search(query, topK) — Semantic search the codebase's knowledge graph. For concept searches ("find the authentication route handler") rather than literal-string matching like grep.
• cv_subgraph(symbol, hops) — Expand a symbol to its surrounding code subgraph (callers/callees/structural neighbors). Use AFTER cv_search to expand context around a found anchor.
• cv_neighbors(symbol, relationship) — Find symbols related to a given one, filtered by relationship: callers, callees, or all. Useful for control-flow / data-flow tracing.

When cvhub is configured but the repo isn't indexed on cv-hub, these tools fall back to local-scan equivalents (ripgrep + recency-weighted ranking + definition/reference search). Lower fidelity than the graph version, but useful — non-indexed repos still get observable benefit from cvhub.

When cvhub isn't configured at all (no cvhub.owner/cvhub.repo), the cv_* tools aren't shown to the model — chat behaves as upstream opencode.

Minimum config for cv-hub graph integration

The fastest path: launch cvc in a git workspace and accept the interactive first-run prompt:

First run in this workspace.
cv-code can use cv-hub graph integration to provide context-aware
coding assistance against your project's knowledge graph.

Detected: github.com/your-org/your-project
Configure cv-hub for this workspace? [Y/n/edit]

Hit Enter to accept the auto-detected owner/repo from your git remote, or type edit to override. Either path writes a cvhub block to the workspace's opencode.json. Type n to decline (the prompt won't fire again in this workspace).

If you prefer to write the config by hand:

{
  "cvhub": {
    "url": "https://api.hub.controlvector.io",
    "owner": "your-org",
    "repo": "your-project",
    "workingSet": { "enabled": true },
    "permission": { "enabled": true }
  }
}

Without cvhub.owner and cvhub.repo, CVHub.isAvailable() returns false and every cvhub-aware code path silently no-ops. Same end result as upstream opencode — the cvc-specific feature set is dormant.

Authentication

cvc auth login cv-hub is the easiest path: an interactive browser-open + paste + validate flow that stores the token at ~/.local/share/cv-code/auth.json (mode 0600). Token resolution precedence:

1. cvhub.token in opencode.json (explicit override; rare)
2. CV_HUB_PAT env var (CI / smoke; takes precedence over file)
3. auth.json cv-hub entry (where cvc auth login saves it)

Tokens for controlvector org repositories can be created at https://hub.controlvector.io/-/user/settings/applications.

Env var prefixes

• CVC_* — top-level cvc config (e.g. CVC_SERVER_PASSWORD, CVC_PURE).
• CV_CVHUB_* — cvhub-subsystem overrides (e.g. CV_CVHUB_PERMISSION_ENABLED, CV_CVHUB_WORKINGSET_SYSTEM_BLOCK_BUDGET, CV_CVHUB_RLM_MAX_COST_USD).
• CV_HUB_PAT — cv-hub authentication (above).

What gets curated when cvhub is enabled and reachable

• The system prompt for each turn includes a top-N working-set of symbols ranked by Markov phase prediction + Personalized PageRank + LinUCB freshness.
• Permission requests show a greppable [POLICY: <tier>] [PERSONAL: <pick>] [COHORT: n/a] recommendation line above the standard [y]es / [a]ll / [n]o prompt.
• The bandit learns from your permission decisions (active and auto-allowed) and persists state to ~/.local/share/cv-code/<workspace-id>/state.db (workspace ID is a 16-hex-char hash of the directory cvc was launched from).

Troubleshooting

If cvhub features don't seem to be firing:

1. Confirm version: cvc --version should print 0.1.0 or later.
2. Confirm token: cvc auth status should show cv-hub: configured (or echo "$CV_HUB_PAT" | head -c 8 should print the first 8 chars).
3. Confirm config: ~/.config/cv-code/config.json (or per-workspace opencode.json) should have cvhub.owner and cvhub.repo set.
4. Confirm status line: cvc cvhub status-line should print cvhub: configured | graph: ready | working-set: ... | phase: ....
5. Confirm state.db: ls ~/.local/share/cv-code/*/state.db should list at least one file after a run. Inspect with sqlite3:

   sqlite3 ~/.local/share/cv-code/*/state.db ".tables"
   # should list: bandit_arms, permission_decisions, trajectories, workflow_transitions

6. Run with logs: cvc run --print-logs --log-level INFO "<prompt>" should emit service=cvhub.working-set lines for the working-set refresh and service=cvhub.permission.recommend lines for permission asks. If neither appears, the wiring is dormant — open an issue with the log output and cvc --version.

Testing & evaluation

docs/testing.md documents the procedures for:

• Manual model-selects-cv_search verification (Sprint 9, deterministic via mock-model integration test + a periodic real-LLM check).
• Per-repo real-use evaluation procedure (the v0.1.0 eval template — running cvc against an indexed repo and capturing a ~/cvc-eval-vN-{repo}-{date}.md report).

The v0.0.4 cv-prd evaluation report is the canonical example of what a multi-turn capture looks like.

Attribution

See ATTRIBUTION.md. cv-code is MIT-licensed; opencode is MIT-licensed. Upstream credit goes to Anomalyco and the opencode contributors.

Issues

• cv-code-specific issues: https://hub.controlvector.io/controlvector/cv-code/issues
• Issues that reproduce on upstream opencode: https://github.com/anomalyco/opencode/issues