An autonomous coding agent inside VS Code. Describe a task in the chat panel and the agent explores your codebase, edits files, runs commands, and shows every step as it works. It runs on local models (Ollama, LM Studio, llama.cpp, vLLM) or any OpenAI-compatible cloud endpoint (Hugging Face router, OpenRouter, …).
Documentation: kit.gramproindia.com/se-agent has the how-to guides, the architecture with diagrams, and a plain-English guide (PDF).
Requires VS Code 1.120 or later.
- In VS Code, open the Extensions view (Ctrl+Shift+X), search for GBS SE Agent, and click Install.
- Or run:
code --install-extension gbs-internal-toolchain.gbs-software-agent
Choose one of these:
- Local model (recommended): your code never leaves your machine. See Running local models.
- Cloud model: see Hugging Face, Groq, Google AI Studio, or any OpenAI-compatible endpoint.
- Open your project folder (File → Open Folder…) and trust it when VS Code asks. The agent stays disabled in Restricted Mode.
- Click the GBS Agent robot icon in the activity bar.
- Click the model chip under the chat input, and select your provider and model.
- Type a task, for example "Add input validation to the signup form and run the tests", and press Enter.
- Install Ollama. It runs in the background at
http://localhost:11434. If it isn't running, start it withollama serve. - Pull a model that supports tool calling, for example:
ollama pull qwen3-coder:30b # strong coding model, needs a capable GPU (~20 GB) ollama pull qwen2.5-coder:14b # good balance for mid-range GPUs ollama pull qwen2.5-coder:7b # runs on most laptops; also a good subagent model - In the chat panel's model menu:
- Provider: Ollama.
- Model: pick the model you pulled. The list is loaded from Ollama.
- Subagent model (optional): a smaller model for codebase exploration, which saves time and memory.
The default model is deepseek-v4-flash:cloud. Models whose name ends in :cloud or -cloud run on Ollama's servers, not your machine. Select a local model to keep everything on your machine. The model chip shows a cloud badge whenever a remote model is selected.
Memory: the agent asks Ollama for a 32K-token context window (gbsAgent.contextWindow). If a model runs out of memory or is very slow, set it to 16384. If you have plenty of VRAM, raise it for large tasks.
Any local server with an OpenAI-compatible /v1/chat/completions endpoint works. No API key is needed for localhost servers.
-
Start the server with a tool-calling capable model:
Server How to start Base URL LM Studio Load a model, then start the server in the Developer tab http://localhost:1234/v1llama.cpp llama-server -m model.gguf --jinja -c 32768(--jinjaenables tool calling)http://localhost:8080/v1vLLM vllm serve <model> --enable-auto-tool-choice --tool-call-parser <parser>(e.g.hermesfor Qwen)http://localhost:8000/v1 -
Open Settings (Ctrl+,), search for
gbsAgent.openai.baseUrl, and enter the server's base URL in your User settings. -
In the model menu, choose OpenAI-compatible and pick the model.
-
Set
gbsAgent.contextWindowto the context length the server was started with, so the agent compacts the conversation before it overflows.
The agent relies on the model calling tools (reading files, editing, running commands):
- Best: models trained for tool use, such as Qwen2.5/Qwen3 Coder, Devstral, gpt-oss, and Llama 3.1+.
- Other models: if a model rejects tool definitions, the agent automatically switches to a text-based tool format. This works, but less reliably.
- Size matters: very small models (under ~7B) often struggle with multi-step tasks.
Hugging Face's Inference Providers router puts hundreds of open models behind one OpenAI-compatible endpoint, billed through a single token. It is the extension's default cloud endpoint, so setup is a token and a model name.
- Open Access Tokens → New token — that link pre-selects the right options — or go to huggingface.co → your avatar → Access Tokens → Create new token → Fine-grained.
- Tick Make calls to Inference Providers. That single permission is all the agent needs; leave repository write access off.
- Create the token and copy it (it starts with
hf_). Hugging Face shows it once.
Run GBS Agent: Set API Key from the Command Palette (Ctrl+Shift+P) and paste it.
The token goes into VS Code's secret storage, never into settings.json and never into the repository. It is bound to
the endpoint it was saved for, so if you later point the extension at a different host, the extension asks before
sending the token there.
Two alternatives, in the order the extension looks for them: the deprecated gbsAgent.openai.apiKey /
gbsAgent.huggingfaceToken settings (plain text — avoid), then the HF_TOKEN or OPENAI_API_KEY environment
variables. The environment route is handy on a shared build machine where you don't want the token stored at all.
| Setting | Value |
|---|---|
gbsAgent.provider |
openai |
gbsAgent.openai.baseUrl |
https://router.huggingface.co/v1 (the default) |
Or just click the model chip under the chat input and choose OpenAI-compatible.
Open the model chip. With a token saved, the list is fetched live from the router's /v1/models, so you can pick from
what is actually being served; you can also type an id yourself.
The model must support tool calling — that is what lets the agent read files and run commands. Browse
models with a provider on the Hub, or try
one out first in the Inference Playground. Ids look like openai/gpt-oss-120b or
deepseek-ai/DeepSeek-R1.
You can append a suffix to the id to control routing:
| Suffix | Effect |
|---|---|
(none) or :fastest |
Highest throughput provider — the default |
:cheapest |
Lowest price per output token |
:preferred |
Your provider order from Inference Provider settings |
:groq, :together, :fireworks-ai, … |
Pin one specific provider |
For example, openai/gpt-oss-120b:cheapest.
Two settings worth adjusting after picking a model: gbsAgent.contextWindow, so compaction matches the model's real
context length, and gbsAgent.subagentModel, which can point exploration at a smaller, cheaper model.
Inference Providers has a free tier with monthly credits, more for PRO and Team accounts, and charges provider rates without a markup. The context meter shows tokens, not currency — check spend on the Hugging Face billing page.
The first time the agent would send code to a remote endpoint, it asks for confirmation, once per destination, and the model chip carries a cloud badge from then on.
Groq serves open models at very high speed and has the most usable free tier for agent work.
- Create a key at console.groq.com/keys.
- Set
gbsAgent.openai.baseUrltohttps://api.groq.com/openai/v1. - Run GBS Agent: Set API Key and paste the key.
- Open the model chip and pick a tool-calling model —
openai/gpt-oss-120bis a good default. The chip lists what your key can reach; the console shows the current catalogue.
Free tier at the time of writing: about 30 requests a minute and 1,000 a day on gpt-oss-120b. That is roughly
30–100 agent tasks a day (see How free tiers run out).
Gemini's Flash models are strong at tool calling and have the largest context of the free options.
- Create a key at aistudio.google.com/apikey.
- Set
gbsAgent.openai.baseUrltohttps://generativelanguage.googleapis.com/v1beta/openai/. - Run GBS Agent: Set API Key and paste the key.
- Pick a Flash-class model, for example
gemini-2.5-flash. Check AI Studio for newer Flash ids; the Pro models left the free tier in April 2026.
Free tier at the time of writing: roughly 10–15 requests a minute, 250 a day and 250k tokens a minute on Flash models — about 10–30 agent tasks a day.
Free tiers are usually advertised in tokens, but an agent is limited by requests. One instruction becomes many model calls: a small edit is three to eight, a refactor that uses subagents can be twenty to sixty. So a daily request cap matters far more than a token allowance, and a per-minute cap below about ten requests makes the agent feel stalled rather than slow.
| Endpoint | Requests/min | Requests/day | Notes |
|---|---|---|---|
| Groq | ~30 | ~1,000 | Best free fit; very fast |
| Google AI Studio | ~10–15 | ~250 | Large context, good tool use |
| Hugging Face router | Varies by provider | Credit-based | Free monthly credits; 429s when a provider is busy |
Ollama cloud (:cloud models) |
Account limits | Account limits | Stays on the Ollama provider — no endpoint change |
| Local (Ollama, LM Studio, llama.cpp) | Unlimited | Unlimited | The only option with no caps and no data leaving |
Two practical notes. Free tiers rate-limit hard, but a busy endpoint no longer ends the turn: a 429 or a 5xx is
retried three times with exponential backoff, honouring the server's Retry-After, and the status line shows the wait
(Esc cancels it). Only when the retries are exhausted does the turn stop. And the saved key is bound to
the endpoint it was saved for, so after changing openai.baseUrl you must run GBS Agent: Set API Key again and
confirm the new destination.
Anything OpenAI-compatible works the same way: set gbsAgent.openai.baseUrl to the provider's /v1 URL, run
GBS Agent: Set API Key, and pick a tool-calling model. That covers OpenRouter, Together, Cerebras, Azure OpenAI and
company-hosted gateways.
Before sending anyone's code to a cloud endpoint, check the provider's data policy — free tiers often carry weaker guarantees than paid ones, and some reserve the right to train on requests. For client code, local models avoid the question entirely.
Type what you want and press Enter (Shift+Enter for a newline). Treat it like briefing a colleague: say what should change and how you'll know it worked.
Add rate limiting to the login endpoint, 5 attempts per minute per IP, and make sure the auth tests still pass.
- The file you have open is attached automatically, along with any selected code. The chip above the input shows what will be sent; click the × to leave it out.
- Point at anything else with
@. Type@and a few letters to pick a file or folder from the workspace; its contents are attached to that message, so the agent starts where you meant instead of searching. Mention as many as you like — attachments are capped at twicemaxToolOutputCharsin total. - Paste a screenshot. Copy an image and paste it into the input to attach it (up to four per message). It is sent to the model as a picture, so this only helps with models that accept images — ask one that doesn't and it will say so. Screenshots stay in the live chat only; they are not written to workspace storage, so they disappear when the window reloads.
- You can keep typing while it works. Your message is delivered at the agent's next step, so you can redirect it without stopping: "actually, put it in middleware instead".
- Stop any time with Esc or the stop button. Finished edits stay; nothing is rolled back.
- On an empty chat, the suggestion buttons are a quick way to start (overview of the codebase, find bugs, write tests, refactor the selection).
Every step is visible, so you can catch a wrong turn early:
- Tool rows — one line per action:
Read src/auth.ts,Search "login",Run npm test. Click a row to see the full result, and a file name to open it. - Agent cards — when the task needs broad exploration, the agent delegates to subagents that search in their own context and report back. The card shows their progress and final report, so that bulk output never enters the main conversation.
- Live command output — long-running commands stream their output into the row as it appears.
- Task checklist — for multi-step work the agent keeps a plan above the input, ticking items off. If it stops early, the list is marked not finished.
- Thinking — models that expose reasoning get a collapsed Thought process section.
- The status line shows what's happening right now and how long the turn has taken.
Shell commands, and edits to files that run code or configure tooling, pause for approval. The card shows the full command (or a preview of the edit) plus warnings when a command chains several programs, reaches the network, redirects output, or contains invisible characters.
- Run / Allow — just this once.
- Always allow
npm test— remembers that command for the rest of the session. Not offered for risky or sensitive cases. - Deny — the agent is told and adapts instead of retrying.
The permission chip under the input switches the overall mode: Auto-edit (default), Ask first, or Full auto. See Security for what each mode still checks.
- Each turn ends with a summary: how long it took, tokens used, and every file changed with
+/−counts. - Undo this turn on that summary puts every file back the way it was before the turn started — restoring what was edited and deleting what was created. You are shown the list first, including anything you have edited since, and files you changed yourself are flagged before they are overwritten. The originals are held in memory for the window, so undo is unavailable after a reload.
- The diff icon opens VS Code's diff view comparing the file with its state before the turn.
- When a file is open in the editor, edits go through the editor buffer and are saved, so Ctrl+Z undoes them as usual. Files that aren't open are written directly — use the diff view or git to review those.
path:linereferences in the chat are clickable.- Code blocks have a copy button.
The meter next to the send button shows how full the model's context window is (hover for the session's token totals).
/compactsummarizes the conversation so far and frees space; useful when the meter turns orange./newstarts a fresh chat, which is cheaper than compacting when you switch to an unrelated task.- Past chats are under the chat title; use GBS Agent: Clear Chat History to delete them all.
- Set
gbsAgent.subagentModelto a smaller model so exploration runs cheaply.
AGENTS.md(orCLAUDE.md) at the project root is read on every request. Keep it short: build and test commands, conventions, things that are always true.- Skills are for bigger knowledge that only matters sometimes. See below.
A skill is a folder with a SKILL.md that teaches the agent something specific to your team or project: how to use your component library, the conventions of one service, the domain rules of an application. Skills stay cheap because only the name and description are always in the prompt (~45 tokens each); the instructions load when the agent decides they apply, and bundled reference files load only if the task needs them.
Run GBS Agent: New Skill, or create the folder yourself:
.gbs/skills/component-library/
├── SKILL.md # index: when to use it, the rules that matter
└── references/
└── forms.md # detail, loaded only when the task needs it
---
name: component-library
description: Builds UI with the GBS component library. Use when adding or changing UI in apps that import @gbs/ui.
autoAttach: ["src/**/*.tsx"] # optional: marks the skill relevant for these files
---
# Component library
- Tables: `DataGrid`, never a raw `<table>`.
- Forms: wrap every input in `FormField`.
- Import from `@gbs/ui`, never from `@gbs/ui/dist/*`.
Details: see references/forms.mdKeep SKILL.md under 500 lines and move the rest into files beside it, so a small task never loads your whole guide. Write the description so it says what it covers and when to use it — that one line is how the agent decides to load it.
| Location | Use for | Shared with |
|---|---|---|
.gbs/skills/ (or .claude/skills/) in the project |
This project's domain, conventions, requirements | Everyone who clones the repo |
A dependency that lists "gbsSkills": ["skills/<name>"] in its package.json |
A library shipping its own usage guide, versioned with the code | Everyone who installs the package |
Your personal skills folder (GBS Agent: Open Skills Folder, or gbsAgent.skillsPath) |
Habits, and company-wide skills you want in every project | Just you, unless that folder is a shared repo |
If the same name appears twice, the project wins over a package, and a package wins over your personal folder.
- The agent loads a skill by itself when the description matches the task; you'll see a
Skillrow in the transcript. /skillslists what's available, where each came from, and what the catalog costs per request. The skills chip under the input shows the count and offers Reload after you edit one.autoAttachglobs tell the agent a skill is relevant to the file you're in, which helps smaller local models pick the right one.- Skills from a repository or a dependency are instructions the agent will follow, so the first time a workspace offers them you're asked once. GBS Agent: Reload Skills asks again.
- A skill missing its
nameordescriptionis listed as invalid in the chip and never sent to the model.
An MCP server is a program that gives the agent extra tools, such as a component library that answers questions about its own API. The agent starts the servers you configure, lists their tools, and calls them when they fit the task. Only stdio servers (a command the extension starts) are supported so far.
Put it under mcpServers in .mcp.json at the project root. This is the same file Claude Code reads, so a server set up for Claude Code (for example with npx @grampro/kit mcp install) works here with no extra step:
{
"mcpServers": {
"grampro": { "command": "npx", "args": ["-y", "@grampro/kit", "mcp"] }
}
}| Location | Use for | Shared with |
|---|---|---|
.mcp.json in the project |
Servers the whole team should get | Everyone who clones the repo |
.gbs/mcp.json in the project |
Servers only for this agent (overrides .mcp.json by name) |
Everyone who clones the repo |
The gbsAgent.mcpServers user setting |
Servers you want in every project | Just you |
Each entry takes command, args, env, cwd (defaults to the workspace folder) and disabled. ${VAR} and ${VAR:-default} are read from the environment, which keeps tokens out of the file.
/mcp(or GBS Agent: Show MCP Servers) lists each server, whether it is running, and its tools. If one fails to start, the reason is shown once and the full error is in GBS Agent: Show Logs.- Tools appear to the model as
mcp__<server>__<tool>. Every call shows an approval card with the arguments, unless the permission mode is Full auto. Always allow covers that one tool for the rest of the session. - Servers from a repository run commands that the repository chose, so they start only after you allow them once per workspace. You are asked again if any of those commands change. GBS Agent: Reload MCP Servers restarts everything and asks again.
- Servers start on your first request and keep running until the window closes or the configuration changes. The first start of an
npx -yserver can take a while because it downloads the package. - An MCP tool can change files without going through the agent's edit review. Such changes are not part of the turn summary or Undo.
From the Command Palette (Ctrl+Shift+P):
| Command | What it does |
|---|---|
| GBS Agent: New Chat | Starts a fresh conversation |
| GBS Agent: Stop Agent | Stops the running agent |
| GBS Agent: Set API Key | Stores a key in secret storage, bound to the current endpoint |
| GBS Agent: Clear Chat History | Deletes all stored chats for this workspace |
| GBS Agent: New Skill | Scaffolds a skill folder and opens it |
| GBS Agent: Open Skills Folder | Opens your personal skills folder |
| GBS Agent: Reload Skills | Re-reads skills and asks again about repository skills |
| GBS Agent: Show Logs | Opens the log (requests, token usage, errors) |
| GBS Agent: Show MCP Servers | Lists MCP servers, their state and their tools |
| GBS Agent: Reload MCP Servers | Restarts MCP servers and asks again about repository servers |
In the chat input: /new, /compact, /skills, /mcp, /help.
- Approvals. In the default Auto-edit mode, ordinary source edits apply automatically. Shell commands need approval, except a few exact read-only ones (
git status,git log --oneline,dir, …). Edits to files that run code or configure tooling always need approval, unless you switch to Full auto. That includes.vscode,.git,.github,package.json, scripts, and linter/test/build configs. Reading likely credential files (.env, keys) also needs approval. - Settings a repository can't change. The provider, model, endpoints, API key, shell, and permission mode are only read from your User settings, so a project's
.vscode/settings.jsoncan't redirect your code or switch off approvals. - Your data. Local models keep your code on your machine. Remote endpoints and
:cloudmodels receive the files the agent reads. The saved API key is only sent to the endpoint it was saved for. Chats are stored in VS Code's workspace storage; use GBS Agent: Clear Chat History to delete them. - Treat repository content as untrusted. The agent is instructed to ignore instructions found in files and command output, but no model is immune to prompt injection. Read approval cards carefully, especially in unfamiliar repositories, and avoid Full auto there.
| Setting | Default | Purpose |
|---|---|---|
gbsAgent.provider |
ollama |
ollama or openai (any OpenAI-compatible server) |
gbsAgent.model |
deepseek-v4-flash:cloud |
Main agent model |
gbsAgent.subagentModel |
(empty) | Smaller model for exploration subagents |
gbsAgent.permissionMode |
acceptEdits |
ask, acceptEdits, or auto |
gbsAgent.ollama.baseUrl |
http://localhost:11434 |
Ollama server |
gbsAgent.openai.baseUrl |
https://router.huggingface.co/v1 |
OpenAI-compatible server (local or cloud) |
gbsAgent.contextWindow |
32768 |
Model context size; sent to Ollama as num_ctx and used to decide when to compact |
gbsAgent.maxOutputTokens |
8192 |
Max tokens per response |
gbsAgent.temperature |
0.2 |
Sampling temperature |
gbsAgent.maxSteps |
60 |
Model calls per request before the agent pauses |
gbsAgent.commandTimeoutSeconds |
120 |
Default shell command timeout |
gbsAgent.maxToolOutputChars |
20000 |
Tool results longer than this are truncated before the model sees them |
gbsAgent.shell |
(empty) | Shell for commands (default: cmd.exe on Windows, $SHELL elsewhere) |
gbsAgent.skills.enabled |
true |
Use skills at all |
gbsAgent.skillsPath |
(empty) | Your personal skills folder (default: the extension's own folder) |
gbsAgent.mcp.enabled |
true |
Start MCP servers and give their tools to the agent |
gbsAgent.mcpServers |
{} |
MCP servers available in every project, in .mcp.json format |
The provider, model, endpoints, permission mode, shell, skills path and MCP servers must be set in User settings. Values in a project's .vscode/settings.json are ignored for those. API keys belong in secret storage via GBS Agent: Set API Key; the older openai.apiKey and huggingfaceToken settings still work but are deprecated, and HF_TOKEN or OPENAI_API_KEY in the environment is used when nothing is stored.
- "Could not reach Ollama": start Ollama (
ollama serve) or checkgbsAgent.ollama.baseUrl. - Model not found (HTTP 404): run
ollama pull <model>, or pick a model from the model menu. - Hugging Face returns 401: the token is missing the Make calls to Inference Providers permission, or it was saved for a different endpoint — run GBS Agent: Set API Key again after changing
openai.baseUrl. - Hugging Face returns 402, or mentions credits: the monthly Inference Providers credits are spent. Add a payment method, wait for the reset, or switch the model chip back to a local model.
- A Hugging Face model id 404s: no provider is serving it right now. Check the model's page on the Hub, or pin a provider with a suffix such as
:groq. - The model menu is empty for OpenAI-compatible: the endpoint could not be listed — usually no token saved yet, or a base URL without the
/v1suffix. Type the model id manually meanwhile. - Slow or out of memory: use a smaller model, or lower
gbsAgent.contextWindowto16384. - The agent doesn't use tools or stops early: switch to a model trained for tool calling (see Which models work). For llama.cpp, add
--jinja; for vLLM, add--enable-auto-tool-choice --tool-call-parser <parser>. - A skill isn't being used: check
/skills— it may be invalid or not allowed for this workspace (Reload Skills re-asks). Otherwise make thedescriptionname the trigger words you actually use, or add anautoAttachglob for the files it applies to. - Skill edits aren't picked up: skills are read once per request; run Reload Skills or use the Reload button in the skills chip.
- Too many approval prompts: use Always allow for commands you repeat, and keep the mode on Auto-edit. Sensitive files always ask.
- The context meter is high: run
/compact, or/newif you're switching tasks. - Asked to send a saved API key to a local server: choose Cancel. Local servers don't need the key.
- Details of what happened: run GBS Agent: Show Logs.
To work on the extension itself:
git clone https://github.com/gramproindia/agent.git
cd agent
npm install
code .
- Press F5 to launch an Extension Development Host with the extension loaded. Rebuilds happen automatically through the watch task.
npm testruns the integration tests in a real VS Code instance.
See architecture.md for how the agent works, and CONTRIBUTING.md for the checks and review process. The user documentation lives in the GramproKit docs site, under docs-site/app/content/se-agent/ in gramproindia/kit.
Report vulnerabilities privately as described in SECURITY.md, never in a public issue.
MIT © 2026 Grampro India