Capstone research project

A GitHub-specialized
AI coding assistant
for VS Code.

Name: OSCAR
Author: Aditya Sarade

OSCAR understands your repository. Compare branches, review PRs, analyze diffs, and run safe git operations from a sidebar chat — backed by a ReAct agent, persistent memory, and human-in-the-loop confirmation. Bring your own LLM: Gemini, OpenAI GPT-5, Claude 4, Groq, or local Ollama.

Get started Read the architecture

Asterix agent core
Gemini · GPT-5 · Claude · Groq · Ollama
FastAPI + SSE
TypeScript VS Code extension

oscar — interactive

OSCAR> compare main and feat/streaming
→ git_compare(base="main", head="feat/streaming")
  12 files · +428 / −96 · 3 commits ahead

Summary
─ Adds SSE-based streaming for /chat
─ Introduces confirmation broker for HITL gates
─ Test coverage extended in tests/test_api.py

OSCAR> review feat/streaming against main
→ git_review(branch="feat/streaming", base="main")
  risk: medium · 1 follow-up suggested

✓ Auth headers preserved across reconnects
✓ Confirmation broker is goroutine-safe
! Consider bounded queue for /chat/cancel race

OSCAR> _

2,308

lines of Python

tools registered

API endpoints

LLM providers supported

models in catalog

100%

safety-classifier accuracy

MIT

licensed

01 · System

Five layers, one agent loop.

OSCAR is a thin client and a deliberate backend. The VS Code extension is a chat surface; the FastAPI server brokers a ReAct loop that calls a small, focused set of git, shell, and web tools. Every effectful action passes through a safety layer before it touches your repository.

Client

VS Code extension TypeScript

Sidebar WebviewViewProvider, branch widget, HTTP/SSE client

activity-bar entry · webview chat UI
streamed responses · confirmation prompts
configurable oscar.serverUrl

Transport

FastAPI server Python

13 endpoints — /chat, /chat/stream, /branches, /compare, /review, /history, /memory, /metrics, /status, /providers, plus confirm/cancel and health

SSE for token-level streaming
broker pattern for confirmation gates
/metrics surfaces Gemini latency, tokens, and audit-log aggregates

Agent

OSCAR agent layer Asterix runtime

ReAct loop, persistent memory blocks, tool dispatch, lifecycle callbacks

on_before_tool_call · safety + confirmation
on_after_tool_call · audit logging
asterix_patch.py bridges Vertex AI Gemini to Asterix

Tools

Registered capabilities

Small, composable functions exposed to the LLM via Asterix tool registration

git_status
git_compare
git_review
git_log
git_diff
git_branches
git_checkout
git_commit
git_push
run_shell_command
web_search
browser_navigate / _search / _extract / _download

Model

Multi-provider LLM pick any backend

One env-var switch (OSCAR_LLM_PROVIDER / OSCAR_LLM_MODEL) routes every chat call to the model you choose. Configurable primary + fallback. Vertex AI ADC is used for Gemini by default — no API key ships in the binary.

Gemini · 2.5 Flash · 3.5 Flash · 3.1 Pro preview · 2.5 Pro · 2.5 Flash-Lite
OpenAI · GPT-5.4 mini · GPT-5.5 · GPT-5.4 · GPT-5.4 nano · o3 · o4-mini · GPT-4.1 · GPT-4o
Anthropic · Claude Opus 4.8 · Sonnet 4.6 · Haiku 4.5 · Opus 4.7 (legacy)
Groq · Llama 3.3 70B · Llama 3.1 8B (LPU inference)
Ollama · Llama 3.3 · Qwen 2.5 Coder · DeepSeek Coder v2 · Mistral Nemo (fully local)

02 · Capabilities

What the agent can actually do.

OSCAR is intentionally narrow. It does git well, shell carefully, and the web sparingly — and everything passes through a single risk classifier before it runs.

Branch comparison

Symmetric diffs between any two refs with LLM-summarized changes, ahead/behind counts, and per-file impact.

git_compare(base, head)

PR-style review

Branch-against-base review with file-level callouts, risk assessment, and follow-up suggestions in plain prose.

git_review(branch, base)

Safe shell execution

Allowlisted commands, cross-platform translation (POSIX ⇄ PowerShell), timeouts, working-directory isolation.

run_shell_command(cmd)

Browser + web search

Headless Playwright for navigate / extract / download. Tavily for keyword search with dual-key fallback for rate limits.

browser_* · web_search

Human-in-the-loop safety

Every tool call is classified low / medium / high. Low auto-approves, medium prompts, high requires a typed CONFIRM.

on_before_tool_call → broker

Persistent memory

Asterix memory blocks: session context, knowledge base, user preferences. Inspectable via /memory.

agent_states/*.json

03 · Results

Measured, not marketed.

Two kinds of numbers below: surface area read straight from the repository at v0.4.0, and evaluation numbers from the in-repo bench harness at bench/run_bench.py. The eval is scoped to what OSCAR actually does — not SWE-bench-style end-to-end patching, which is out of scope.

Surface area

Backend (Python)	2,308 LOC
Tools registered	15 (9 git · 4 browser · 1 shell · 1 web search)
HTTP endpoints	13
LLM providers / models	5 / 26 catalogued
SSE event types	6 (`step`, `confirm`, `response`, `error`, `cancelled`, `done`)
VS Code modules	4 (.ts, 508 LOC)
Test functions	15 across 3 suites

T4 — Safety classifier

Labelled cases	20
Overall accuracy	100% (20/20)
Dangerous tier	P 1.00 · R 1.00 · 5 cases
High tier	P 1.00 · R 1.00 · 4 cases
Medium tier	P 1.00 · R 1.00 · 5 cases
Low tier	P 1.00 · R 1.00 · 6 cases

Safety model

Risk tiers	4 — low / medium / high / dangerous
Dangerous regexes	8 patterns
Shell allowlist	22 safe commands
Confirmation	broker over SSE · typed `CONFIRM` for dangerous
Audit	JSONL · `risk` + `approved` + `latency_ms` per call
Bypass	none in production code path

Runtime

Primary LLM	Gemini 2.5 Flash · Vertex AI (default; any of 5 providers selectable)
Auth	ADC for Gemini · per-provider API key for OpenAI/Anthropic/Groq
Streaming	Server-Sent Events
Python	≥ 3.10 · CI matrix 3.10/3.11/3.12
Memory budget	3 Asterix blocks · 8,000 tokens
License	MIT

Live telemetry · GET /metrics

LLM latency	mean ms per Gemini call (running total)
Token usage	cumulative input + output tokens per provider
Tool distribution	per-tool call count from `audit.jsonl`
Risk histogram	low / medium / high / dangerous · per-call
Gate firing rate	approved vs. rejected by safety classifier
Per-call latency	tool-execution ms · mean · median · p95 · max

Reproducing the bench: python bench/run_bench.py --offline runs the T4 safety track without LLM credentials. python bench/run_bench.py additionally runs T3 (tool selection accuracy) and T5 (latency + token + cost) once Vertex AI is authenticated. Each run writes bench/results/<UTC>/summary.json.

04 · Positioning

Where OSCAR sits in the landscape.

OSCAR is not the largest agent, nor the most general. The matrix below is a qualitative comparison drawn from each system's public documentation — it describes shape, not winners.

Capability	OSCAR	MemGPT	AIOS	OSAgent	ReAct	Claude Code
Git-specialized tool surface	●	—	—	—	—	◐
VS Code sidebar UI	●	—	—	—	—	—
Bring-your-own LLM (5 providers)	●	◐	◐	—	—	—
Persistent memory blocks	●	●	◐	—	—	◐
ReAct-style reasoning loop	●	◐	●	●	●	●
Human-in-the-loop confirmation	●	—	—	—	—	●
Tiered risk classifier	●	—	—	—	—	◐
Local-only by default	●	●	●	●	●	—
Open source (MIT)	●	●	●	●	●	—

● present · ◐ partial · — absent or out of scope

05 · In use

What a session looks like.

OSCAR is designed to be operated in plain English. Below are the same queries as they arrive over /chat and the tool calls they expand into.

You say

“Show me what's changed on feat/streaming vs main.”

OSCAR runs

// risk: low · auto-approved
git_compare(base="main", head="feat/streaming")

You say

“Commit these changes and push.”

OSCAR runs

// risk: high · CONFIRM required
git_commit(message="feat: streaming responses")
git_push(remote="origin", branch="feat/streaming")

You say

“Find an example of FastAPI SSE with cleanup.”

OSCAR runs

// risk: low · auto-approved
web_search(query="FastAPI SSE EventSource cleanup")
browser_extract(query="cancellation pattern")

06 · Quick start

Three steps to a working agent.

OSCAR runs locally. The Vertex AI auth step is the only external dependency; everything else is on your machine.

Clone & install

# requires Python ≥ 3.10
git clone https://github.com/adityasarade/OSCAR.git
cd OSCAR
pip install -e .
playwright install chromium

Pick your LLM

# Default — Gemini via Vertex AI Application Default Credentials
gcloud auth application-default login

# Or set OSCAR_LLM_PROVIDER / OSCAR_LLM_MODEL in .env and add the API key
# OSCAR_LLM_PROVIDER=anthropic   OSCAR_LLM_MODEL=claude-sonnet-4-6   ANTHROPIC_API_KEY=...
# OSCAR_LLM_PROVIDER=openai      OSCAR_LLM_MODEL=gpt-5-mini          OPENAI_API_KEY=...
# OSCAR_LLM_PROVIDER=ollama      OSCAR_LLM_MODEL=llama3.3            # local, no API key

Optional: set TAVILY_API_KEY1 / TAVILY_API_KEY2 in .env for web search. Run oscar providers for the full model catalog.

Run it

# interactive CLI
oscar

# or start the backend for the VS Code extension
oscar-server

07 · Built with

Boring tools, on purpose.

Every dependency is here because it earns its weight. Nothing is wrapped, nothing is hidden.

AgentAsterix 0.2.1
LLMsGemini · OpenAI · Anthropic · Groq · Ollama
SDKsgoogle-genai · openai · anthropic · ollama
APIFastAPI + Uvicorn + SSE
BrowserPlaywright (chromium)
SearchTavily
CLIClick + Rich
ExtensionTypeScript · VS Code 1.85+
ValidationPydantic 2
Testspytest + httpx

08 · Author

Built by Aditya Sarade.

Final year B.Tech, Department of AI & Data Science, AISSMS Institute of Information Technology, Pune. OSCAR is the engineering side of a capstone that also includes a survey paper positioning it against MemGPT, AIOS, OSAgent, and ReAct.

Source on GitHub Asterix framework

A GitHub-specializedAI coding assistantfor VS Code.

VS Code extension TypeScript

FastAPI server Python

OSCAR agent layer Asterix runtime

Registered capabilities

Multi-provider LLM pick any backend

Branch comparison

PR-style review

Safe shell execution

Browser + web search

Human-in-the-loop safety

Persistent memory

Clone & install

Pick your LLM

Run it

Built by Aditya Sarade.

A GitHub-specialized
AI coding assistant
for VS Code.