Skip to content

# A coding agent for any model

Works with frontier models, but also strives to be as reliable as possible with smaller models, including local ones. Designed for tight context windows and limited resources. Free, open-source, and easy to set up.

Get Started Read the Docs
$uv tool install swival
# or on macOS: brew trust swival/tap && brew install swival/tap/swival
$swival "Simplify the error handling in src/api.py"

Works with your stack

LM Studio llama.cpp HuggingFace OpenRouter Google Gemini Vertex AI ChatGPT AWS Bedrock Any OpenAI‑compatible

## Why Swival

Built for the reality of small context windows, limited resources, and models that need careful prompting to produce good output.

### Reliable with small models

Context management is one of its strengths. Keeps things clean and focused, avoids unnecessary context bloat. Graduated compaction and persistent state mean the agent doesn't lose track of work, even under tight limits.

### Your models, your way

Auto-discovers your LM Studio or llama.cpp model, or point it at HuggingFace, OpenRouter, Google Gemini, Vertex AI, ChatGPT Plus/Pro, AWS Bedrock, or any OpenAI-compatible server. You pick the model and the infrastructure.

### Review loop and benchmarking

A configurable review loop with LLM-as-a-judge support. JSON reports capture timing, tool usage, and context events. Useful for comparing models, settings, skills, and MCP servers on real coding tasks.

### Secrets stay on your machine

Enable `--encrypt-secrets` and API keys and credentials in LLM messages are encrypted before they leave your machine. The model never sees the real values. Decryption happens locally when the response comes back, so tools still work normally.

### Cross-session memory

The agent remembers things across sessions. Relevant past notes are retrieved via BM25 ranking, so context from earlier work carries forward without bloating the prompt. Use `/learn` to teach it on the spot.

### Autonomous security audits

Run `/audit` and Swival scans your codebase for provable security bugs. Findings are verified by isolated agents in separate worktrees that must reproduce each issue before it reaches the report. Very few false positives, just real bugs with patches.

### A2A and ACP

Run `swival --serve` to expose the agent as an A2A endpoint other agents can call over HTTP, or `swival --acp` to drive Swival from ACP-aware editors like Zed and `agent-client-protocol.nvim`.

### Skills, MetaSKILLs, and MCP

Extend the agent with SKILL.md-based skills, dynamic workflows written in a safe Python subset via MetaSKILLs, and MCP servers. Small and hackable: pure Python with no framework. Easy to read and modify.

## Built for the long run

Two things we obsess over so the agent can stay focused on your task instead of the environment around it.

### Context that survives compaction

Pre-flight pruning, graduated compaction, and persistent think / todo / snapshot state mean the agent keeps working through long sessions — even on small models with tight context windows. Learn how →

### Safety you can actually configure

Workspace-only file access by default, command whitelists, OS-level sandboxes via AgentFS or nono, and format-preserving secret encryption. Read the guide →

## Get started in seconds

Pick your provider and run your first task.

1. Install LM Studio and load a model with tool-calling support. Recommended first model: qwen3-coder-next (great quality/speed tradeoff on local hardware). Start the server.
2. Install Swival:

       uv tool install swival

   or on macOS:

       brew trust swival/tap
       brew install swival/tap/swival

3. Run:

       swival "Simplify the error handling in src/api.py"

1. Start `llama-server` with a model (`--fit on` auto-sizes context, `-hf` downloads from HuggingFace):

       llama-server --reasoning auto --fit on \
           -hf unsloth/gemma-4-26B-A4B-it-GGUF:UD-Q4_K_XL

2. Install Swival:

       uv tool install swival

   or on macOS:

       brew trust swival/tap
       brew install swival/tap/swival

3. Run (model is auto-discovered):

       swival --provider llamacpp "Simplify the error handling in src/api.py"

1. Create a token at huggingface.co/settings/tokens and export it:

       export HF_TOKEN=hf_...

2. Install Swival:

       uv tool install swival

   or on macOS:

       brew trust swival/tap
       brew install swival/tap/swival

3. Run with a tool-calling model (e.g. GLM-5):

       swival "Simplify the error handling in src/api.py" \
           --provider huggingface --model zai-org/GLM-5.2

1. Sign up at openrouter.ai and export your API key:

       export OPENROUTER_API_KEY=sk_or_...

2. Install Swival:

       uv tool install swival

   or on macOS:

       brew trust swival/tap
       brew install swival/tap/swival

3. Run with any model on the platform (e.g. GLM-5.2):

       swival "Simplify the error handling in src/api.py" \
           --provider openrouter --model z-ai/glm-5.2

Swival also works with ChatGPT Plus/Pro (uses your existing subscription via OAuth), Google Gemini, the Gemini Enterprise Agent Platform (Vertex AI, with Google Cloud ADC), AWS Bedrock, and any OpenAI-compatible server (ollama, mlx_lm.server, vLLM, etc.). See all providers.

### Interactive mode

For back-and-forth sessions, just run `swival` with no arguments. The agent keeps the full conversation in memory, so you can iterate on a task across multiple turns.

    swival

### Python library

Embed an agent loop directly in your own code. The simplest way is `swival.run()`:

    import swival

    answer = swival.run(
        "What files handle authentication?",
        provider="openrouter",
        model="z-ai/glm-5.2",
    )

For multi-turn conversations, use the `Session` class — see the Python API docs.

## Benchmark and evaluate

Run evals with Calibra — Swival's companion for benchmarking and evaluation. Compare models, settings, skills, and MCP servers on real coding tasks.

## Get started in one command

Install Swival, point it at any OpenAI-compatible model, and ship a real change in minutes. No telemetry, no signup, no lock-in.

Get Started Star on GitHub