band-aider-pub/FAQ.md

# Band-Aider FAQ

## What is Band-Aider?

Band-Aider is a local-first software-engineering system for small and local language models. It gives the model a narrow job, bounded files, selected evidence, and explicit validation instead of handing it an entire repository and hoping context size turns into engineering judgement.

It follows its own software-development lifecycle: discovery, scoping, source work, traceable testing, failure routing, test repair, graph stabilization, closure, and final validation.

## What problem is it designed to solve?

Band-Aider solves software problems inside repositories whose architecture and tests already provide usable evidence.

Its strongest work is refactoring and classical engineering bookkeeping:

- locating the true edit surface;
- tracing dependency ripple;
- preserving interfaces and local patterns;
- separating source changes from test changes;
- running the tests connected to changed code;
- deciding who owns a failure;
- tracking unfinished work until the graph closes;
- proving the repository remains stable afterward.

The model proposes and judges bounded changes. The harness remembers what has happened and what must happen next.

## Is it a general-purpose environment repair agent?

No.

Band-Aider can detect and report missing dependencies, collection failures, stale generated files, broken test commands, or an invalid baseline. It does not promise to repair every development environment as part of an unrelated software request.

The caller is responsible for providing the supported runtime, reproducible dependencies, normal test command, and a passing baseline. Otherwise the run gradually stops being software engineering and becomes digital archaeology, a field already tragically overstaffed.

## Who is it for?

As of July 2026, the supported production target is Python libraries and isolatable pure-Python modules or packages.

The best-fit repository has:

- a clean Git working tree;
- a passing baseline;
- separate source and test roots;
- standard, independently runnable `pytest` unit tests;
- useful coverage;
- reproducible dependencies and test commands;
- ordinary Python structure without monkey patching or hidden runtime mutation.

More language support and repository shapes are planned.

## Why does it work better with smaller models?

Band-Aider offloads the hard workflow and SDLC bookkeeping into a classical symbolic layer written in Python.

The model does not own the workflow, memory, retry policy, graph traversal, test routing, role permissions, stabilization frontier, checkpoints, or completion decision. Those live in deterministic, Turing-complete code. The model is asked narrower questions where approximate judgement is useful:

- Which files and structural beats are relevant?
- What bounded patch should be made?
- Does this failure belong to source, tests, or the environment?
- Is the current evidence sufficient?

This reduces the amount of architecture a small model must hold in free-form context at once.

## What model size is Band-Aider designed around?

The reference target is roughly a **26B-class model with about a 96k context window**. Capability varies by model family, quantization, runtime, and task, so the parameter count is a design center rather than a minimum requirement carved into a stone tablet.

Around **30B parameters** is usually the practical sweet spot between economy and capability for local use. Smaller models can work on well-scoped changes; larger models can handle more ambiguity and may be useful as escalation tiers.

Band-Aider supports other sizes through OpenAI-compatible endpoints. The harness does not require one named model, but weaker models will need stronger repository structure, better tests, narrower tasks, and more retries.

## How is the context budget divided?

For a model with about 96k of usable context, the reference operating profile is approximately:

- **60k tokens for input evidence and instructions;**
- **12k tokens for internal reasoning or thinking;**
- **4k tokens for the final generated answer or patch;**
- the remaining space as headroom for system wrappers, estimation error, tool or protocol overhead, and overflow safety.

These are planning targets, not a promise that every endpoint exposes or enforces the same internal partition. Reasoning budgets are model- and server-specific.

Band-Aider gives smaller models substantial reasoning room because they often need to reconstruct the problem from selected evidence rather than retrieve a memorized solution. On bounded engineering tasks, a smaller model allowed to reason deliberately can outperform a larger model forced to answer immediately. It can also finish competitively because token generation is a real runtime bottleneck and smaller models commonly decode faster. This remains hardware- and model-dependent, because reality occasionally refuses to fit in marketing copy.

## Where are the token budgets configured?

Band-Aider's process-wide token settings live in:

```text
band_aider/context/token_budget_state.py
```

The principal source constants are:

```python
DEFAULT_MAX_PROMPT_TOKENS
DEFAULT_MAX_OUTPUT_TOKENS
DEFAULT_TOKENS_PER_WORD
DEFAULT_BATCH_TARGET_RATIO
```

The current source ceiling and the recommended operating profile are not necessarily the same thing. In the source snapshot used for this FAQ, `DEFAULT_MAX_PROMPT_TOKENS` is `80000` and `DEFAULT_MAX_OUTPUT_TOKENS` is `15000`; those are harness limits, while the 60k input and 4k visible-generation figures describe the intended working envelope for a 96k model.

Runtime overrides are exposed by `band_aider/cli.py`:

```text
--max-prompt-tokens
--max-output-tokens
--tokens-per-word
```

The corresponding environment settings are:

```text
BAND_AIDER_MAX_PROMPT_TOKENS
BAND_AIDER_MAX_OUTPUT_TOKENS
BAND_AIDER_TOKENS_PER_WORD
BAND_AIDER_CONTEXT_BATCH_TARGET_RATIO
```

Internal reasoning or thinking allowance is normally configured at the model endpoint or inference server because OpenAI-compatible backends expose reasoning controls differently. Tune the harness ceilings and endpoint reasoning budget together so their combined use fits the actual model context window. Setting all knobs to the advertised maximum is the traditional route to discovering that advertised context and usable context are distant relatives.

## How does search work?

Search is hybrid.

Lexical anchors and a local semantic encoder narrow the candidate set first. A generative model then selects richer structural evidence from identified code beats. Symbolic dependency traversal follows the repository graph upstream and downstream so relevance is not based only on vocabulary or file proximity.

The expensive model is therefore used after cheaper lexical, semantic, and graph-based narrowing rather than as a full-repository search engine.

## Is Model2Vec optional?

No.

`model2vec==0.8.*` is a required runtime dependency and is installed with Band-Aider. It provides the local semantic narrowing layer used before more expensive generative selection. It is not an optional extras package and Band-Aider should not be documented or packaged as though the normal path falls back to having no local encoder.

The embedding-model cache can still require an initial download. Its default location is `${XDG_CACHE_HOME:-~/.cache}/band-aider/model2vec`, or the location selected by `BAND_AIDER_MODEL2VEC_CACHE_DIR`.

## What are structural beats?

A beat is an identified structural unit such as a class header, method, function, field, import region, or fallback source window.

The selector returns beat identifiers rather than copying source blocks back. Band-Aider resolves those identifiers to authoritative repository ranges and renders the source itself. This is faster and avoids trusting copied model text as evidence.

## How does progressive rendering work?

Small files and small combined scopes are rendered whole.

Large files inside a large scope begin with strict beat selection. Repeated exposure progressively loosens selection:

- strict;
- cautious expansion;
- generous expansion;
- recall-biased expansion;
- whole-file rendering after the compression cap.

The read count is intentionally a probabilistic proxy for insufficient context. It is not wired to every possible Alpha, Beta, editor, validator, and test failure edge because that coupling would be expensive, fragile, and still incomplete.

## What happens when local context is too small?

Band-Aider can advance through configured OpenAI-compatible model tiers. A run may begin on a local model and escalate to a larger local or cloud model when repetition, cycle detection, or context pressure requires it.

The cloud endpoint is optional. Local-first does not mean local-only.

## What are Alpha, Beta, and Stabilization?

Alpha owns source changes.

Beta owns test changes.

Stabilization runs traceable tests, collects failure evidence, decides whether a failure belongs to source or tests, and expands through the code and test graph until the current frontier is stable.

Keeping those roles separate prevents a model from repairing a source failure by casually rewriting the test that noticed it.

## Does Band-Aider run every test?

During stabilization, it runs every test traceable to the changed code. Before completion, it runs the full configured suite.

This assumes unit tests are genuinely unit-sized and cheap to run individually. A repository where hundreds of nominal unit tests each take minutes is outside the current operating contract, regardless of what the directory is named.

## What does graph closure mean?

Work ordering and completion are based on source and test dependency graphs.

Within the repository contract, Band-Aider keeps expanding reachable source, tests, failures, and dependent work until the frontier closes. The guarantee depends on the graph being observable. Monkey patching, generated modules, hidden runtime registration, or a broken baseline can hide edges that no static harness can honestly promise to recover.

## How are new features handled?

New feature work uses query inversion.

Instead of searching only for code that already matches the request, Band-Aider starts from the intended interface, usage, or test shape and works backward to the source structures and dependencies that must be created or changed.

## Why is Band-Aider suited to long refactors?

Long refactors fail differently from one-file edits. The early change is usually made with the full task in view; later edits are often made after the agent has compacted, forgotten, or conversationally mutated the original intent.

Band-Aider keeps the original job, COT task breakdown, workflow queues, source and test graph, file metadata, change history, and stabilization frontier outside the model. A later Alpha or Beta pass therefore receives its current bounded responsibility within the same persisted SDLC rather than becoming the tired final turn of one enormous chat.

That is where Band-Aider's bookkeeping is most valuable: multi-file refactors that take hours, require repeated targeted tests, and must remain equally rigorous on the first and last edit.

## Can I interrupt, save, and resume a run?

Yes.

Band-Aider writes repository-scoped save points and resumes them with:

```bash
band-aider --resume --repo-root /path/to/repo
```

The interactive launcher can detect existing save points and offer to resume them. Resume restores checkpointed workflow state, not merely the last conversation text.

The operator can also press F5 to request human intervention before the next AI call. Enter corrective guidance and press F8 to send it and resume, or press Escape to continue without adding guidance. This allows a human to redirect a long run while its graph, backlog, and original objective remain intact.

## How does it avoid getting stuck?

Band-Aider detects repeated model output and workflow cycles. It can broaden rendered evidence, escalate to another configured model, pause for human guidance, or accept an operator interrupt from the terminal UI.

Escalation is visible in the terminal UX rather than occurring as an invisible endpoint substitution. The operator can see that the run changed tiers and inspect the surrounding log evidence.

## What can I see while it runs?

The terminal UI shows the original task, active COT item, current loop, backlog, stabilization target and frontier, recent logs, token activity, and model escalation.

Its principal panes are scrollable. Tab or Shift-Tab changes focus; Up and Down scroll the focused task, backlog, COT, report, or log pane. The completion report can also be opened inside the terminal and scrolled without abandoning the main UI.

## How are logs organized?

Band-Aider splits logs along the same role and work hierarchy used by the SDLC. Supreme, stabilization, Alpha, Beta, file, and child-operation namespaces can be inspected separately, while the aggregate hierarchy gives a broad chronological view.

The terminal UI can filter logs by text, severity, and logger namespace. Once an operator develops an intuition for whether a failure belongs to search, Alpha, Beta, stabilization, rendering, or a particular file, the log view can be narrowed to that layer instead of treating the whole run as one swollen transcript.

The hierarchy is the user-facing contract. Python logger propagation is merely plumbing and should not be used as a metric for counting operations when the same record is intentionally visible through more than one view.

## What report does Band-Aider generate?

Band-Aider writes a Markdown change report at the end of a run and can present it in a scrollable terminal report view.

A successful report can look like this:

```text
Final summary: SUCCESS: Created report_ui.py, integrated it into TerminalUI
with navigation options, and added corresponding tests.

| Metric | Value |
| --- | ---: |
| Total tokens spent | 75,841,752 |
| Baseline tokens | 52,377,824 (69.1%) |
| Escalated tokens | 23,463,928 (30.9%) |
| LLM calls | 2,826 |
| Total operation time | 4h 50m 22s |
| Files modified | 4 |
| Files added | 2 |
```

The report then shows the original job, the COT task breakdown, and the resulting file ledger. The same run recorded three planned tasks: update TerminalUI completion handling, implement `ReportUI`, and preserve the established escalation-screen navigation pattern.

Its file section records not just the final diff surface but how each file moved through the workflow. A created source file, for example, can show:

```text
band_aider/ui/report_ui.py
Kind: source
Effect: created

CDC:
- Bootstrap preflight created a planned blank source.
- Bootstrap preflight registered temporary participant relevance.
- Implemented ReportUI and ReportUIState.
- Recorded the completed interactive report-view integration.
```

The final report contains:

- final summary and original job;
- total, baseline, and escalated token use;
- largest query, LLM-call count, LLM wait, total operation time, and COT timing;
- activity grouped into time buckets;
- baseline-versus-escalated usage and subtotals by model and endpoint;
- persisted COT tasks;
- files grouped by directory;
- file kind, effect, and summary;
- relevant symbols that justified the edit surface;
- CDC history showing bootstrap, implementation, and test-work events.

The report is deliberately capable of documenting failure too. A failed sibling run recorded 2,833 LLM calls, 75,864,420 tokens, and zero modified files rather than quietly converting motion into success. Humanity has invented enough dashboards that reward activity for its own sake.

Band-Aider favors economical targeted edits through narrowed search, scoped file roles, structural rendering, traceable tests, and selective escalation. The report lets the user verify whether the run lived up to that design.

## What token information is available?

Band-Aider reports and bins token use across prompts and model calls. Progressive rendering, context growth, cache use, and escalation are observable rather than hidden behind one aggregate bill.

Reports include totals, time buckets, baseline-versus-escalated use, and subtotals by model and endpoint. The live UX also surfaces token activity and escalation while the run is still recoverable, which is generally when humans prefer to discover that a machine has become extravagant.

## Can Band-Aider run tests and edit code in an isolated container?

Yes, but the container must already exist and be ready to run the project.

Band-Aider attaches to a persistent running container, edits the checkout on that instance, and performs discovery, git operations, and tests there. The caller must provide the repository, Python environment, dependencies, test runner, compilers, services, generated artifacts, and any other expected runtime.

The relevant flags are:

```text
--repo-container <running-name-or-id>
--repo-root <checkout-path-in-container>
--src-root <repo-relative-source-path>
--tests-root <repo-relative-test-path>
--repo-python-bin <optional-python-path-in-container>
--task <requested-change>
--resume
```

`BAND_AIDER_REPO_CONTAINER` can provide the container name to the launcher.

`--repo-root` is the checkout path inside the container. `--src-root` and `--tests-root` are relative to that checkout, just as they are in host mode. For `/workspace/project`, use `--src-root src` and `--tests-root tests`, not absolute paths.

Band-Aider uses `docker exec`; it does not create the container or repair its environment. The point is to isolate software work inside a runtime you control, not to turn the coding harness into a resentful infrastructure department.

## Does Band-Aider support SWE-bench?

Not fully, and SWE-bench is not the primary product contract.

SWE-bench is useful for public comparison and marketing, so the experimental adapter will remain useful. But many benchmark cases are historical repository snapshots with stale dependencies, baseline failures, unusual test runners, optional integrations, generated files, or tests whose cost and semantics no longer resemble a maintained production library.

Band-Aider targets almost the opposite environment:

- a short requested change;
- a potentially large architectural ripple;
- a clean and passing baseline;
- standard reproducible tests;
- inexpensive unit tests;
- current dependencies and maintained code.

SWE-bench asks whether a patch satisfies a later evaluator. Band-Aider asks whether a small model can complete a software-development lifecycle without damaging a repository whose architecture and tests are worth preserving. Those overlap, but they are not the same benchmark.

Band-Aider may identify the correct patch in a broken benchmark checkout and still refuse to call the repository stable. That is not useful leaderboard behavior, but it is fairly sensible software-engineering behavior.

## What repositories are poor fits today?

Poor fits include:

- a failing baseline;
- stale or unreproducible dependencies;
- tests mixed into the source package;
- monkey patching or runtime registration that hides dependencies;
- generated source required for import or collection;
- custom test semantics that ordinary `pytest` does not preserve;
- integration tests presented as unit tests;
- suites too expensive to run incrementally;
- applications that cannot isolate a pure-Python library or module boundary.

Band-Aider may still find the right edit in such repositories. It cannot make unreliable evidence become reliable by staring at it harder.

## Is Band-Aider local-only?

No. It is local-first.

Local OpenAI-compatible models can handle routine search, judgement, and patches. Configured escalation tiers can use stronger local models or cloud models through an OpenAI-compatible endpoint. The user controls those endpoints and credentials.

## What license applies?

Band-Aider's source release is licensed under **GNU AGPLv3**. The AGPL permits personal, hobby, open-source, and commercial use when its terms are followed, including the applicable source-availability obligations.

A separate commercial license is available for organizations or products that need proprietary use, closed-source modification, redistribution, network operation without AGPL obligations, or other terms outside the AGPL. Commercial licenses can be purchased at:

https://arpeggio.one/shop

This is a practical summary, not legal advice. Review the license text or obtain legal advice for a specific deployment.

## What is planned next?

The immediate priorities are configurable transitive inspection, UX modified/added file counts that largely match `git diff --stat` for the same baseline and scope, and **FastAPI + HTML + React together**. Full-stack support then extends to **Django**, followed by **pybind and C++**.

Longer term, investigate **horizontal scaling of intelligence**: independently deployable small-model workers on additional GPUs, coordinated by Band-Aider for parallel exploration and speculative generation. The direction includes GPU/session affinity and KV-cache reuse, heterogeneous models and selective escalation, transactional admission of combined patches, and scheduling around compute, energy, privacy, and completion time. Stronger local tie breakers remain part of the comparison.

The reported 3,430-call, roughly 31–32-hour capstone run measures one largely sequential local-model strategy. Future experiments hold the capstone and acceptance criteria constant while varying model capability, GPU/worker count, and escalation policy, tracking verified, accepted work per GPU-hour alongside total cost and completion time. The [development plan](docs/development-plan.md#20-horizontal-scaling-of-intelligence-and-inference-production--future) records the hypotheses and validation requirements. These are planned capabilities; horizontal scaling gains remain to be demonstrated.