Skip to content

Latest commit

 

History

History
62 lines (47 loc) · 3.79 KB

AGENTS.md

File metadata and controls

62 lines (47 loc) · 3.79 KB

AGENTS.md

Guidance for AI agents working in this repository.

Project

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.

Structure

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.ts runs in the Node/CJS extension host context. Everything under webview/ is bundled separately for the browser context inside the WebviewPanel — the two never share runtime state directly, only postMessage.
  • ModelProvider is the seam between the rest of the extension and any specific local backend. New backends (e.g. LM Studio) implement this interface; nothing outside providers/ should assume Ollama-specific behavior.
  • config/models.json is 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.

Build & tooling

  • Package manager: pnpm (not npm/yarn).
  • Bundler: esbuild (esbuild.js), two entry points — src/extension.ts (Node/CJS) and src/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) and pnpm 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.

Branching

  • 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).

Commits

Simple, one-line commit messages following Conventional Commits (feat:, fix:, chore:, docs:, etc.). No commit body, no co-author trailers.

Constraints (do not violate)

  • 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.