Valstorm Agent for Developers & Engineers
A technical guide covering the ReAct loop, developer toolbelt, LSP diagnostic feedback, multi-provider routing, and CLI workflows.
vsagent is a standalone, local-first AI engineering runtime and CLI companion designed for monorepo development, automated testing, and enterprise operations.
It executes an autonomous ReAct (Reason + Act) loop that bridges large language models directly with your local shell, file tree, compiler diagnostics, and backend APIs.
š The Core ReAct Architecture
Traditional LLM integrations are stateless: you send a prompt, you get a string back.
vsagent uses an event-driven ReAct execution engine (core/react.py):
āāāāāāāāāāāāāāāāāāāāāāāāā
ā User Prompt ā
āāāāāāāāāāāāā¬āāāāāāāāāāāā
ā
āāāāāāāāāāāāāāāāāāā¼āāāāāāāāāāāāāāāāāā
ā LLM Step Generation ā
ā ā¢ Emits Thought & ToolCall ā
āāāāāāāāāāāāāāāāāāā¬āāāāāāāāāāāāāāāāāā
ā
āāāāāāāāāāāāāāāāāāā¼āāāāāāāāāāāāāāāāāā
ā Tool Execution Engine ā
ā ā¢ Sandbox Dispatch & LSP Check ā
āāāāāāāāāāāāāāāāāāā¬āāāāāāāāāāāāāāāāāā
ā
āāāāāāāāāāāāāāāāāāāāāāāā“āāāāāāāāāāāāāāāāāāāāāāā
ā¼ ā¼
[More actions needed] [Task Complete]
Observation fed back to LLM Final Answer RenderedTurn Lifecycle & Telemetry
Every turn tracks:
- Token telemetry: Input, output, and cumulative tokens per message and session.
- Duration & Execution Latency: Per-tool execution timing in milliseconds.
- Payload Size & Truncation: Automatic protection buffers ensuring oversized outputs don't blow out the context window.
š§° The Developer Toolbelt
vsagent exposes high-performance software engineering tools:
| Tool Name | What It Does | Key Capabilities |
|---|---|---|
patch_file | Atomic targeted find-and-replace | Generates unified diffs, enforces unique string matching, runs live LSP checks. |
write_file | File creation & overwrite | Creates parent directories automatically, atomic write via temp files, runs live LSP checks. |
read_file | Budgeted line reading | 1-indexed line numbers with pagination offset and limit guards. |
search_files | Ripgrep / Regex grep & file search | High-speed native rg search ignoring .git, node_modules, and build artifacts. |
terminal_exec | Async shell execution | Non-blocking subprocess execution with timeout and output windowing. |
execute_code | In-process Python runtime | Runs multi-step scripts with pre-bound tool helpers in a single turn. |
ā” Live LSP Compiler Diagnostic Loop
One of the biggest problems with coding agents is that they frequently introduce subtle syntax errors, missing imports, or broken types.
vsagent solves this with an in-memory Language Server Protocol (LSP) and compiler feedback loop (core/lsp/):
1. Agent invokes `patch_file("apps/api/main.py", ...)`
2. Tool writes changes to disk atomically.
3. LSP engine runs immediate background diagnostics (<100ms for AST/JSON/YAML, <1.5s for TypeScript/Go/Rust).
4. If errors are found, they are appended directly to the tool output:
Successfully patched apps/api/main.py.
[LSP Compiler Diagnostics]:
- Line 42: Type error: Argument 'tenant_id' cannot be None (expected str).
- Line 48: NameError: 'datetime' is not imported.
5. The agent immediately self-corrects on Turn 2 before running any tests!š Universal Model Freedom & BYOK
vsagent is not locked to a single model provider. It supports native adapters (Gemini, Claude, OpenAI) and any OpenAI-compatible API endpoint (DeepSeek, Groq, Moonshot/Kimi, Mistral/Codestral, and local Ollama):
1. Cloud Providers:
# Set your API keys
vsagent keys set deepseek sk-your-key
vsagent keys set groq gsk-your-key
vsagent keys set anthropic sk-ant-your-key
# Chat with specific models
vsagent chat --provider deepseek --model deepseek-chat
vsagent chat --provider groq --model llama-3.3-70b-versatile
vsagent chat --provider anthropic --model claude-3-7-sonnet-202502192. Local & Zero-Telemetry Mode (Ollama / vLLM):
Run completely private models offline on Apple Silicon or Linux GPUs with $0 API cost and zero telemetry transmission:
# Start Ollama with Qwen 2.5 Coder
ollama run qwen2.5-coder:32b
# Connect vsagent directly to localhost:11434
vsagent chat --provider ollama --model qwen2.5-coder:32bāŖ Transactional Git Snapshots & /undo
Before executing any file mutation, vsagent creates an internal Git working-tree snapshot. If an agent refactor goes off track, you can revert it immediately:
[developer] > /undo
ā Successfully rolled back working tree to turn #3 checkpoint.This restores all modified files to their exact pre-turn state and trims the conversational turn from memory.
š Standard CLI Commands
# Interactive Chat REPL with a specialized role
vsagent chat --profile developer
vsagent chat --profile researcher
vsagent chat --profile architect
# Single-Shot Task Execution
vsagent run "Inspect apps/api and run the pytest suite"
vsagent run --provider deepseek "Refactor database query logic in apps/api"
# Status & Keys Management
vsagent status
vsagent keys list
vsagent keys set gemini <KEY>
# Memory & Skills
vsagent memory list
vsagent memory add "Prefers uv for Python dependencies" --target memory
vsagent skills list
vsagent skills show systematic-debugging