VS Kizuna

VS Kizuna is a pre-release Visual Studio Code extension for workspace context, local Git status, bounded local change insights, and read-only GitHub repository activity. The dashboard brings these views together in the editor.

Project status: VS Kizuna is in active pre-release development. It is not currently described as a stable, Marketplace-published release. Build and install a local VSIX using the instructions below.

Quick start

Requirements

• Visual Studio Code 1.145.0 or later (the manifest currently declares ^1.145.0).
• The built-in VS Code Git extension for local Git status and local change analysis.
• The built-in VS Code GitHub Authentication extension for optional GitHub features.
• Node.js 22 and npm only when building or testing from source.

Build and install a local VSIX

From a clone of this repository:

npm ci
npm run compile
npx --yes @vscode/vsce package --no-dependencies

Install the generated .vsix using the VS Code Extensions view: open the Extensions view, select …, choose Install from VSIX…, and select the package. Alternatively, use the VS Code CLI:

code --install-extension <path-to-generated-vsix>

The VSIX is built locally; this project has not yet documented a public Marketplace installation route.

First run

1. Open a folder or workspace in VS Code. Local Git information and local change insights depend on the built-in Git extension and workspace files reported as changed.
2. Open the Command Palette and run VS Kizuna: Open Dashboard. The VS Kizuna status bar item also opens the dashboard when the status-bar setting is enabled (the default).
3. To show the signed-in GitHub account label, optionally run VS Kizuna: Connect GitHub. This requests basic profile access (read:user).
4. To discover repositories and use the GitHub activity panels, run VS Kizuna: Connect GitHub Repositories. Review the GitHub permission prompt before approving the classic OAuth repo scope.
5. After repositories load, choose Use in dashboard context on a repository card. The dashboard then loads that repository's open pull requests, open issues, and recent commits. Use Refresh all activity to refresh the selected repository metadata and all three panels together.

You can use the workspace, Git, and local-insight features without connecting GitHub. The repository permission prompt can be declined; GitHub features remain unavailable until repository access is granted.

Current features

• Workspace context: displays the names of workspace folders open in the current VS Code window.
• Local Git status: uses the built-in VS Code Git extension to display the current branch, commit, staged changes, modified files, untracked files, merge conflicts, upstream, and ahead/behind counts.
• Status bar entry point: the VS Kizuna status bar item opens the dashboard. It is enabled by default and can be disabled in Settings.
• GitHub account status: uses VS Code's built-in GitHub authentication provider to show the connected account label.
• GitHub repository discovery: lists repositories visible to the authenticated GitHub account, including owned repositories, collaborator repositories, and organization-member repositories. The dashboard shows up to the 50 most recently updated repositories.
• Dashboard repository context: select one discovered repository for the dashboard panels, or clear that context. The selection is held in extension-host memory; it is not a persistent workspace or account preference.
• Open pull requests panel: displays open pull requests for the selected repository, including title, author, draft state, branches, labels, update date, and a body preview.
• Open issues panel: displays open issues for the selected repository, including title, author, assignees, labels, milestone, comment count, update date, and a body preview. Pull-request-shaped records returned by GitHub's combined issues endpoint are filtered out.
• Recent commits panel: displays commits on the selected repository's default branch, including SHA, subject, author, authored date, parent count, and a description preview.
• GitHub activity controls: refresh each panel independently, load additional results when available, or use Refresh all activity to refresh repository metadata and reload pull requests, issues, and commits from their first pages.
• Local change insights: the dashboard shows severity counts and up to ten recent findings grouped by repository. Findings include a category and pattern-confidence label, and can open the affected file at the reported line. VS Kizuna: Analyze Local Changes opens the complete searchable findings list.

Screenshots

No verified UI screenshots are included in the repository yet. The repository currently has no screenshot assets, so this README does not use mockups or generated images as if they were captures of the running extension.

See the screenshot capture checklist for the views to capture, the test-data requirements, and the privacy checks to complete before adding real screenshots.

Commands

Open the Command Palette and run a command by its displayed name.

Main commands

Dashboard activity actions

These commands are contributed by the extension and are normally used through links in the dashboard. The refresh and load-more actions operate on the currently selected dashboard repository.

The three dashboard activity panels request up to 100 records per page and cap pagination at 20 pages per panel. The separate Command Palette browse commands show the latest page of up to 100 records for the repository selected in their Quick Pick.

GitHub permissions and data handling

GitHub access is optional and uses VS Code's built-in GitHub Authentication provider.

• Connect GitHub requests the read:user scope for basic account identity.
• Connect GitHub Repositories separately requests the classic OAuth repo scope to list private and public repositories. This is a broad permission and can include write access. GitHub does not offer a read-only variant of this classic scope.

The permission prompt explains why the repository scope is requested. VS Kizuna's current repository, pull-request, issue, and commit services use the access token transiently for read-only HTTPS GET requests to GitHub. They do not create, edit, or delete repositories, issues, or pull requests. VS Kizuna does not intentionally persist or retain the access token in its own service state; VS Code manages the authentication session.

Repository discovery requests up to 100 repositories per page and processes at most 20 pages (2,000 repositories) per refresh. Duplicate repository IDs are ignored; results are sorted by update time and the dashboard displays up to 50 repositories. The dashboard indicates when repository discovery reached its 2,000-repository cap.

The pull-request, issue, and commit features read metadata for the repository selected by the user. They do not download repository file contents. The GitHub issues endpoint can return pull-request-shaped records; those are excluded from the issue list.

You can cancel the GitHub permission prompt. Do not grant repository access unless you are comfortable with the scope GitHub presents. You can continue using local features without repository access. See PRIVACY.md for the current data-access, transmission, and retention disclosure.

Local change analysis

The Analyze Local Changes command reads the current workspace contents for files the built-in VS Code Git extension reports as staged, modified, untracked, or conflicted.

The enabled-by-default checks flag:

• Merge-conflict opening, separator, and closing markers, including incomplete conflict blocks.
• Standalone debugger statements.
• console.log and console.debug calls.
• TODO, FIXME, and HACK markers.
• Dynamic code evaluation through eval() and new Function().
• Potentially unsafe DOM sinks such as innerHTML assignments and document.write().
• Process execution APIs and shell: true options.
• Disabled TLS certificate verification through rejectUnauthorized: false.
• TypeScript checking suppressions such as @ts-ignore and @ts-nocheck.

Findings are heuristics, not proof of a defect or vulnerability. They are conservative, line-oriented text matches rather than syntax-aware or AST-based analysis. Severity describes the potential impact if the pattern is unsafe; pattern confidence describes how directly the text matched a rule, not the probability that the code is vulnerable. Review each finding in context.

Analysis is local-only: it does not send source code or snippets to GitHub or another external service, does not execute shell commands, and does not modify files. It reads current workspace contents for changed file paths; it does not inspect staged Git blob contents separately or perform a full diff review.

For bounded resource use, one run considers at most 100 changed files, reads at most 512 KiB per file and 5 MiB in total, and reports at most 200 findings. Generated folders, lockfiles, source maps, minified files, snapshots, and binary files are skipped. Unreadable and skipped files are reflected in the scan summary. The dashboard shows severity totals and up to ten findings; use Analyze Local Changes to browse the complete searchable findings list.

Local insight and status-bar settings

All local insight rule families are enabled by default. You can disable individual checks in VS Code Settings by searching for VS Kizuna Local Insights or editing the corresponding settings:

The full local-insight setting names use the vsKizuna.localInsights.rules. prefix. Changing a rule setting refreshes the open dashboard analysis.

The status-bar item is enabled by default. Set vsKizuna.statusBar.enabled to false to hide it; the Open Dashboard Command Palette command remains available.

Known limitations

• Local change analysis inspects current contents of changed files, not the staged Git blob or a complete diff. Its text heuristics can miss issues or report false positives.
• Local analysis is limited to 100 changed files, 512 KiB per file, 5 MiB total, and 200 findings per run. The dashboard displays up to ten findings.
• Repository discovery processes at most 2,000 repositories and displays at most 50. Each dashboard activity panel paginates up to 20 pages of 100 records; the separate Quick Pick browse commands show one page of up to 100.
• GitHub features depend on network access, the user's GitHub permissions, organization policies, and GitHub API availability and rate limits.
• The dashboard's lower What is taking shape area still contains roadmap placeholder cards marked Planned; those cards are not implemented features.
• The manifest declares the VS Code engine range ^1.145.0. The automated Extension Host and VSIX installation checks currently run on VS Code 1.145.2 in GitHub Actions. This is not a claim of manual verification on every supported operating system or VS Code release.

Optional AI integration

VS Kizuna includes an optional OpenAI provider using the OpenAI Responses API. AI remains disabled by default. To configure it:

1. Run VS Kizuna: Set OpenAI API Key and enter an API key. The key is stored using VS Code SecretStorage, not in workspace or user settings.
2. Set vsKizuna.ai.enabled to true in VS Code Settings. The provider identifier defaults to openai.
3. Optionally change vsKizuna.ai.openai.model (default: gpt-6.1-sol) to a model available to your OpenAI API account.
4. Select a specific code snippet in an editor and run VS Kizuna: Explain Selected Code with AI. Enter a question, review the exact JSON request preview opened in the editor, and approve the modal confirmation to send it. Declining sends nothing.

The provider sends only the messages explicitly passed to it to https://api.openai.com/v1/responses. The selected-code workflow constructs those messages from the highlighted text, your question, and the editor language identifier. It does not read the whole file, file path, surrounding lines, other workspace files, GitHub activity, or credentials. Before sending, VS Kizuna opens a JSON preview containing the exact messages and then asks for modal approval. The preview is a snapshot; editing it does not change the pending request. Requests set the Responses API store parameter to false, so response application state is not retained by default. This does not disable OpenAI's abuse-monitoring logs: OpenAI documents that these may contain prompts and responses and are retained for up to 30 days by default, subject to its stated exceptions. OpenAI says API data is not used to train or improve models unless you explicitly opt in. Review OpenAI API data controls before sending sensitive material. API usage may incur charges under your OpenAI API account.

Use VS Kizuna: Clear OpenAI API Key to remove the stored key. Do not paste API keys into settings, issues, logs, or source files.

Configuration:

• vsKizuna.ai.enabled: opt-in feature switch; defaults to false.
• vsKizuna.ai.providerId: registered provider identifier; defaults to openai.
• vsKizuna.ai.openai.model: OpenAI model identifier; defaults to gpt-6.1-sol.
• vsKizuna.ai.requestTimeoutMs: request timeout from 1,000 to 60,000 milliseconds; defaults to 30,000.

The provider uses bounded request validation, cancellation, and timeout handling. Provider errors and response bodies are not logged verbatim. The adapter currently uses non-streaming Responses API requests.

Automated tests

Run the unit suite with:

npm test

The test script compiles the TypeScript sources and runs Node's built-in test runner. The suites cover local-change rules and settings; CRLF line numbers; finding limits and metadata; generated-file exclusions; Windows paths; binary files; directory and unreadable-file handling; per-file and total-byte limits; changed-file limits; and file-size changes between metadata and reads. GitHub API service tests use a mocked fetch transport to verify read-only request headers, response normalization, trusted URL filtering, pagination indicators and limits, duplicate repository handling, authorization failures, rate limits, malformed payloads, and transport errors without real network requests or credentials. The workspace scanner uses injected filesystem readers, so its safety limits and skip behavior can be tested without starting a VS Code Extension Host. CI runs the unit suite on every pull request and push to main.

Extension Host smoke tests

The Extension Host suite launches a clean, stable VS Code instance and exercises the extension through the real VS Code API. It creates a temporary Git workspace and checks extension activation, command registration, GitHub authentication scope requests, session-change handling through an injected test provider, token-free auth snapshots, status bar lifecycle, authentication and repository listener failures, local insight scan cancellation and refresh, built-in Git repository discovery, command and listener cleanup, dashboard lifecycle and GitHub activity panel behavior, rule-setting updates, finding navigation, and startup rollback.

The VS Code test harness is an optional development dependency and is deliberately not part of the extension's runtime package. To run the smoke tests locally:

npm ci
npm install --no-save --package-lock=false @vscode/test-electron@3.1.0
npm run test:extension-host

On Linux, run the command under an X virtual framebuffer when no graphical display is available:

xvfb-run -a npm run test:extension-host

GitHub Actions installs Xvfb and runs this suite as a separate job. The suite uses stable VS Code rather than a mocked Extension Host.

Packaging and installation verification

Create a local VS Code extension package (VSIX) after compiling the extension:

npm ci
npm run compile
npx --yes @vscode/vsce package --no-dependencies

The package includes the compiled extension, README, and MIT license. Development-only source files, test suites, and build scripts are excluded by .vscodeignore. CI builds the VSIX, checks that required runtime files are present and development files are absent, and uploads the package as the vs-kizuna-vsix workflow artifact for 14 days.

CI then installs that exact artifact with the VS Code CLI into a temporary, isolated user-data and extensions profile. It verifies that VS Code lists the expected publisher, extension identifier, and package version after installation. This installation smoke test uses VS Code 1.145.2; it confirms installation and registration, not Marketplace publication or cross-platform UI behavior.

To run the package-installation smoke test locally after building a VSIX, install the optional harness and run:

npm install --no-save --package-lock=false @vscode/test-electron@3.1.0
npm run test:vsix-install -- ./vs-kizuna.vsix

The test uses a temporary profile and removes it when complete. It validates package installation; it does not publish the extension to the Visual Studio Marketplace.

AI-assisted code workflows

AI features are disabled by default. To use them, enable vsKizuna.ai.enabled, configure an OpenAI API key with VS Kizuna: Set OpenAI API Key, and review the API billing and data-handling terms in PRIVACY.md.

• Explain Selected Code with AI sends only the explicit editor selection, the question, and the language identifier. It does not fall back to the whole file.
• Review Git Diff with AI lets you choose a workspace Git repository and either staged or unstaged changes. It obtains the patch from VS Code's built-in Git extension; untracked files are not included. The selected diff is limited to 24,000 characters, and the question is limited to 2,000 characters.
• Both commands show the exact provider message payload in a local editor document and require a separate modal approval before transmission. Editing the preview does not change the pending request; declining sends nothing.
• AI requests may include source code and file paths present in the selected diff. Only the explicit selection or selected Git patch is supplied; no additional workspace files or GitHub activity are collected.

Release process

The .github/workflows/release.yml workflow is manually triggered and creates a draft GitHub Release; it does not publish automatically. Before running it, a version tag must exist and match the version in package.json (for example, v0.0.1). The workflow checks out that tag, runs unit and Extension Host tests, runs ESLint, builds and inspects the VSIX, then attaches the package to a draft release with generated release notes. Review the draft and its asset before publishing it. Keep release history in CHANGELOG.md.

The draft-release workflow is a separate, manual release operation. Do not run it as part of the documentation or verification steps described here.

Security and privacy

See SECURITY.md for vulnerability reporting guidance and PRIVACY.md for the extension's current data-access, transmission, and retention disclosures. The privacy document describes the implementation as it exists today; review it before each public release if data flows change.

See CONTRIBUTING.md for development setup, test commands, implementation guidelines, and pull request expectations.

Dependency maintenance

Dependabot checks npm packages and GitHub Actions weekly, grouping related updates into manageable pull requests. TypeScript updates are constrained to the current typescript-eslint peer-supported range; review compiler and lint-tool compatibility before changing that policy. Review dependency changes and require the normal CI checks to pass before merging them.

Development

Requirements:

• Visual Studio Code 1.145.0 or later (manifest range: ^1.145.0)
• Node.js 22
• npm

Install dependencies and run the quality checks:

npm ci
npm run compile
npm run lint
npm run format:check
npm test

To launch the extension in an Extension Development Host, open this repository in VS Code and press F5.

Implementation notes

• The dashboard is a VS Code Webview with a restrictive Content Security Policy and scripts disabled.
• Local repository data comes from the built-in vscode.git API.
• GitHub sign-in comes from the built-in github authentication provider managed by VS Code.
• GitHub repository, pull-request, issue, and commit requests use the GitHub REST API. These services use only GET requests and do not run Git commands or shell out to Git.
• The pull-request, issue, and commit Quick Pick browsers request up to 100 records for one explicitly selected repository and open only validated GitHub HTTPS links.
• The dashboard activity panels support bounded pagination and show the selected repository context.
• GitHub API access is optional; the dashboard remains usable when GitHub repository access has not been granted.
• Local change insights use the built-in Git extension and VS Code workspace file APIs only. They do not use GitHub credentials, network requests, or shell commands.