Grass Local Coding Agent

Grass is a VS Code extension for controlled, local-first software maintenance. It combines a TypeScript VS Code extension with a self-hosted LangGraph/ReAct agent, file and shell tools, code retrieval, multi-layer memory, and optional compliance services.

This repository is the public edition. It contains one execution kernel implemented in this repository. Alternate competition-only integrations and vendor files are intentionally excluded.

What it does

• ReAct execution with list_files, grep_files, read_file, edit_file, create_file, and run_shell tools.
• Plan mode for complex tasks, with an approval checkpoint before execution.
• Project brief, rolling conversation compaction, lessons, code index, and semantic search.
• Local OpenAI-compatible model endpoints, including Lemonade, Ollama, LM Studio, and llama.cpp servers.
• Optional rule/ONNX compliance classification and embedding services with CPU, iGPU (DirectML), or NPU (VitisAI) providers.
• Capability-based authorization, audit logging, and optional identity/face-provider integrations.

Reliability boundaries

The agent is designed to make code-maintenance actions explicit and recoverable. Tool calls are checked by the execution layer, and file edits require a unique match. The workflow reads before writing, performs a pre-write validation, reads the result back, and rejects repeated or stale tool calls. A task must provide a concrete todo state and a verified finish result before the graph can terminate. These gates reduce hallucinated edits and false completion; they do not replace code review or tests.

Requirements

• Windows 10/11 and VS Code ^1.115.0.
• Node.js 18 or newer.
• A local OpenAI-compatible endpoint. The default is Lemonade at http://127.0.0.1:13305/api/v1.
• Python 3.10+ only when using the optional embedding/classifier services.

The reference hardware is AMD Ryzen AI Max+ 395. The extension itself does not directly drive hardware: Lemonade/llama.cpp owns LLM placement, while ONNX Runtime owns embedding and classification execution providers. CPU fallback remains available when an accelerator is missing or unstable.

Quick start

npm ci
npm run compile

Open this folder in VS Code and press F5 to launch an Extension Development Host. Set these settings in the development host when needed:

• grass.provider: local (default)
• grass.baseURL: your local OpenAI-compatible endpoint
• grass.model: the model name exposed by that endpoint
• grass.security.complianceMode: strict for local-only enforcement

To build a production VSIX:

npm run package

The generated VSIX is ignored by Git. Model weights, face data, and caches are never part of this repository; download them separately and point to them with environment variables such as GRASS_BGE_SNAPSHOT.

Optional Python services

tools/embed_server.py exposes /embed, /index, and /search. tools/classifier_server.py exposes compliance classification endpoints. Both print a dynamically selected port as PORT=<n> and degrade to CPU/rule execution when an accelerator or model is unavailable.

Install the Python dependencies in an isolated environment and set GRASS_EMBED_PYTHON if the interpreter is not on PATH. Set GRASS_EMBED_PROVIDER=cpu, dml, or vitisai according to the host. Do not commit model snapshots or provider configuration files.

Security and privacy

Strict mode accepts only loopback or RFC1918 endpoints and blocks accidental cloud fallback. API keys are read from VS Code settings and are not stored in source files. The public repository contains no model weights, face database, private keys, or competition user data. Review every shell command and file diff before applying it in a production environment; this is a research/competition prototype, not an unattended industrial-control system.

Project layout

src/                 Extension, LangGraph workflow, tools, memory, and webviews
tools/               Optional embedding and compliance HTTP services
resources/           Extension assets
docs/                Public documentation

License

The original Grass source in this repository is released under the MIT License. See THIRD_PARTY_NOTICES.md for dependency notices and their respective licenses.