Swival: A Coding Agent Built to Not Break on Small Models

What Is Swival

Swival is a CLI coding agent built by Frank Denis (jedisct1, creator of libsodium). Pure Python, no framework. 575 commits, actively maintained.

The tagline: “A coding agent for any model.”

Most coding agents — Claude Code, Codex, Hermes, Aider — are built and tested against frontier models with 128K+ context windows. They assume clean tool calls, reliable instruction following, and plenty of room. When those assumptions break, the agent falls apart in ways that look like the model’s fault but are really the agent’s.

Swival takes the opposite approach. It assumes the model will have tight limits and rough edges, then does the extra work to keep the task moving anyway.

Source: github.com/swival/swival

Provider Support

Swival connects to eight provider types out of the box:

The generic provider covers ollama, llama.cpp, mlx_lm.server, vLLM, DeepSeek API, and anything that speaks the OpenAI chat completions protocol. The command provider can even wrap codex exec or custom scripts as a backend.

Popular Models

Swival’s userbase skews toward smaller and local models:

Local (primary targets):

• Qwen3-Coder-Next — top recommendation, great quality/speed on consumer hardware
• Qwen3.5-35B-A3B — via vLLM or HuggingFace Endpoints
• Gemma 4 26B A4B — via llama.cpp (GGUF)
• Qwen3-Coder-480B-A35B-4bit — via mlx_lm.server
• Qwen3 32B — via ollama

Cloud:

• GLM-5 via HuggingFace or OpenRouter (note: z.ai’s non-standard URL path /api/coding/paas/v4 is incompatible — Swival auto-appends /v1 to the base URL)
• Gemini 2.5 Flash via Google
• GPT-5.4 via ChatGPT Plus/Pro (no API key needed — browser OAuth)
• Claude Opus 4.6 via AWS Bedrock
• DeepSeek Chat via DeepSeek API
• Qwen3-Coder-480B via NVIDIA NIM (generic provider — rate limit issues, see below)

The heavy Qwen3 bias makes sense — Qwen3 has strong tool-calling at small quantized sizes, which is exactly where Swival shines.

Installation

uv (Python 3.13+):

1
uv tool install swival
2
uv tool upgrade swival

Homebrew (macOS):

1
brew install swival/tap/swival
2
brew upgrade swival

No npm, no Docker, no binary download. Pure Python, minimal dependencies.

Quick Start

1
swival "Refactor the error handling in src/api.py"

1
export HF_TOKEN=hf_...
2
swival --provider huggingface --model zai-org/GLM-5 "Fix the bug in auth.ts"

1
# Start llama-server first
2
llama-server --reasoning auto --fit on \
3
    -hf unsloth/gemma-4-26B-A4B-it-GGUF:UD-Q4_K_XL
4

5
# Then connect
6
swival --provider llamacpp "Add input validation to signup endpoint"

1
export OPENAI_API_KEY="nvapi-..."
2
swival --provider generic \
3
    --base-url https://integrate.api.nvidia.com/v1 \
4
    --model qwen/qwen3-coder-480b-a35b-instruct \
5
    "Add input validation to the signup endpoint"

1
swival --provider generic \
2
    --base-url https://integrate.api.nvidia.com/v1 \
3
    --api-key "nvapi-..." \
4
    --model qwen/qwen3-coder-480b-a35b-instruct \
5
    "task"

1
swival --provider generic \
2
    --base-url http://127.0.0.1:8080 \
3
    --model my-model \
4
    "task description"

1
swival

1
swival -q < objective.md
2
cat prompts/review.md | swival --provider huggingface --model zai-org/GLM-5

Deep Dive: Context Management

This is where Swival diverges most from other agents. The entire system is designed around one reality: small models have tight context windows, and context management is the agent’s job, not the model’s.

Other Features

Review loop and LLM-as-judge. Configurable review loop that runs external reviewer scripts or uses a built-in LLM-as-judge to evaluate and retry output. Good for quality assurance on critical tasks.

Benchmarking reports. --report report.json writes machine-readable evaluation data: per-call LLM timing, tool success/failure counts, context compaction events, and guardrail interventions.

Secret encryption. --encrypt-secrets transparently detects API keys in LLM messages and encrypts them before they leave your machine. The LLM never sees real values. Decryption happens locally when responses come back.

Cross-session memory. Stores notes in a local memory file, retrieves relevant entries using BM25 ranking. Use /learn in the REPL to teach it something on the spot.

Session resume. When interrupted (Ctrl+C, max turns, context overflow), state saves to disk. Next run in the same directory picks up where it left off.

A2A server mode. swival --serve makes the agent an Agent-to-Agent endpoint other agents can call over HTTP. Multi-turn context, streaming, rate limiting, bearer auth built in.

Skills, MCP, and A2A. SKILL.md-based skills for reusable workflows, Model Context Protocol for external tools, Agent-to-Agent protocol for remote agent communication.

Prompt caching. Automatically marks the system message as cacheable for providers that support it (Anthropic, Gemini, Bedrock). Typically saves 30-60% of input token costs.

Swival vs Hermes Agent

When to use Swival:

• Running local models with tight context windows
• You want zero-config with LM Studio
• Benchmarking model performance on coding tasks
• You need secret encryption for API keys
• CLI piping workflows (swival -q < task.md | jq .)
• Using ChatGPT Plus/Pro without a separate API key

When to use Hermes:

• You need multi-platform delivery (Telegram, Discord, etc.)
• Subagent orchestration and parallel workstreams
• Background processes and cron scheduling
• Built-in browser automation
• Richer tool ecosystem (3000+ tests, vision, sandbox execution)

They’re complementary more than competing. Swival excels at the “run a local model on a coding task and get reliable output” problem. Hermes is a full agent platform with messaging, scheduling, and multi-agent coordination.

Profile Configuration

If you switch between providers regularly, use profiles:

1
[profiles.local]
2
provider = "lmstudio"
3
model = "qwen3-coder-next"
4

5
[profiles.gpt5]
6
provider = "chatgpt"
7
model = "gpt-5.4"
8
reasoning_effort = "high"
9

10
[profiles.hf]
11
provider = "huggingface"
12
model = "zai-org/GLM-5"

1
swival --profile local "quick task"
2
swival --profile gpt5 "hard task"

Switch mid-session in the REPL:

1
swival> /profile gpt5

Final Thoughts

Swival fills a real gap for local coding. Its entire architecture — 4-level compaction, durable state, bounded outputs, forgiving parsers — is built around the constraint that context is scarce and model outputs are imperfect. This is exactly the reality when running 8B-35B models locally.

Where Swival falls short is with cloud API providers. In our testing:

• z.ai — incompatible. Non-standard URL path (/api/coding/paas/v4) breaks Swival’s auto-appended /v1.
• NVIDIA NIM — technically works, but Swival’s multi-turn agent loop burns through NIM’s rate quota fast. Not practical on free tiers.
• Cloud LLMs via generic provider — Swival auto-prepends openai/ to model names, breaking providers that don’t recognize the prefix. Agentic tool calling becomes unusable.

The common thread: Swival’s generic provider isn’t truly generic. Between the forced openai/ prefix, the auto-appended /v1 on URLs, and the chatty agent loop, cloud API usage is fragile at best. This is fine when inference is local and free (LM Studio, llama.cpp, ollama). It becomes a problem when you’re paying per token or have rate limits.

Verdict: Swival is best suited for local coding with local models. If you have a GPU and run Qwen3, Gemma, or similar models locally, Swival is purpose-built for that workflow — zero config with LM Studio, auto-discovery, and context management that keeps small models on track. For cloud-based coding with API providers, agents like Hermes, Claude Code, or Codex are better suited due to their optimized prompt caching, fewer round-trips, and provider-native integrations.

At ~45 GitHub stars and 575 commits from a respected security engineer, it’s early but clearly serious. If you run local models for coding tasks and find other agents unreliable, Swival is worth a try.

Links:

• Repository: github.com/swival/swival
• Documentation: swival.dev
• Install: uv tool install swival (Python 3.13+)