AIClerk — a harness designed for local AI

A lightweight planning agent that runs over your local codebase using Ollama or LM Studio as inference backend. The extension itself is <50MB of memory overhead (no bundled model) and delegates all inference to external servers running on your machine.

Features

• Structured Planning — /agent start creates a plan, the agent executes steps one by one with checkpoint/plan progress tracking
• Chat Panel — real-time conversation showing step progress, artifacts, and results
• Inline Completion — lightweight tab-completion using fast models while you edit
• Model Selection — automatically picks the best model per step type (planner-heavy for planning steps, coder-light for code-gen) or manually override

Installation

1. Prerequisites

Install one of these inference backends:

• Ollama — run ollama pull qwen2.5-coder:7b
• LM Studio — start the local server on port 1234 by default

2. Install this extension in VS Code

Open the Extensions view (Ctrl+Shift+X) and search for "AIClerk", or install from the .vsix package:

vsce package
code --install-extension aiclerk-0.1.0.vsix

3. Configure your backend

In VS Code Settings, set the following under AIClerk:

Setting	Default	Description
agent.modelProvider.type	ollama	Either ollama or lm-studio
agent.modelProvider.baseUrl	http://localhost:11434	URL of your inference server
agent.modelProvider.defaultModel	qwen2.5-coder:7b	Default model name

Usage

Start a new plan

Run the command palette (Ctrl+Shift+P) and type /agent start. You'll be prompted for a task description like "Build a data pipeline with DVC". The agent will generate steps, then execute them one-by-one.

Stop execution

/agent stop halts the current plan immediately.

Open the chat panel

AIClerk: Open Chat Panel shows the live view of your plan's progress and conversation history.

Model selection

Click Change model for next step in the sidebar to pick a different model. The agent will use it for all subsequent steps.

Architecture

package.json          # Extension manifest & settings schema
src/extension.ts      # Entry point (activate/deactivate)
src/orchestrator/     # Plan execution loop + model selection
src/llm-client/       # Ollama / LM Studio clients (mocked for tests)
src/context-builder/  # Prompt assembly per step
src/state-manager/    # Persistence: plan & checkpoint files
src/tool-registry/    # File I/O and shell commands
src/ui/               # Chat panel, sidebar, inline completion
artifacts/            # Generated artifacts (per-plan)
checkpoints.json      # Current execution state
agent-plan.json       # Active plan being executed

Development

# Run all tests
./test.sh

# Build and produce .vsix (tests must pass first)
./build.sh

# Watch mode (for active development)
npx tsc --watch -p ./

Memory Budget

Component	Memory
Extension process	~10–30 MB (TypeScript runtime + VS Code API overhead)
LLM models	Zero — they run in separate processes
Context per step	Bounded by agent.contextWindowTokens config (~8 KB default)

Future Evolution Points

• Multi-agent pattern (planner ↔ executor separate roles)
• Plan regeneration mid-execution if something fails
• Git-aware operations (commit per step, branch creation)
• Test execution integration after code-gen steps
• Context pruning for very long plans (>10 steps)
• Import/export plan history as JSON