Swival: a Python CLI coding agent tuned for small and local models
A small, powerful, open-source CLI coding agent that works with open models.
At a glance
- What is it?
- Swival is an MIT-licensed CLI coding agent that connects to LM Studio, llama.cpp, HuggingFace, OpenRouter, Gemini, Bedrock, ChatGPT Plus/Pro, or any OpenAI-compatible server. Its stated design goal is reliability with smaller and local models rather than peak capability with frontier ones.
- Who is it for?
- Swival is for engineers who already run models locally through LM Studio or llama.cpp and want an agent loop without writing provider plumbing themselves, and for anyone who needs one CLI that switches between a local server and a hosted endpoint by changing a single flag. It is not for teams that need a reviewed, versioned agent platform: releases land roughly weekly, the project is at 1.0.43, and the README does not describe a stability commitment or a support window.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 1 day ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The problem Swival is aimed at
Most coding agents are written against a single hosted API and assume a large context window. Swival starts from the opposite assumption. The README says it is built to be "as reliable as possible with smaller models, including local ones," and that it is "designed from the ground up to handle tight context windows and limited resources without falling apart." That is a concrete engineering target, not a marketing line: a tool loop that re-sends conversation history on every step will exhaust a small window quickly, and a model that emits malformed tool calls will derail the loop entirely.
The audience follows from that. If you run a quantized model in LM Studio or llama.cpp on a laptop or a single GPU box, you are the intended user. So is anyone who wants to point a coding agent at a self-hosted OpenAI-compatible server such as ollama, mlx_lm.server, or vLLM. The project also supports frontier providers, but that is a convenience rather than the reason it exists. If you already pay for a frontier model and have no interest in local inference, the design constraints Swival accepts buy you little.
One CLI, many providers, and a tool loop
The architecture visible in the README is a provider adapter layer plus an autonomous tool loop. Swival connects to a backend, sends your task, and per the README "runs an autonomous tool loop until it produces an answer." The provider list is unusually wide for a project this size: LM Studio, llama.cpp, HuggingFace Inference API, OpenRouter, Google Gemini, Gemini Enterprise Agent Platform (formerly Vertex AI), ChatGPT Plus/Pro, AWS Bedrock, Apple Foundation Models (marked experimental), any OpenAI-compatible server, and an external command provider.
The command provider is the interesting one. With --provider command --model "codex exec --full-auto", Swival shells out to another agent instead of talking to a model API. That turns Swival into a wrapper that can drive tools it has no native integration for, and it means the tool loop and the model loop are separable concerns in the design.
Auto-discovery is the other mechanism worth naming. With LM Studio and llama.cpp the README states that Swival auto-discovers your loaded model, "so there's nothing to configure." For llama.cpp the default base URL is http://127.0.0.1:8080, overridable with --base-url. The repository topics include mcp and a2a, which suggests Model Context Protocol and agent-to-agent integration are in scope, though the README excerpt does not document how either is configured, so treat that as unconfirmed from the material available.
Getting it running: real commands and config keys
Installation is a single uv command, and the README requires Python 3.13 or newer: uv tool install --python 3.14 swival. On macOS there is a Homebrew path, and the README is explicit that you trust the tap first: brew trust swival/tap, then brew install swival/tap/swival.
The fastest start needs no flags at all. Load a tool-calling model in LM Studio, start its server, and run swival "Refactor the error handling in src/api.py". Swival finds the model and connects. For llama.cpp, start llama-server with a model (the README shows llama-server --reasoning auto --fit on -hf unsloth/gemma-4-26B-A4B-it-GGUF:UD-Q4_K_XL), then run swival --provider llamacpp "...".
Hosted providers each take a provider flag, a model flag, and an API key from either an environment variable or --api-key. HuggingFace reads HF_TOKEN and takes --provider huggingface --model ORG/MODEL. OpenRouter reads OPENROUTER_API_KEY and takes --provider openrouter --model MODEL. Gemini reads GEMINI_API_KEY and takes --provider google --model gemini-2.5-flash. For enterprise Google Cloud, the geap provider uses Application Default Credentials instead of an API key and needs --gcp-project, --location, and --model; --provider vertexai is accepted as an alias. Anything else goes through --provider generic --base-url URL --model MODEL.
Configuration lives at ~/.config/swival/config.toml. Running swival with no arguments on a terminal triggers a setup wizard that writes a starter config there if none exists. swival --help is described as the grouped CLI reference with copy-paste examples.
Where Swival is the wrong tool
The honest limitation is the one the README implies rather than states. Swival's reliability with small models depends on the model emitting usable tool calls and on the context budget being large enough for the loop. The README tells LM Studio users to "crank the context size as high as your hardware allows," which is an admission that low context is the failure mode. If your GPU cannot hold a working context for the model you want, no amount of agent-side design fixes that, and the loop will truncate or stall partway through a task.
Second, the provider matrix is wide but shallow in places. Apple Foundation Models is labeled experimental in the README. The a2a and mcp topics appear on the repository but the README excerpt does not document their configuration, so you cannot plan around them from this material alone.
Third, this is a fast-moving 1.0.x project. Releases 1.0.41, 1.0.42, and 1.0.43 landed within roughly two weeks of each other in August and September 2026. That cadence is good for bug fixes and bad for anyone who wants to pin a version and forget it. If your workflow requires a frozen toolchain with a documented deprecation policy, the README does not offer one.
Finally, a CLI agent that runs an autonomous tool loop against your working tree is a different risk profile from a chat window. The README does not describe sandboxing, permission prompts, or a dry-run mode in the excerpt available, so do not assume any of those exist.
How it differs from Aider and from plain API scripts
Aider is the closest well-known comparison: a Python CLI coding agent that edits files in a git repository. The difference in approach is provider breadth and the target model class. Aider's documentation centers on frontier models and its own edit-format machinery for making models produce reliable diffs. Swival instead treats the backend as a pluggable adapter with auto-discovery for the two most common local servers, and states that small and local models are the primary design case rather than a supported fallback. If you are running a 7B to 30B quantized model, that stated priority is the reason to look at Swival first.
The other alternative is not a product but a pattern: a short Python script against the OpenAI SDK. That gives you total control and no dependency, and it is the right answer if your task is a single prompt and a single response. It stops being the right answer the moment you need a multi-step tool loop, provider switching, and model discovery, because you end up rebuilding exactly the adapter layer Swival already ships. The command provider makes this trade explicit: Swival can wrap an existing agent, so you can keep a tool you already trust and still get Swival's loop around it.
Licence, maintenance, and what upgrades cost you
Swival is MIT-licensed, which permits commercial use, modification, and redistribution provided the copyright notice and permission notice are preserved. That is a permissive licence with no copyleft obligation on your own code. This is a description of the licence text, not legal advice; if you are redistributing Swival inside a product, have your own counsel review the notice requirements.
The maintenance cost is the upgrade cadence. Three patch releases in about three weeks, with the most recent push dated 2026-09-10, means the project is actively maintained. It also means that if you pin a version, you will be behind within a month. The practical cost is not the upgrade itself but re-verifying that your provider configuration still behaves: a change to how auto-discovery talks to LM Studio or llama.cpp would be invisible until a task fails. The repository is not archived, and the homepage is swival.dev, where the fuller documentation lives. The README excerpt here is a quickstart, not a reference, so provider-specific edge cases (custom endpoints, proxy settings, credential chains for Bedrock) should be checked against swival.dev before you commit to a setup.
Editorial conclusion
Swival is for engineers who already run models locally through LM Studio or llama.cpp and want an agent loop without writing provider plumbing themselves, and for anyone who needs one CLI that switches between a local server and a hosted endpoint by changing a single flag. It is not for teams that need a reviewed, versioned agent platform: releases land roughly weekly, the project is at 1.0.43, and the README does not describe a stability commitment or a support window. Before adopting it, install with uv tool install --python 3.14 swival, run swival with no arguments to generate ~/.config/swival/config.toml, and confirm two things on your own hardware: that your chosen model actually emits tool calls, and that the context size you can afford is large enough for the tool loop to finish a real task.
Community notes