SFE is a context-routing layer for AI-assisted coding. It selects relevant project context, routes execution modes, and isolates filesystem changes in Git worktrees before promotion.

Instead of sending broad project context into every coding call, SFE narrows the executor prompt to the files and constraints that matter for the current task. On selected benchmark fixtures, SFE significantly reduced executor input tokens compared with full-context baselines.

Output-token cost can also be lowered by delegating execution to a cheaper or more specialized model once the context is already narrow. Savings depend on task shape, provider behavior, and model choices.

SFE: Context Control for AI Coding

SFE turns a coding request into a controlled run. It routes the task, selects the relevant files and constraints, gives the executor a bounded working context, and verifies the result before completing.

flowchart TB
    T["User task"] --> M["Route task"]
    M --> D["Find relevant files<br/>and constraints"]
    D --> B["Bounded working context"]
    B --> E["Executor edits files"]
    E --> V["Verify result"]

    V -->|passes| OK["Completed run"]
    V -->|needs retry| R["Targeted retry task"]
    R --> E
    V -->|no progress| S["Stop with clear reason"]

    classDef input fill:#f8fafc,stroke:#64748b,stroke-width:2px,color:#0f172a
    classDef control fill:#eff6ff,stroke:#2563eb,stroke-width:2px,color:#0f172a
    classDef context fill:#ecfdf5,stroke:#059669,stroke-width:2px,color:#052e1a
    classDef loop fill:#fffbeb,stroke:#d97706,stroke-width:2px,color:#3b2600
    classDef success fill:#f0fdf4,stroke:#16a34a,stroke-width:2px,color:#052e16
    classDef stop fill:#fff1f2,stroke:#e11d48,stroke-width:2px,color:#3b0a0a

    class T input
    class M,D,V control
    class B,E context
    class R loop
    class OK success
    class S stop

Loading

What SFE Does

• Builds a compact project map and selects task-relevant files.
• Routes a task to read-only answers or isolated code changes. Tasks outside the local workspace are rejected.
• Runs write tasks in isolated Git worktrees before promoting changes.
• Can verify completed write runs with bounded Real Loop retries when a verifier is available.
• Uses Aider as the default external writer for normal workspace_write runs.
• Exposes the same runtime through a local TUI and an MCP server.

Why Not Just Run Aider Directly?

Aider is the writer. SFE is the routing and guard layer around it.

Aider already has its own repository map and token controls. SFE does not replace that. It adds a pre-execution layer that selects task-specific context, chooses the execution mode, and prepares an isolated Git worktree before Aider writes.

Run Aider directly when you already know the files, scope, and write mode. Use SFE when you want context selection, model-role separation, read/write routing, isolated filesystem changes, and a compact run report before deciding what to keep.

Benchmark snapshot

On controlled benchmark fixtures, SFE showed stronger amortization as context size increased.

Router-inclusive input reduction observed:

Tier	OpenAI	Anthropic	Alibaba/Qwen
standard [2k-5k tokens]	21.71%	19.09%	19.77%
practical [10k-20k tokens]	63.40%	62.01%	62.29%
high_context [20k-50k tokens]	73.38%	72.02%	72.34%
structural [50k+ tokens]	84.08%	83.63%	83.57%

These are controlled observations, not production guarantees.

See Benchmarks for the full provider table, executor-visible reductions, and claim boundary.

Quick Install

Requirements:

• Python 3.10+
• Git
• Aider for normal write runs: pipx install aider-chat

git clone https://github.com/Patrice-Gaudicheau/sfe.git
cd sfe
make install
make doctor
make sfe-tui

make install installs SFE locally in .venv with pip install -e .. It reuses an existing .venv, creates .env from .env.example when needed, and never overwrites an existing .env. If Aider is missing, the installer can install it with pipx install aider-chat after confirmation, or you can run that command manually. Makefile targets use the project virtualenv automatically.

First Run

Configure a provider by editing .env, uncommenting one SFE_PROVIDER, and filling the required key or local provider URL. make doctor reports whether a provider appears configured.

Start the TUI:

make sfe-tui

Then run a task:

Workspace: /path/to/your/project
/task Add a small README usage section
/run

Basic TUI Commands

• /task <text> sets the current task.
• /run routes and executes the task.
• /run-report shows diagnostics for the previous run without running again.
• /status shows workspace and provider state.
• /context shows selected context summaries.
• /quit exits.

How It Works

1. SFE reads the task and current workspace.
2. The router chooses an execution mode.
3. Discovery selects a bounded set of relevant files.
4. For write tasks, SFE creates or reuses an isolated Git worktree.
5. The configured writer runs inside that isolated workspace.
6. SFE promotes the resulting changes back to the source repository.

Real Loop

Real Loop is SFE's bounded verifier path for completed /run workspace_write attempts. After a write run completes, SFE can ask a verifier whether the workspace state satisfies the original task. If the verifier reports an incomplete or incorrect result and provides a useful correction, SFE may run a narrower retry task instead of repeating the original request.

Real Loop does not keep retrying indefinitely. It is limited by SFE_REAL_LOOP_MAX_ITERATIONS, which counts the original write attempt plus any retries. SFE stops on verifier pass, blocked or abort verdicts, no meaningful progress, duplicate retry task, repeated failure, a failed retry attempt, or the configured attempt limit.

flowchart LR
    E["Executor result"] --> V["Verifier"]
    V -->|pass| C["Complete"]
    V -->|needs retry| R["Targeted retry task"]
    R --> E
    V -->|retry cap, no progress,<br/>duplicate retry, or blocked| S["Stop with reason"]

Loading

Real Loop is a guard and recovery path, not a guarantee that the final code is correct. Review the final diff before keeping, committing, or publishing changes.

See Real Loop for the current behavior and configuration.

Safety Model

SFE is a local developer tool, not a sandbox boundary.

It does provide practical guardrails:

• write tasks run through the isolated workspace_write path;
• source changes are prepared in .sfe-worktrees/ before promotion;
• absolute paths, parent traversal, and internal repository paths are rejected;
• .env and common secret-like files are excluded from normal context loading;
• reports avoid raw provider payloads and secret values.

You should still review diffs before publishing code.

Minimal Provider Configuration

Set one shared provider:

SFE_PROVIDER=openai
OPENAI_API_KEY=...

Or split roles:

SFE_PROVIDER_ROUTER=openai
SFE_PROVIDER_DISCOVERY=openai
SFE_PROVIDER_EXECUTOR=anthropic

For Aider-backed writes, set SFE_AIDER_PROVIDER when SFE itself uses codexcli; Aider cannot use CodexCLI as its LLM backend. Set SFE_AIDER_MODEL when your executor model name is not already a valid Aider/LiteLLM model name, for example openai/Gemma-4-E4B-it-GGUF for Lemonade.

See Configuration for provider variables and local provider notes.

Documentation

• Install
• Usage
• Configuration
• Architecture
• Real Loop
• Benchmarks
• FAQ
• Documentation index

Current Status And Limitations

SFE is a practical public edition of an evolving local developer tool. The current workflow is strongest for local repositories, explicit coding tasks, and provider configurations you control.

Known limits:

• Aider is external and required for normal write execution.
• Provider quality and model compatibility vary by role.
• The router can add overhead on small tasks.
• Worktree isolation helps with review and promotion, but it is not a security sandbox.
• Benchmark observations are limited to selected fixtures and local runs.