Guidance for AI agents working in this repository.
VS Code extension: a Claude Code–style chat panel powered entirely by local LLMs (Ollama first, other OpenAI-compatible local backends later). Personal tool, not published to the Marketplace — iterate freely, no back-compat concerns.
Full product brief and build order: docs/_local/initial-prompt.md.
src/
extension.ts # activation, command registration
webview/ # chat panel UI (Preact)
chatPanel.ts # creates/manages the WebviewPanel, injects HTML
main.tsx # Preact entry point, mounted in the webview
App.tsx
richInput/ # contenteditable input with inline chip rendering + @ and / triggers
providers/
ModelProvider.ts # interface: send(messages) -> streamed tokens
OllamaProvider.ts # implementation for Ollama's /api/chat
context/
projectContext.ts # reads AGENTS.md, active file, selections
skills/
skillDiscovery.ts # finds SKILL.md files in known paths, parses frontmatter
skillCompletionProvider.ts # VS Code CompletionItemProvider for "/" trigger in the webview input
tools/
toolRegistry.ts # whitelisted read-only tools (git diff, git status, git log, file read)
executionStrategy.ts # decides native tool-calling vs deterministic fallback per model
config/
models.json # per-model capability flags (tool_calling: native|deterministic, reliable: bool)
extension.tsruns in the Node/CJS extension host context. Everything underwebview/is bundled separately for the browser context inside the WebviewPanel — the two never share runtime state directly, onlypostMessage.ModelProvideris the seam between the rest of the extension and any specific local backend. New backends (e.g. LM Studio) implement this interface; nothing outsideproviders/should assume Ollama-specific behavior.config/models.jsonis the source of truth for whether a model uses native tool-calling or the deterministic fallback. Unlisted models default to deterministic — never assume native tool-calling works for a model that hasn't been validated there.
- Package manager: pnpm (not npm/yarn).
- Bundler: esbuild (
esbuild.js), two entry points —src/extension.ts(Node/CJS) andsrc/webview/main.tsx(browser/IIFE). - UI: Preact with JSX (
jsxImportSource: preact), not React. pnpm run build— one-off build;pnpm run watch— rebuild on change.pnpm run lint(ESLint) andpnpm run format(Prettier) before considering a change done.- No test harness yet — add one (
@vscode/test-electron) when there's real logic to test (skill parsing, execution strategy selection), not preemptively.
main: scaffolding and stable milestones.development: active work, following the build order in the project brief (chat skeleton → context injection → rich input → skills → deterministic tools → native tool-calling).
Simple, one-line commit messages following Conventional Commits (feat:, fix:, chore:, docs:, etc.). No commit body, no co-author trailers.
- No autonomous agent loop. Tools are a fixed, whitelisted, read-only set per skill (
git diff,git status,git log, file read). No arbitrary shell execution, no automatic file editing, no unsupervised multi-step planning. - No cloud models. Local backends only (Ollama, and later other local/OpenAI-compatible servers).
- Keep context size assumptions modest — target hardware includes a 6GB VRAM box and 16–18GB unified-memory laptops. Don't design features that assume large context windows are always affordable.