Skip to content

Commit eb196a6

Browse files
tbitcsoz-agent
tbitcs
and
oz-agent
committed
docs: VS Code extension in README + readthedocs
Co-Authored-By: Oz <oz-agent@warp.dev>
2 parents 1806ec4 + 4d91ebc commit eb196a6

3 files changed

Lines changed: 227 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@
55
[![PyPI](https://img.shields.io/pypi/v/specsmith?label=stable&style=flat&color=blue&cacheSeconds=60)](https://pypi.org/project/specsmith/)
66
[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)
77
[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
8+
[![VS Code Extension](https://img.shields.io/badge/VS%20Code-AEE%20Workbench-4ec9b0?logo=visualstudiocode)](https://github.com/BitConcepts/specsmith-vscode)
89

910
**Applied Epistemic Engineering toolkit for AI-assisted development.**
1011

@@ -74,6 +75,27 @@ GPT, Gemini, and local Ollama models, with skills, hooks, and tool loops.
7475

7576
Every governed project follows: **propose → check → execute → verify → record**.
7677

78+
## VS Code Extension
79+
80+
The **specsmith AEE Workbench** VS Code extension brings the full specsmith workflow into your editor:
81+
82+
- **Multi-tab agent sessions** — one independent agent process per project, running in your right-side panel
83+
- **Live model listing** — fetches current models from Anthropic, OpenAI, Gemini, Mistral, and local Ollama with GPU-aware context sizing
84+
- **Ollama integration** — browse catalog, download models with progress, GPU VRAM detection, task-based model suggestions
85+
- **Governance Panel** (`Ctrl+Shift+G`) — scaffold.yml form editor, governance file status, quick actions (audit/validate/doctor), AI prompt palette
86+
- **API key management** — stored in OS credential store (Windows Credential Manager / macOS Keychain) via VS Code SecretStorage
87+
- **Projects sidebar** — full file tree + governance docs for each project, right-click to open agent session
88+
- **Chat history** — session history saved to `.specsmith/chat/`, replayed on re-open
89+
90+
```
91+
# In VS Code: Ctrl+Shift+P → specsmith: New Agent Session
92+
# Panel is on the right side (View → Open Secondary Side Bar)
93+
```
94+
95+
**[→ specsmith-vscode on GitHub](https://github.com/BitConcepts/specsmith-vscode)**
96+
97+
---
98+
7799
## Install
78100

79101
**Recommended — global install via [pipx](https://pipx.pypa.io) (isolated, no dependency conflicts):**

‎docs/site/vscode-extension.md‎

Lines changed: 204 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,204 @@
1+
# VS Code Extension — specsmith AEE Workbench
2+
3+
The **specsmith AEE Workbench** VS Code extension is the flagship client for specsmith. It provides multi-tab AI agent sessions, live model management, governance file editing, and full Ollama support — all inside VS Code's right-side panel.
4+
5+
**GitHub:** [BitConcepts/specsmith-vscode](https://github.com/BitConcepts/specsmith-vscode)
6+
7+
---
8+
9+
## Requirements
10+
11+
- VS Code 1.85+
12+
- specsmith v0.3.1+ installed and on PATH
13+
- At least one LLM provider (API key or local Ollama)
14+
15+
```bash
16+
# Install specsmith first
17+
pip install "specsmith[anthropic,openai,gemini,mistral]"
18+
# or
19+
pipx install specsmith
20+
```
21+
22+
---
23+
24+
## Installation
25+
26+
Install the extension from [the GitHub repository](https://github.com/BitConcepts/specsmith-vscode):
27+
28+
```bash
29+
git clone https://github.com/BitConcepts/specsmith-vscode
30+
cd specsmith-vscode
31+
npm install && npm run build
32+
# Press F5 in VS Code to launch the Extension Development Host
33+
```
34+
35+
!!! note "Marketplace"
36+
The extension will be published to the VS Code Marketplace. Until then, install from source as above.
37+
38+
---
39+
40+
## First Run
41+
42+
1. Open the **Secondary Side Bar** — `View → Open Secondary Side Bar` or `Ctrl+Alt+B`
43+
2. The **specsmith AEE** panel appears on the right
44+
3. Set your API key: `Ctrl+Shift+P → specsmith: Set API Key`
45+
4. Click **+** in the Sessions panel or press `Ctrl+Shift+;`
46+
5. Select your project folder — the agent starts automatically
47+
48+
---
49+
50+
## Features
51+
52+
### Agent Sessions
53+
54+
Each session is an independent `specsmith run --json-events` process with its own:
55+
56+
- Conversation history (saved to `.specsmith/chat/`)
57+
- Provider and model (remembered per project)
58+
- Token budget tracking with live context fill bar
59+
60+
When a session connects, it automatically runs the **start protocol**:
61+
sync → load AGENTS.md → read LEDGER.md → check for updates.
62+
63+
### Model Provider Support
64+
65+
| Provider | Free tier | Notes |
66+
|----------|-----------|-------|
67+
| **Anthropic** | No | Best for requirements engineering |
68+
| **OpenAI** | No (separate from ChatGPT sub) | GPT-4o, o3, o3-mini |
69+
| **Google Gemini** | Yes (generous limits) | Free key at [aistudio.google.com](https://aistudio.google.com/apikey) |
70+
| **Mistral** | Trial credits | Pixtral supports OCR |
71+
| **Ollama** | Yes (local, free) | GPU-aware; see [Ollama setup](#ollama-local-models) below |
72+
73+
API keys are stored in the **OS credential store** (Windows Credential Manager / macOS Keychain) via VS Code's SecretStorage — never in `settings.json`.
74+
75+
### Ollama — Local Models
76+
77+
The extension includes full Ollama integration:
78+
79+
```bash
80+
# From terminal — see available models for your GPU
81+
specsmith ollama available
82+
83+
# Download a model (also available via model dropdown in VS Code)
84+
specsmith ollama pull qwen2.5:14b
85+
86+
# Get GPU-aware model suggestions for your task
87+
specsmith ollama suggest requirements
88+
```
89+
90+
From VS Code:
91+
92+
- **Model dropdown** — shows `Installed` and `Available to Download` groups, GPU-VRAM filtered
93+
- Selecting an undownloaded model → download confirmation → progress notification with Cancel
94+
- `Ctrl+Shift+P → specsmith: Select Model for Task` — task-specific model recommendations
95+
96+
Context length is auto-detected from GPU VRAM:
97+
98+
| VRAM | Context |
99+
|------|---------|
100+
| < 4 GB | 4K tokens |
101+
| 4–8 GB | 8K tokens |
102+
| 8–16 GB | 16K tokens |
103+
| 16+ GB | 32K tokens |
104+
105+
Override with `specsmith.ollamaContextLength` in VS Code settings.
106+
107+
### Governance Panel
108+
109+
Open with `Ctrl+Shift+G` or the `📖` icon in the Projects toolbar.
110+
111+
The Governance Panel provides:
112+
113+
- **scaffold.yml form** — project type (all 33 types), platforms, agent integrations, VCS
114+
- **Governance file status** — ✓/✗ for REQUIREMENTS.md, AGENTS.md, LEDGER.md, TEST_SPEC.md, architecture.md
115+
- **Quick Actions** — audit --fix, validate, doctor, epistemic-audit, stress-test, export
116+
- **AI Prompt Palette** — 9 pre-written prompts sent to the active agent session
117+
118+
### Projects Sidebar
119+
120+
The Projects panel (right side bar) shows each project with:
121+
- `📋 Governance` folder — key spec docs with direct Open buttons
122+
- Full file tree (dirs-first, filtered for noise)
123+
- Right-click: New File, New Folder, Delete, Rename, Copy Path
124+
125+
### Keyboard Shortcuts
126+
127+
| Shortcut | Action |
128+
|----------|--------|
129+
| `Ctrl+Shift+;` | New agent session |
130+
| `Ctrl+Shift+G` | Open Governance Panel |
131+
| `Ctrl+Shift+R` | Quick add requirement |
132+
| `Ctrl+Shift+Q` | Navigate requirements (QuickPick) |
133+
| `Enter` | Send message |
134+
| `Shift+Enter` | New line in message |
135+
| `↑` (empty input) | Recall last message |
136+
| `@` (empty input) | Pick file to inject as context |
137+
| `Escape` | Stop agent |
138+
139+
### Chat Features
140+
141+
- **Drag & drop** — drop files or screenshots onto the chat to inject as context
142+
- **Paste images** — `Ctrl+V` pastes screenshots directly
143+
- **Copy message** — hover any message → `⎘` button
144+
- **Edit last message** — hover user message → `✏` button → puts back in input
145+
- **Regenerate** — hover agent message → `↺` button
146+
- **Export chat** — `⬇` button in header → saves as Markdown
147+
- **Clear history** — `🗑` button → clears display + JSONL files + agent context
148+
- **Resize input** — drag the teal handle above the input bar (drag up = bigger textarea)
149+
150+
---
151+
152+
## Configuration
153+
154+
All settings are under `specsmith.*` in VS Code settings (`Ctrl+,`):
155+
156+
| Setting | Default | Description |
157+
|---------|---------|-------------|
158+
| `specsmith.executablePath` | `specsmith` | Path to specsmith CLI. Auto-detected if not set. |
159+
| `specsmith.defaultProvider` | `anthropic` | Default LLM provider. Auto-selected if only one API key is set. |
160+
| `specsmith.defaultModel` | `` | Default model. Remembered per-project. |
161+
| `specsmith.ollamaContextLength` | `0` | Ollama context size. `0` = auto-detect from GPU VRAM. |
162+
163+
---
164+
165+
## Bridge Protocol
166+
167+
The extension communicates with specsmith via `specsmith run --json-events`:
168+
169+
```
170+
specsmith run --json-events --project-dir <dir> --provider <p> --model <m>
171+
↑ stdin: user messages (one line each)
172+
↓ stdout: JSONL events
173+
```
174+
175+
Event types: `ready`, `llm_chunk`, `tool_started`, `tool_finished`, `tokens`, `turn_done`, `error`, `system`.
176+
177+
This design means all AI logic lives in the Python CLI — the extension is a pure UI layer.
178+
179+
---
180+
181+
## Troubleshooting
182+
183+
**"specsmith not responding"** — The extension probes for a valid specsmith (>= v0.3.1) across all known paths. If it fails:
184+
185+
1. Run `Ctrl+Shift+P → specsmith: Install or Upgrade`
186+
2. Or set `specsmith.executablePath` to the full path of your installation
187+
188+
**"Ollama 404 — model not installed"** — The saved model for this project isn't in Ollama. Open the model dropdown and select from the **Installed** group.
189+
190+
**"Ollama not running"** — Start Ollama: run `ollama serve` in a terminal, or open the Ollama desktop app.
191+
192+
**API key 401** — Re-enter via `Ctrl+Shift+P → specsmith: Set API Key`.
193+
194+
**API key 429 (quota exceeded)** — Add credits at your provider's billing portal.
195+
196+
---
197+
198+
## Links
199+
200+
- [GitHub: specsmith-vscode](https://github.com/BitConcepts/specsmith-vscode)
201+
- [GitHub: specsmith](https://github.com/BitConcepts/specsmith)
202+
- [specsmith CLI reference](commands.md)
203+
- [Agentic client overview](agent-client.md)
204+
- [Ollama documentation](https://ollama.ai)

‎mkdocs.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -40,6 +40,7 @@ nav:
4040
- Agentic Client:
4141
- Overview: agent-client.md
4242
- Agent Integrations: agent-integrations.md
43+
- VS Code Extension: vscode-extension.md
4344
- Project Types: project-types.md
4445
- Tool Registry: tool-registry.md
4546
- Importing Projects: importing.md

0 commit comments

Comments
 (0)