ArchForge AI for VS Code

ArchForge AI is a VS Code extension for asking architecture-focused questions about code directly from the editor. It provides a sidebar chat view and an editor context-menu command for sending highlighted code to the hosted ArchForge AI backend.

Current Features

• Architecture Chat view in the VS Code Activity Bar.
• ArchForge: Ask AI about this code editor command.
• Highlighted-code context in questions.
• Full active-document context when no text is selected.
• Markdown-style rendering for headings, emphasis, inline code, and code blocks.
• Hosted HTTPS backend integration.

Requirements

• VS Code 1.85.0 or newer.
• Network access to https://api.archforge.hbhanot.tech.
• A running hosted ArchForge backend with the extension chat endpoint enabled.

The extension does not require the backend .env file on the user's machine. Gemini and other AI credentials remain on the ArchForge backend and must never be placed in the extension.

Install From VSIX

From the repository root:

cd archforge-vscode
npm install
npm run compile
npx vsce package

This creates a file similar to archforge-vscode-0.0.1.vsix.

Install it with the VS Code CLI:

code --install-extension archforge-vscode-0.0.1.vsix

Or use Extensions in VS Code, open the ... menu, select Install from VSIX..., and choose the generated file.

Development

cd archforge-vscode
npm install
npm run compile

For continuous compilation:

npm run watch

To debug the extension, open the archforge-vscode folder in VS Code and press F5 to launch an Extension Development Host. The current repository does not yet include a dedicated .vscode/launch.json configuration.

Usage

1. Open a source file in VS Code.
2. Highlight the code you want to discuss.
3. Right-click and select ArchForge: Ask AI about this code.
4. Open ArchForge AI from the Activity Bar if the sidebar is not visible.
5. Enter a question and select Ask AI. Press Enter to submit or Shift+Enter for a new line.

If no code is selected, the extension sends the entire active document as context. The current command requires a selection to open the sidebar; the sidebar itself can use the active document when no selection is present.

Backend Contract

The extension sends a POST request to:

https://api.archforge.hbhanot.tech/api/v1/extension/chat

Request body:

{
  "code": "selected or active-document source code",
  "question": "the user's architecture question"
}

Expected successful response:

{
  "answer": "AI-generated response"
}

The backend may return an error response containing an error field.

Architecture

• src/extension.ts registers the command and the sidebar webview provider.
• src/chatProvider.ts renders the webview, reads editor context, sends HTTPS requests, and displays responses.
• out/ contains compiled JavaScript generated by npm run compile.
• package.json declares the VS Code command, Activity Bar container, sidebar view, and build scripts.

Known Limitations

• The backend URL is hard-coded; there is no user or workspace setting for a custom server.
• The extension endpoint currently has no visible extension-specific authentication flow.
• The chat request uses the active editor or selected text only. It does not query the user's indexed ArchForge project or workspace graph.
• Requests have no explicit timeout or cancellation handling.
• HTTP status codes and malformed successful responses are not handled with detailed diagnostics.
• Chat history is held only in the webview and is not persisted.
• The generated webview uses a small custom Markdown renderer rather than a complete Markdown parser.
• There is no automated extension test suite or checked-in VS Code launch configuration.
• package.json still needs marketplace packaging metadata such as publisher before publishing to the VS Code Marketplace.

Improvement Plan

Phase 1: Release Reliability

1. Add publisher, repository metadata, icon, keywords, and a VS Code-compatible license declaration to package.json.
2. Add .vscodeignore so source maps, development dependencies, and unnecessary files are excluded from the VSIX.
3. Add .vscode/launch.json and a package script for repeatable local packaging.
4. Add a CI workflow that installs dependencies, compiles the extension, packages the VSIX, and runs tests.
5. Add an activation smoke test covering command registration, view registration, and webview message handling.

Phase 2: Configuration and Security

1. Replace the hard-coded host with an archforge.apiUrl setting and default it to the hosted API.
2. Add a secure authentication flow using VS Code Secret Storage; never store tokens in settings or source code.
3. Protect the backend extension route with authentication, rate limiting, request-size limits, and structured logs.
4. Add request timeouts, cancellation support, retry rules for transient failures, and useful status messages.
5. Make the webview error states distinguish network errors, authentication failures, server errors, and invalid responses.

Phase 3: Better Editor Experience

1. Pass language ID, file path, workspace name, and selection range as optional context.
2. Fix the command flow so highlighted code is explicitly preserved when the sidebar opens.
3. Add loading, cancel, empty-state, and connection-status UI states.
4. Persist chat history per workspace with ExtensionContext.workspaceState.
5. Add commands for asking about the current file, workspace architecture, and selected code.

Phase 4: ArchForge Workspace Intelligence

1. Add a backend endpoint that identifies the active ArchForge project for the current workspace.
2. Send a repository or project identifier with each chat request.
3. Reuse the backend's indexed IR, graph, and embeddings instead of treating every question as an isolated code snippet.
4. Add architecture actions such as dependency explanation, impact analysis, symbol lookup, and HLD generation.
5. Add streaming responses so longer answers appear progressively.

Phase 5: Productization

1. Add telemetry only with clear consent and avoid collecting source code in analytics.
2. Add accessibility checks for keyboard navigation, focus management, contrast, and screen readers.
3. Add internationalization support if the extension will serve multiple language communities.
4. Publish signed VSIX releases through a tagged CI workflow.
5. Document privacy, data retention, supported languages, backend availability, and troubleshooting.

Troubleshooting

Check the Output panel and select the extension host logs if the sidebar does not load. Confirm that the hosted API is reachable:

curl https://api.archforge.hbhanot.tech/health

The expected health response contains:

{
  "status": "ok",
  "service": "archforge-api"
}