Swival — A coding agent for any model
Description: Swival is a CLI coding agent built to be reliable with smaller models, including local ones. Designed from the ground up for tight context windows and limited resources. Works with LM Studio, HuggingFace, and OpenRouter.

# A coding agent for any model

Swival works with frontier models, but also strives to be as reliable as possible with smaller models, including local ones. Designed from the ground up for tight context windows and limited resources.
Free, opensource, and easy to set up.

$uv tool install swival
$swival "Refactor the error handling in src/api.py"

## Why Swival

### 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 model, or point it at any HuggingFace or OpenRouter model. 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.

### Skills, MCP, and more

Extend the agent with SKILL.md-based skills and MCP servers. Small and hackable: a few thousand lines of Python, no framework. Read the whole thing in an afternoon.

## Quickstart

### LM Studio

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

3. Run:

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

### HuggingFace

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

       export HF_TOKEN=hf_...

2. Install Swival:

       uv tool install swival

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

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

### OpenRouter

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

       export OPENROUTER_API_KEY=sk_or_...

2. Install Swival:

       uv tool install swival

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

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

## Interactive mode

For back-and-forth sessions, start the REPL with `swival --repl`. The agent keeps the full conversation in memory, so you can iterate on a task across multiple turns without repeating context.

    swival --repl

## Python library

Swival also works as a Python library, so you can embed an agent loop directly in your own code. The simplest way is the `swival.run()` one-liner:

    import swival

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

For multi-turn conversations or finer control, use the `Session` class:

    from swival import Session

    session = Session(provider="lmstudio", yolo=True)

    result = session.run("Add type hints to utils.py")
    print(result.answer)

    # Continue the conversation
    follow_up = session.ask("Now add tests for those functions")
    print(follow_up.answer)

`Session` accepts the same options you'd pass on the command line — provider, model, allowed commands, MCP servers, and everything else. Check the usage docs for the full list.