Nicolás Bruna
Selected work

Case study

SnapContext

AI context management for developers

Relevant project context, prepared automatically.

An open-source AI coding assistant that detects the project, selects the relevant files and prepares the context an AI workflow needs — with cloud providers or fully local models.

  • Open Source
  • Python
  • AI
  • CLI + IDEs
Scroll to the next section

The problem

An AI assistant can only work with the context it is given.

When I used AI coding assistants on real projects, the bottleneck was rarely the model. It was the context: which files the assistant could see. Hand the model the whole repository and small local models choke on files that do not fit the window; hand it nothing and it guesses.

Curating that list by hand does not scale. Attaching files manually before every request — the way Aider’s /add works — turns each task into a preparation ritual: remember the files, keep the list current, trim it again when the window overflows.

It gets worse with local models. A model running on your own machine often has a context window of a few thousand tokens, so sending whole files fails constantly — precisely the setup where automatic help is worth the most.

SnapContext was created to remove that preparation work: detect the project, find the relevant files and fit them into the context the model actually receives.

One command from project to prepared context.

SnapContext looks at the project the way a developer would: what stack is this, which files could matter for this request, what should the model actually see. The user starts from a task — describe a bug, request a change — and the context is built around it.

The goal is not to hide the model but to make the hand-off precise: relevant files and blocks instead of an unfiltered dump of the repository.

  1. Project

  2. Stack detection

  3. Candidate scan

  4. AI selection

  5. Prepared context

SnapContext is not a model. It prepares and manages context, then hands the work to a provider the user chooses — a cloud API or a local model through Ollama.

How it works

One request, one pipeline. Each stage exists because the next one needs it.

  1. Developer

    Describes a task or asks a question.

  2. Project

    The working directory is validated as a project root and the stack is detected from marker files: pubspec.yaml, package.json, pyproject.toml, go.mod, Cargo.toml.

  3. Scan

    Candidate files are listed — git ls-files when available, otherwise a directory walk — and ranked locally against the request before any model is involved.

  4. Select

    The configured AI provider chooses the most relevant files among the top-ranked candidates. A local heuristic mode covers requests without an API key.

  5. Shape

    Tokens are estimated, oversized files are reduced to their relevant blocks, and verbose tool output is pruned so the prompt fits the model’s window.

  6. Execute

    The ReAct agent works with that context: answering, planning, editing through the built-in editor or Aider, and running the project’s tests in a loop.

The same pipeline sits behind every interface: the CLI, the IDE extensions, the web UI and the messenger gateways.

Architecture

SnapContext sits between the development environment and the AI providers.

  1. Entry points

    1. CLI
    2. IDE extensions
    3. Web / TUI / API

  2. SnapContext core

    1. Project detection
    2. Context pipeline
    3. ReAct agent + planner
    4. Memory + history
    5. Permissions + sandbox

  3. AI providers (external)

    1. Gemini
    2. Claude
    3. Ollama
    4. DeepSeek
    5. Groq

  4. Execution

    1. Built-in editor / Aider
    2. Test loop
    3. Git

SnapContext is a layer between the developer’s environment and the AI providers. It understands the project, prepares the context, enforces permissions and memory, and delegates generation and execution to the selected provider and editor.

Technical decisions

Decisions that are visible in the way the project behaves.

  1. Context as an explicit pipeline

    Detection, scanning, selection and shaping are separate stages instead of one opaque prompt builder.

    Why
    A single prompt that dumps the repository breaks as soon as one file exceeds the window.
    Consequence
    Each stage can degrade independently: without git it walks directories, without tree-sitter it falls back to regex, without an API key it selects with local heuristics.

  2. Heuristics before the model

    Files are ranked locally against the request first; only the best candidates reach the selection prompt.

    Why
    The model’s job is choosing among plausible files, not reading the whole tree.
    Consequence
    Selection stays cheap and deterministic, works with local models and without API keys, and its cost does not grow with the size of the repository.

  3. Token-budget context

    Every file is measured before it is sent. Oversized files are reduced to their relevant blocks — extracted with tree-sitter when the language is supported — and verbose tool output is pruned to summaries.

    Why
    Local models often have windows of a few thousand tokens; whole files simply do not fit.
    Consequence
    Large codebases remain usable on small local models, and context-overflow errors from providers are detected and handled instead of crashing the run.

  4. An editor of its own, with backups

    SnapContext ships a built-in editor — validated writes inside the project, automatic backups — and keeps Aider as an optional alternative.

    Why
    Depending on an external tool for every edit made the base workflow fragile.
    Consequence
    Plans can commit step by step and changes can be undone per step with snapcontext revert.

  5. Autonomy behind permissions

    Approved actions persist in a permissions file, risky commands run in a Docker sandbox by default, and background processes without it are rejected.

    Why
    An agent that edits and executes code needs boundaries the user controls.
    Consequence
    Autonomous mode reuses the decisions the user already approved instead of asking again for each step.

What “context” means here

Four different things are called context in an AI workflow. SnapContext treats them as distinct stages.

  1. Source code

    Everything in the repository.

  2. Candidate files

    The subset the scanner considers relevant to the request.

  3. Selected files

    The files the provider chooses for this task.

  4. Relevant blocks

    Inside oversized files, the functions and classes that matter.

  5. Model input

    The shaped prompt that actually reaches the model.

Only the last stage is visible to the provider.

What SnapContext is

A context layer and an orchestrator: it prepares what the model sees, calls the provider, applies edits through its editor and keeps the memory of the project.

What it is not

It is not a model. Code is generated by the connected provider — Gemini, Claude, a local model through Ollama, or another OpenAI-compatible API.

Provider profiles adapt the prompt per model: cloud models receive fuller instructions, while local models get reduced context to stay inside smaller windows.

Where it runs

One core, several surfaces. All of them drive the same pipeline.

The CLI is the primary surface: snapcontext, snapcontext --chat, --plan, --tui. The installation is pipx or pip, the --init wizard configures the provider, and --demo runs without an API key.

The VS Code extension embeds the web chat in a webview, streams the orchestrator logs to an output channel, and adds an “Add to context” action in the explorer — the visual equivalent of /add.

The JetBrains plugin brings the same actions into IntelliJ IDEA and PyCharm: a Tools menu, a bottom tool window with live output, a settings page, and files added to the context from the project view. It expects the snapcontext CLI to be installed.

  • CLI
  • VS Code
  • JetBrains IDEs
  • Web UI
  • TUI
  • REST API
  • Discord
  • Telegram
  • GitHub
  • PyPI
  • VS Code Marketplace — link not available yet
  • JetBrains Marketplace — link not available yet

The VS Code and JetBrains marketplace listings are not public yet.

Windows, Linux and macOS are supported. Installers exist for all three, including a Windows executable without Python.

Where the project stands

SnapContext is published on PyPI and under active development. The labels below describe today, not the roadmap.

  • Automatic project detection

    Marker files and typical folders identify the stack before anything runs.

    In place

  • Repository scan and candidate ranking

    git-aware listing plus local scoring of files against the request, before any model is called.

    In place

  • AI file selection

    Provider-backed selection among ranked candidates, with a heuristic local mode.

    In place

  • Token-aware shaping and pruning

    Relevant-block extraction for oversized files and proactive pruning of tool output.

    In place

  • ReAct agent and planner

    Tool-driven reasoning loop, multi-step plans and an autonomous mode with retries.

    In place

  • Built-in editor and Aider support

    Validated writes with automatic backups, step commits and per-step revert.

    In place

  • Permissions and Docker sandbox

    Persistent approvals, default-deny sandboxing of risky commands, safe file writes.

    In place

  • Persistent memory

    Project memory (CLAUDE.md), SQLite history and a proactive curation daemon.

    In place

  • MCP client and plugin marketplace

    Built-in database, API and browser tools, plus third-party MCP servers.

    In place

  • Graph RAG and LSP analysis

    A code dependency graph and LSP-backed symbols, degrading to regex search when unavailable.

    In place

  • Interfaces and integrations

    CLI, TUI, web UI, REST API, VS Code and JetBrains extensions, Discord and Telegram.

    In place

  • Testing and benchmark

    A pytest suite with coverage gates, ruff and mypy, and a 50-task editing benchmark verified by AST.

    In place

  • Multi-repository Graph RAG

    Cross-repository indexing is a stated direction, not a shipped capability.

    In development

  • Intel XPU acceleration

    Local inference on Intel Arc GPUs exists behind an extra; broader hardware support is experimental.

    In development

  • Monolith decomposition

    The orchestrator and the messenger gateways are still being extracted into modules.

    In development

  • Editing benchmark, deep mode

    The full-agent benchmark with a local model is planned; the light engine benchmark is the one measured.

    In development

The benchmark measures the editing engine on synthetic tasks with AST verification, not general coding quality, and says so in the repository.

What building it taught me

Building SnapContext taught me that context is an engineering problem before it is an AI problem.

The original friction — attaching files to an assistant by hand — turned into work on project detection, repository scanning, token budgets, parser integration, safe file writes, sandboxing and permission systems. An assistant that edits code on its own is only trustworthy when everything around the model is explicit: what it may read, what it may run, and what happens when a component is missing.

  • developer tooling
  • IDE extension development
  • repository analysis
  • token budgets
  • parser integration
  • safe file writes
  • sandboxing
  • permission systems
  • graceful degradation
  • open-source maintenance

The hard part of an AI coding assistant is not the model — it is deciding what the model sees.

Built to remove friction from AI-assisted development.

SnapContext started as a simple annoyance: preparing context by hand, file by file, before every request. The answer was a tool that reads the project the way a developer does — and hands the model only what matters.

Back to selected work