Kyber Companion

Kyber Companion combines deterministic project/deployment guidance with a documentation-grounded OpenAI chat. Its character, Kybi, is a floating green astronaut helper with glowing antennae and a holographic developer laptop. Error diagnosis and deploy guards remain deterministic; chat answers are restricted to Kyber's supported public behavior.

Included in the first implementation

• A dedicated Kyber activity-bar view.
• An animated, reduced-motion-aware Kybi webview.
• Deterministic error-code-to-playbook mapping.
• kyber doctor --json integration.
• An allowlist for commands exposed as clickable actions.
• A guarded deployment command that records a successful version and blocks a later release with the same version.
• Tests for playbook selection and version guarding.
• Ask Kybi, an OpenAI-powered chat grounded privately in Kyber's public guides and installed CLI help.
• A draggable floating Kybi mascot that remembers its position inside the chat panel.

Run locally

1. Open this kyber-companion directory in VS Code.
2. Press F5 and select Run Kyber Companion (Clean). This launches the Extension Development Host without unrelated installed extensions.
3. The included launch profile opens the sibling kyber-agents workspace and lists every nested agent containing a kyber.agent.json, YAML, or YML file.

Python virtual environments

For the selected agent, Companion resolves kyber in this order:

1. The interpreter currently selected by the VS Code Python extension.
2. VIRTUAL_ENV or CONDA_PREFIX inherited by VS Code.
3. .venv, venv, or env in the agent directory.
4. .venv, venv, or env in the opened workspace directory.
5. The normal system PATH.

The selected executable and its source are displayed below the workspace agent list.

Ask Kybi

Run Kyber: Ask Kybi or select Ask Kybi in the Companion sidebar. Kybi answers from the public Kyber developer guides bundled with the extension and prefers live content from an opened workspace. Kybi answers directly: it does not expose documentation filenames or ask developers to open Markdown files. When the available context does not document an answer, Kybi says so instead of using outside knowledge. Questions about private implementation details are refused while public behavior is still explained.

Answers are rendered as safe Markdown. JSON is shown as formatted JSON code blocks, and shell commands are shown in Bash code blocks.

On the first question, Kybi asks for an OpenAI API key. The key is stored in VS Code Secret Storage and is never passed to the webview. You can replace or remove it with Kyber: Set OpenAI API Key and Kyber: Clear OpenAI API Key. OPENAI_API_KEY is also supported. The documentation corpus is read once per extension session and placed in a stable prompt prefix so later questions can reuse OpenAI prompt caching. The first request establishes the cache; reuse is subject to OpenAI's cache lifetime and eligibility rules.

The floating character can be dragged anywhere inside the Ask Kybi webview and remembers its position. VS Code extensions cannot draw arbitrary overlays on top of native editor controls, so dragging is intentionally bounded to that panel. 4. Select the Kyber Companion icon in the Activity Bar.

Run the dependency-free checks with:

npm test
npm run check

CLI contract

The diagnostic command is expected to return JSON:

{
  "success": false,
  "error": {
    "code": "KYBER_AUTH_REQUIRED"
  }
}

Unknown codes always use the KYBER_UNKNOWN playbook. They never receive speculative instructions.

Deployment behavior

Use Kyber: Deploy with Version Guard from the Command Palette or the companion sidebar. After a successful kyber deploy, the extension stores the deployed version in VS Code workspace state. A second release using the same version is blocked and opens the manifest so the developer can update it.

The guard currently applies to deployments launched through the companion. Enforcing the same rule for kyber deploy invoked in an arbitrary external terminal requires the CLI deploy command to call the shared guard contract before deployment. That integration should be added only after matching the host CLI's existing command architecture and version source.