Swival

https://swival.dev
Admin
Swival is an open-source coding agent designed to reliably execute software engineering tasks across...
Tokens:59,498
Snippets:851
Trust Score:6.5
Update:1 month ago
Show doc for...
Tokens:
Raw
### Setup and verify nono

Source: https://swival.dev/pages/nono.html

Initializes the nono environment and verifies the installation on the system path.

```sh
nono setup
```

```sh
nono --version
```

--------------------------------

### Installation Feedback and Warnings

Source: https://swival.dev/pages/library.html

Examples of console output when installing skills, including success messages and duplicate warnings.

```text
Installed 1 skill(s) into this project (.swival/skills): ponytail-review
```

```text
⚠ Warning: skill 'ponytail-review' already exists in .swival/skills; use --force to replace
Installed 5 skill(s) into this project (.swival/skills): ponytail, ponytail-audit, ponytail-debt, ponytail-gain, ponytail-help
```

--------------------------------

### Staging Output Example

Source: https://swival.dev/pages/library.html

Example output displayed after successfully staging a collection.

```text
Staged 6 skill(s) into the library (~/.config/swival/library/skills/ponytail):
  ponytail, ponytail-audit, ponytail-debt, ponytail-gain, ponytail-help, ponytail-review
Run 'swival skills add ponytail' to install them into this project,
or 'swival skills add --global ponytail' to install them globally.
```

--------------------------------

### Install agent-browser

Source: https://swival.dev/pages/web-browsing.html

Installation commands for npm and Homebrew environments.

```sh
npm install -g agent-browser
agent-browser install        # downloads Chrome for Testing (first time only)
```

```sh
brew install agent-browser
agent-browser install
```

--------------------------------

### Example Session

Source: https://swival.dev/pages/web-browsing.html

Initiating a browsing task via the Swival CLI.

```sh
swival --commands agent-browser
> Go to https://news.ycombinator.com, click on the top story, and summarize the article
```

--------------------------------

### A2aServer.serve()

Source: https://swival.dev/pages/a2a.html

Starts the server instance.

```APIDOC
## A2aServer.serve()

### Description
Starts the A2aServer to begin listening for requests.
```

--------------------------------

### Install AgentFS

Source: https://swival.dev/pages/agentfs.html

Installs the AgentFS CLI tool via the provided installation script.

```sh
curl -fsSL https://agentfs.ai/install | bash
```

--------------------------------

### Install MetaSKILLs support

Source: https://swival.dev/pages/metaskills.html

Install the Starlark runtime required for executing MetaSKILLs using the swival tool.

```sh
uv tool install --python 3.14 'swival[metaskills]'
```

--------------------------------

### Install and Run Swival

Source: https://swival.dev/

Commands to install the Swival tool and execute a coding task.

```bash
uv tool install --python 3.14 swival
```

```bash
# or on macOS: brew trust swival/tap && brew install swival/tap/swival
```

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

--------------------------------

### Install Swival CLI

Source: https://swival.dev/

Standard installation methods for the Swival CLI tool using uv or Homebrew.

```bash
uv tool install --python 3.14 swival
```

```bash
brew trust swival/tap
brew install swival/tap/swival
```

--------------------------------

### Start the Server

Source: https://swival.dev/pages/a2a.html

Commands to navigate to the project directory and launch the swival server.

```sh
cd acme-api/
swival --serve --serve-port 9100
```

--------------------------------

### Path matching pattern examples

Source: https://swival.dev/pages/audit.html

Examples of how different wildcard patterns match files within the repository structure.

```markdown
Pattern | Matches  
---|---  
`*.rs` | every `.rs` file at any depth (slashless wildcard, recursive shorthand)  
`src/*.rs` | only direct `.rs` children of a top-level `src/` directory  
`src/**/*.rs` | every `.rs` file at any depth under a top-level `src/` directory  
`src/` | every file under a top-level `src/` directory
```

--------------------------------

### Example AGENTS.md Content

Source: https://swival.dev/pages/customization.html

An example of project-specific rules defined within an AGENTS.md file.

```markdown
This is a Go project using Chi for routing. Tests use testify.
Always run `go test ./...` after making changes.
Don't add dependencies without asking.
```

--------------------------------

### Audit Configuration Example

Source: https://swival.dev/pages/audit.html

Example of setting the patch_max_turns in the swival.toml configuration file.

```toml
[audit]
patch_max_turns = 50
```

--------------------------------

### Example TOML Configuration

Source: https://swival.dev/pages/customization.html

A comprehensive example of a Swival configuration file, including provider settings, command permissions, and A2A agent definitions.

```toml
provider = "openrouter"
model = "qwen/qwen3-coder-next"
# base_url = "http://127.0.0.1:1234"    # provider API base URL
# api_key = "..."                       # prefer env vars over config for credentials
# user_agent = "..."                    # User-Agent header for LLM requests
# system_prompt = "..."                 # replaces the built-in system prompt
# no_system_prompt = false              # omit the system message entirely
max_turns = 250
# max_output_lines = 2000               # default line count for file reads
# max_output_kb = 50                    # tool output size cap in KB (reads, grep, listings, outline, fetch)
# temperature = 0.3
# top_p = 0.9
# seed = 42
commands = ["ls", "git", "python3"]    # also accepts "all", "none", or "ask"
# approved_buckets = ["ls", "git push", "python3 -m pytest"]  # explicit pre-approvals for ask mode (runtime approvals go to .swival/approved_buckets)
allowed_dirs = ["/tmp"]
allowed_dirs_ro = ["/opt/zig/lib/std"]
proactive_summaries = true
# no_continue = false
quiet = false
extra_body = { chat_template_kwargs = { enable_thinking = false } }
reasoning_effort = "high"
cache = true
# cache_dir = ".swival"
# retries = 5              # max provider retries on transient network errors
# color = true             # true = force color, false = force no-color, absent = auto
# files = "some"           # filesystem access: "some" (workspace) | "all" (unrestricted) | "none" (.swival/ only)
# yolo = false             # shorthand for files = "all" + commands = "all"
# oneshot_commands = false # enable / and ! command dispatch in one-shot mode
# no_read_guard = false    # disable read-before-write guard
# no_mcp = false           # disable MCP server connections
# no_a2a = false           # disable A2A agent connections
# no_instructions = false  # skip CLAUDE.md and AGENTS.md loading
# no_skills = false        # disable skill discovery
# metaskills = "local"     # "local", "all", or "off"
# no_memory = false        # skip auto-memory loading
# memory_full = false      # inject entire MEMORY.md instead of budgeted retrieval
# no_history = false       # disable HISTORY.md writes
# network = "full"         # "full", "provider-only" (agent commands network-blocked), or "none" (air-gapped)
# sandbox = "builtin"      # "builtin", "agentfs", or "nono"
# sandbox_session = "..."  # AgentFS session ID
# sandbox_strict_read = false  # strict read isolation (agentfs only)
# sandbox_auto_session = true  # auto session ID from project dir (agentfs only)
# encrypt_secrets = false  # transparent credential encryption
# encrypt_secrets_key = "..." # hex 32-byte key for stable ciphertext
# sanitize_thinking = false   # strip leaked <think> tags
# trace_dir = "traces"        # directory for JSONL trace export (HuggingFace format)

# Reviewer settings
reviewer = "swival --reviewer-mode"
# self_review = true               # shorthand: mirrors provider/model into reviewer
review_prompt = "Focus on correctness and test coverage"
max_review_rounds = 15
objective = "objective.md"
verify = "verification/working.md"

# A2A agents (see docs.md/a2a.md)
[a2a_servers.research-agent]
url = "https://research.example.com"
auth_type = "bearer"
auth_token = "sk-..."
```

--------------------------------

### Verify Lightpanda Installation

Source: https://swival.dev/pages/web-browsing.html

Command to verify the installation by fetching HTML content from a URL.

```sh
lightpanda fetch --dump html https://example.com
```

--------------------------------

### Start llama-server

Source: https://swival.dev/pages/providers.html

Launch a local llama.cpp server with a HuggingFace model and specific inference parameters.

```sh
llama-server \
    --reasoning auto \
    --fit on \
    -hf unsloth/gemma-4-26B-A4B-it-GGUF:UD-Q4_K_XL \
    --temp 1.0 --top-p 0.95 --top-k 64
```

--------------------------------

### Install Lightpanda on Linux

Source: https://swival.dev/pages/web-browsing.html

Commands to download and install the Lightpanda binary on x86_64 Linux systems.

```sh
curl -L -o lightpanda https://github.com/lightpanda-io/browser/releases/download/nightly/lightpanda-x86_64-linux
chmod a+x ./lightpanda
sudo mv ./lightpanda /usr/local/bin/
```

--------------------------------

### Install a skill directly

Source: https://swival.dev/pages/library.html

Clones and installs a skill directly into the current project without a staging step.

```sh
swival skills add https://github.com/DietrichGebert/ponytail
```

--------------------------------

### Install uv package manager

Source: https://swival.dev/pages/getting-started.html

Use this command to install the uv tool if it is not already present on your system.

```sh
curl -LsSf https://astral.sh/uv/install.sh | sh
```

--------------------------------

### Configure HuggingFace Provider

Source: https://swival.dev/

Setup and run Swival using the HuggingFace provider.

```bash
export HF_TOKEN=hf_...
```

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

--------------------------------

### Install Swival CLI via Homebrew

Source: https://swival.dev/pages/getting-started.html

Use these commands on macOS to trust the tap and install the CLI.

```sh
brew trust swival/tap
brew install swival/tap/swival
```

--------------------------------

### Project Directory Structure

Source: https://swival.dev/pages/a2a.html

Example layout of a project containing documentation and swival configuration.

```text
acme-api/
  README.md       # endpoint reference, auth, error codes
  app.py          # FastAPI source
  CHANGELOG.md
  swival.toml     # server config (see below)
```

--------------------------------

### Configure llama.cpp Provider

Source: https://swival.dev/

Setup and run Swival using the llama.cpp provider.

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

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

--------------------------------

### Configure OpenRouter Provider

Source: https://swival.dev/

Setup and run Swival using the OpenRouter provider.

```bash
export OPENROUTER_API_KEY=sk_or_...
```

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

--------------------------------

### Start a REPL session with sandbox mode

Source: https://swival.dev/pages/agentfs.html

Launches an interactive agent session inside an AgentFS overlay.

```sh
swival --sandbox agentfs --yolo
```

--------------------------------

### Static skill instruction example

Source: https://swival.dev/pages/metaskills.html

Example of a static skill defined by simple text instructions.

```text
When deploying, run the deploy command, check the health endpoint, and report
the result.
```

--------------------------------

### Install Swival CLI via uv

Source: https://swival.dev/pages/getting-started.html

Installs the Swival CLI and ensures a compatible Python version is used.

```sh
uv tool install --python 3.14 swival
```

--------------------------------

### Start Audit from REPL

Source: https://swival.dev/pages/audit.html

Initiate a full repository audit from the interactive REPL.

```text
swival> /audit
```

--------------------------------

### Configure Stdio MCP Server

Source: https://swival.dev/pages/mcp.html

Example of configuring a local stdio-based MCP server with environment variables.

```toml
[mcp_servers.my-server]
command = "node"
args = ["server.js"]
env = { API_KEY = "secret" }
```

--------------------------------

### Force Overwrite Installation

Source: https://swival.dev/pages/library.html

Use the --force flag to overwrite existing skills during installation.

```sh
swival skills add --force ponytail
```

--------------------------------

### Execute Swival Fetch Command

Source: https://swival.dev/pages/web-browsing.html

Example of using Swival to fetch and summarize content from a website.

```sh
swival
> Fetch https://news.ycombinator.com and summarize the top 5 stories
```

--------------------------------

### Example Swival Browsing Command

Source: https://swival.dev/pages/web-browsing.html

Example of a natural language command for Swival to navigate and summarize a webpage.

```sh
swival
> Navigate to https://news.ycombinator.com, find the top story, and summarize it
```

--------------------------------

### Configure Generic Provider for Local Servers

Source: https://swival.dev/pages/providers.html

Examples for connecting to local servers like mlx_lm and Ollama. These typically do not require an API key.

```sh
# mlx_lm.server
swival --provider generic \
    --base-url http://127.0.0.1:8080 \
    --model mlx-community/Qwen3-Coder-480B-A35B-4bit \
    "task"
```

```sh
# ollama
swival --provider generic \
    --base-url http://127.0.0.1:11434 \
    --model qwen3:32b \
    "task"
```

--------------------------------

### Install Lightpanda on macOS

Source: https://swival.dev/pages/web-browsing.html

Commands to download and install the Lightpanda binary on Apple Silicon macOS systems.

```sh
curl -L -o lightpanda https://github.com/lightpanda-io/browser/releases/download/nightly/lightpanda-aarch64-macos
chmod a+x ./lightpanda
sudo mv ./lightpanda /usr/local/bin/
```

--------------------------------

### Using Lightpanda Engine

Source: https://swival.dev/pages/web-browsing.html

Configuration and usage examples for the Lightpanda browser engine.

```sh
export AGENT_BROWSER_ENGINE=lightpanda
```

```sh
agent-browser open https://example.com
agent-browser snapshot -i
agent-browser close
```

```sh
agent-browser --engine lightpanda open https://example.com
```

```sh
export AGENT_BROWSER_ENGINE=lightpanda
swival --commands agent-browser "Open example.com and describe the page"
```

--------------------------------

### Configure Generic Provider with API Keys

Source: https://swival.dev/pages/providers.html

Examples for connecting to remote APIs that require authentication via environment variables or the --api-key flag.

```sh
# DeepSeek API
export DEEPSEEK_API_KEY=sk-...
swival --provider generic \
    --base-url https://api.deepseek.com \
    --model deepseek-v4-pro \
    --api-key "$DEEPSEEK_API_KEY" \
    "task"
```

```sh
# Z.AI — note the /v4 endpoint, which Swival keeps as-is
export ZAI_API_KEY=...
swival --provider generic \
    --base-url https://api.z.ai/api/paas/v4 \
    --model glm-5.2 \
    --api-key "$ZAI_API_KEY" \
    "task"
```

```sh
export OPENAI_API_KEY=sk-...
swival --provider generic \
    --base-url https://my-server.example.com \
    --model my-model \
    "task"
```

--------------------------------

### Configure Lightpanda MCP Server

Source: https://swival.dev/pages/web-browsing.html

Configuration examples for adding the Lightpanda MCP server to Swival using either TOML or JSON formats.

```toml
[mcp_servers.lightpanda]
command = "lightpanda"
args = ["mcp"]
```

```json
{
  "mcpServers": {
    "lightpanda": {
      "command": "lightpanda",
      "args": ["mcp"]
    }
  }
}
```

--------------------------------

### Install Skills from Library

Source: https://swival.dev/pages/library.html

Adds skills or collections to the current project or global set. Use --global to make skills available across all projects.

```sh
swival skills add ponytail-review            # one skill, into this project
swival skills add --global ponytail-gain     # one skill, active everywhere
swival skills add ponytail                   # the whole collection, into this project
```

--------------------------------

### Configure Generic Provider with Custom User-Agent

Source: https://swival.dev/pages/providers.html

Example for providers that require a specific User-Agent header for access.

```sh
export KIMI_API_KEY=sk-kimi-...
swival --provider generic \
    --base-url https://api.kimi.com/coding/v1 \
    --model kimi-for-coding \
    --api-key "$KIMI_API_KEY" \
    --user-agent "KimiCLI/Swival" \
    "task"
```

--------------------------------

### Session Cost Output Example

Source: https://swival.dev/pages/usage.html

Example of the cumulative cost estimate printed to stderr after a successful turn.

```text
  LLM responded in 1.4s  finish_reason=tool_calls
  Session cost: ~$0.003812

```

--------------------------------

### Run Interactive Mode

Source: https://swival.dev/

Start an interactive back-and-forth session with the agent.

```bash
swival
```

--------------------------------

### SKILL.md File Format

Source: https://swival.dev/pages/skills.html

Example of a skill definition file using YAML frontmatter for metadata followed by the instruction body.

```markdown
---
name: deploy
description: Deploy the application to production using the deploy script.
---

Run `scripts/deploy.sh` from the skill directory, check the output for errors,
and verify the deployment through the health endpoint.

The deploy script expects `DEPLOY_ENV` to be set. Use `production` for prod
and `staging` for staging.
```

--------------------------------

### Run Swival with LM Studio

Source: https://swival.dev/pages/getting-started.html

Executes the default Swival command after starting the LM Studio local server.

```sh
swival "Hello world"
```

--------------------------------

### Disabling Instructions

Source: https://swival.dev/pages/customization.html

Command to start Swival while skipping all instruction files.

```sh
swival --no-instructions "task"
```

--------------------------------

### Configure LM Studio Provider

Source: https://swival.dev/pages/providers.html

Examples for overriding default LM Studio settings, including base URL, model selection, and context token limits.

```sh
swival --base-url http://192.168.1.100:1234 "task"
```

```sh
swival --model "qwen3-coder-next" "task"
```

```sh
swival --max-context-tokens 131072 "task"
```

--------------------------------

### Start Swival A2A Server

Source: https://swival.dev/pages/a2a.html

Initializes the HTTP server at 0.0.0.0:8080 to accept A2A JSON-RPC requests using the specified provider and model.

```bash
swival --serve --provider openrouter --model z-ai/glm-5.2
```

--------------------------------

### Initialize Configuration Files

Source: https://swival.dev/pages/customization.html

Commands to generate starter configuration files for global or project-specific settings.

```sh
swival --init-config            # global config
swival --init-config --project  # project config in current directory
```

--------------------------------

### Command line pattern usage

Source: https://swival.dev/pages/audit.html

Example of combining multiple patterns in a single audit command.

```bash
/audit '*.rs' '*.toml'
```

--------------------------------

### Execute commands with run_command

Source: https://swival.dev/pages/tools.html

Examples of invoking the run_command tool using different command whitelist and interactive modes.

```sh
swival --commands ls,git,python3 "Run the tests"
swival --commands ask "Run the tests"
```

--------------------------------

### Example report JSON output

Source: https://swival.dev/pages/reports.html

A sample JSON report generated from a local run with --max-turns 0.

```json
{
  "version": 1,
  "mode": "oneshot",
  "timestamp": "2026-02-25T22:37:31.546022+00:00",
  "task": "No-op example",
  "model": "dummy-model",
  "provider": "lmstudio",
  "settings": {
    "temperature": null,
    "top_p": null,
    "seed": null,
    "max_turns": 0,
    "max_output_tokens": 32768,
    "context_length": null,
    "files": "some",
    "commands": "all",
    "max_review_rounds": 15,
    "skills_discovered": [],
    "instructions_loaded": []
  },
  "sandbox": {
    "mode": "builtin"
  },
  "result": {
    "outcome": "exhausted",
    "answer": null,
    "exit_code": 2
  },
  "stats": {
    "turns": 0,
    "tool_calls_total": 0,
    "tool_calls_succeeded": 0,
    "tool_calls_failed": 0,
    "tool_calls_by_name": {},
    "compactions": 0,
    "turn_drops": 0,
    "guardrail_interventions": 0,
    "recovered_responses": 0,
    "truncation_repairs": 0,
    "scavenged_calls": 0,
    "stormed_calls": 0,
    "llm_calls": 0,
    "total_llm_time_s": 0.0,
    "total_tool_time_s": 0.0,
    "skills_used": [],
    "review_rounds": 0
  },
  "timeline": []
}
```

--------------------------------

### Constructor

Source: https://swival.dev/pages/python-api.html

Initializes a new Swival session with the specified configuration parameters.

```APIDOC
## Constructor

### Description
Initializes the Swival agent session. Parameters define the project root, LLM provider settings, security policies, and operational limits.

### Parameters
- **base_dir** (string) - Required - Project root. Tools resolve paths relative to this.
- **provider** (string) - Required - LLM provider: "lmstudio", "llamacpp", "huggingface", "openrouter", "chatgpt", "google", "geap", "bedrock", "generic", "applefm", or "command".
- **model** (string) - Required - Model identifier.
- **api_key** (string) - Optional - API key for the provider.
- **user_agent** (string) - Optional - User-Agent header for LLM API requests.
- **base_url** (string) - Optional - Override the provider's default endpoint.
- **max_turns** (integer) - Optional - Maximum agent loop iterations.
- **max_output_tokens** (integer) - Optional - Maximum tokens per LLM response.
- **max_context_tokens** (integer) - Optional - Hard cap on context window size.
- **max_output_lines** (integer) - Optional - Default number of lines returned by file reads.
- **max_output_kb** (integer) - Optional - Size cap in KB for tool output.
- **temperature** (float) - Optional - Sampling temperature.
- **files** (string) - Optional - Filesystem access policy: "some", "all", or "none".
- **commands** (string/list) - Optional - Command execution policy: "all", "none", "ask", or a list of whitelisted command names.
- **yolo** (boolean) - Optional - Shorthand for files="all".
- **network** (string) - Optional - Network policy: "provider-only" or "none".
- **system_prompt** (string) - Optional - Override the default system prompt.
- **mcp_servers** (object) - Optional - MCP server configurations.
- **a2a_servers** (object) - Optional - A2A server configurations.
- **lifecycle_command** (string) - Optional - Shell command to run at startup and exit.
- **lifecycle_fail_closed** (boolean) - Optional - If True, hook failures raise LifecycleError.
- **llm_filter** (string) - Optional - Path to a filter script for outbound LLM requests.
- **subagents** (boolean) - Optional - Enable parallel subagent support.
- **encrypt_secrets** (boolean) - Optional - Enable format-preserving secret encryption.
- **retries** (integer) - Optional - Number of LLM call retries.
- **history** (boolean) - Optional - Write HISTORY.md after successful runs.
- **memory** (boolean) - Optional - Load memory files into the system prompt.
- **prompt_cache** (boolean) - Optional - Inject explicit cache_control annotations.
- **cache** (boolean) - Optional - Cache LLM responses to disk.
- **trace_dir** (string) - Optional - Directory to write session traces.
- **verbose** (boolean) - Optional - Print diagnostics to stderr.
- **command_middleware** (string) - Optional - Script to intercept and rewrite shell commands.
- **aws_profile** (string) - Optional - AWS profile name for the bedrock provider.
- **approved_buckets** (set) - Optional - Pre-approved command buckets for commands="ask" mode.
- **storm_breaker** (boolean) - Optional - Suppress repeated identical tool calls.
- **flatten_mcp_schemas** (boolean) - Optional - Flatten deeply nested MCP tool schemas.
```

--------------------------------

### Initialize AgentFS with a local overlay

Source: https://swival.dev/pages/agentfs.html

Initializes a project-local overlay database and executes a Swival command within that context.

```sh
cd ~/my-project

agentfs init --base . -c \
    'swival "Add a config module" --yolo --max-turns 20' \
    add-config
```

--------------------------------

### Run One-Shot Loop Commands

Source: https://swival.dev/pages/usage.html

Examples of using the --oneshot-commands flag to execute recurring tasks in one-shot mode.

```sh
swival --oneshot-commands '/loop 5m check open PRs and summarize blockers'
swival --oneshot-commands '/loop every hour run the build and report failures'
swival --oneshot-commands '/loop 30 sec check git status and report unusual activity'
```

--------------------------------

### View Cache Diagnostics

Source: https://swival.dev/pages/providers.html

Example output displayed in stderr when diagnostics are enabled, showing cache hit and write statistics.

```text
Prompt cache: 4821 tokens cached
Prompt cache: 6103 tokens written to cache
```

--------------------------------

### Configure HuggingFace Inference API

Source: https://swival.dev/pages/providers.html

Examples for using HuggingFace serverless and dedicated endpoints with required authentication and model identifiers.

```sh
export HF_TOKEN=hf_your_token_here
swival --provider huggingface --model zai-org/GLM-5.2 "task"
```

```sh
swival --provider huggingface \
    --model zai-org/GLM-5.2 \
    --base-url https://xyz.endpoints.huggingface.cloud \
    --api-key hf_your_key \
    "task"
```

```sh
swival --provider huggingface \
    --model Qwen/Qwen3.5-35B-A3B \
    --base-url https://tfg1ghx03o7xuv5p.us-east-1.aws.endpoints.huggingface.cloud
```

--------------------------------

### Upgrade Swival CLI

Source: https://swival.dev/pages/getting-started.html

Updates the existing installation to the latest version based on the original installation method.

```sh
uv tool upgrade swival    # if installed with uv
brew upgrade swival       # if installed with Homebrew
```

--------------------------------

### Initialize Session with MCP servers

Source: https://swival.dev/pages/mcp.html

Configure MCP servers by passing a dictionary of server names and their respective command and argument configurations to the Session constructor.

```python
from swival import Session

session = Session(
    mcp_servers={
        "brave-search": {
            "command": "npx",
            "args": ["-y", "@modelcontextprotocol/server-brave-search"],
            "env": {"BRAVE_API_KEY": "your-key-here"},
        }
    }
)
result = session.run("Search for Python async best practices")
```

--------------------------------

### MetaSKILL Workflow Implementation

Source: https://swival.dev/pages/metaskills.html

The SKILL.star file contains the logic for the skill, utilizing host-provided functions to perform tasks and trace execution.

```python
def run(input):
    task = input["task"]
    heading = input["heading"]

    for i in range(3):
        result = ask(task, {
            "purpose": "draft",
            "max_turns": 4,
        })

        if heading in result["answer"]:
            return {
                "status": "accepted",
                "answer": result["answer"],
                "attempts": i + 1,
            }

        trace("missing-heading", {
            "attempt": i + 1,
            "heading": heading,
        })

        task = (
            "Revise the draft so it includes this exact heading:\n" +
            heading +
            "\n\nPrevious draft:\n" +
            result["answer"]
        )

    return {
        "status": "exhausted",
        "answer": result["answer"],
        "warning": "The required heading was still missing.",
    }
```

--------------------------------

### Session.reset()

Source: https://swival.dev/pages/python-api.html

Clears the conversation state while preserving setup configuration.

```APIDOC
## Session.reset()

### Description
Clears the conversation state. The next call to ask() will start with a fresh message history, but setup such as provider validation and MCP connections are preserved.
```

--------------------------------

### Combined Audit Options

Source: https://swival.dev/pages/audit.html

Examples of combining audit flags with focus paths.

```text
swival> /audit src/api/ --resume --workers 6
swival> /audit src/api/ --regen
```

--------------------------------

### Disabling Auto-Memory

Source: https://swival.dev/pages/customization.html

Command to start Swival while skipping the loading of auto-memory files.

```sh
swival --no-memory "task"
```

--------------------------------

### Switch Profiles via CLI and REPL

Source: https://swival.dev/pages/providers.html

Apply profiles at startup using command-line flags or switch during an active session using the REPL command.

```sh
swival --profile local "quick task"
swival --profile gpt5 "hard task"
```

```text
swival> /profile gpt5
```

--------------------------------

### Connect Swival to llama.cpp

Source: https://swival.dev/pages/providers.html

Connect Swival to a local llama.cpp server using default settings or custom overrides.

```sh
swival --provider llamacpp "task"
```

```sh
swival --provider llamacpp \
    --base-url http://192.168.1.10:9090 \
    --model my-model \
    "task"
```

--------------------------------

### Create commands directory

Source: https://swival.dev/pages/custom-commands.html

Initializes the directory where Swival looks for custom command files.

```sh
mkdir -p ~/.config/swival/commands
```

--------------------------------

### Handle ContextOverflowError

Source: https://swival.dev/pages/python-api.html

Example of catching ContextOverflowError to reset the session and retry with a smaller task.

```python
from swival import Session, ContextOverflowError

session = Session(provider="lmstudio")
try:
    result = session.ask("very large task")
except ContextOverflowError:
    session.reset()
    result = session.ask("smaller subtask")
```

--------------------------------

### Execute agent task with run()

Source: https://swival.dev/pages/python-api.html

Use the convenience function to create a session, execute a question, and return the result.

```python
import swival

answer = swival.run("list the Python files in this directory", provider="lmstudio")
print(answer)
```

--------------------------------

### Audit Completion Output

Source: https://swival.dev/pages/audit.html

Example output displayed upon successful completion of an audit.

```text
swival> /audit
Audit complete. 2 finding(s) written to audit-findings/. Open audit-findings/README.md to review.
```

--------------------------------

### ask(prompt, opts={})

Source: https://swival.dev/pages/metaskills.html

Asks the host agent to perform a nested piece of work using the host's model, tools, and sandbox.

```APIDOC
## ask(prompt, opts={})

### Description
Asks the host agent to perform a nested piece of work. It utilizes the host's normal model, tools, sandbox, cancellation, and reporting behavior.

### Parameters
- **prompt** (string) - Required - Prompt for the nested agent turn.
- **opts.purpose** (string) - Optional - Label for traces and reports.
- **opts.max_turns** (integer) - Optional - Nested turn cap.

### Response
- **answer** (string) - Text returned by the nested agent.
- **exhausted** (boolean) - Indicates whether the nested turn hit a host limit.
- **turns** (integer) - Number of turns used.
- **truncated** (boolean) - True when answer was shortened.
```

--------------------------------

### A2aServer Constructor

Source: https://swival.dev/pages/a2a.html

Initializes a new A2aServer instance with session configuration, network settings, and defined skills.

```APIDOC
## A2aServer(session_kwargs, host, port, auth_token, name, description, skills)

### Description
Initializes the server instance. The constructor accepts operational tuning parameters including max_request_size, max_requests_per_minute, max_concurrent, and heartbeat_interval.

### Parameters
- **session_kwargs** (dict) - Configuration for the provider and model.
- **host** (str) - The host address to bind to.
- **port** (int) - The port to listen on.
- **auth_token** (str) - Optional bearer token for security.
- **name** (str) - Display name for the agent.
- **description** (str) - Description of the agent's purpose.
- **skills** (list) - A list of skill dictionaries defining agent capabilities.
```

--------------------------------

### Iterate on an existing session

Source: https://swival.dev/pages/agentfs.html

Reuse a session name to continue refining changes without starting over.

```sh
agentfs run --session add-config -- \
    swival "The tests are failing because config.py doesn't handle missing env vars. Fix it." --yolo
```

--------------------------------

### Audit Incomplete Verification Message

Source: https://swival.dev/pages/audit.html

Example output displayed when an audit session is interrupted before all findings are verified.

```text
Audit incomplete: 2 findings not verified after 3 attempts (1 failed). Use /audit --resume to retry.
```

--------------------------------

### Audit Findings Directory Structure

Source: https://swival.dev/pages/audit.html

Example of the file structure generated in the audit-findings directory after artifact generation.

```text
audit-findings/
  README.md
  001-command-injection-in-handler.md
  001-command-injection-in-handler.patch
  002-missing-null-check-in-parser.md
  002-missing-null-check-in-parser.patch
```

--------------------------------

### Execute Single-Shot Request

Source: https://swival.dev/pages/python-api.html

Perform an independent execution using Session.run, which starts with fresh message history and state.

```python
session = Session(provider="lmstudio")
result = session.run("refactor the login handler")
print(result.answer)
```

--------------------------------

### snapshot

Source: https://swival.dev/pages/tools.html

A context management tool for collapsing exploration turns into compact summaries to maintain a clean context window.

```APIDOC
## snapshot

### Description
Collapses multiple turns of exploration into a single summary message. Supports actions: save, restore, cancel, and status.

### Parameters
- **action** (string) - Required - The action to perform: 'save', 'restore', 'cancel', or 'status'.
- **label** (string) - Optional - Required for 'save' action (max 100 characters).
- **summary** (string) - Optional - Required for 'restore' action (max 4,000 characters).
- **force** (boolean) - Optional - Used with 'restore' to override dirty scope checks (default false).
```

--------------------------------

### Configure Middleware

Source: https://swival.dev/pages/command-middleware.html

Enable the middleware via CLI flag or persistent configuration file.

```sh
swival --command-middleware "./scripts/rtk-adapter.py" "Investigate the failing tests"
```

```toml
command_middleware = "./scripts/rtk-adapter.py"
```

--------------------------------

### Session(mcp_servers)

Source: https://swival.dev/pages/mcp.html

Initializes a new session with configured MCP servers and executes tasks.

```APIDOC
## Session(mcp_servers)

### Description
Initializes a session instance with a dictionary of MCP server configurations. The session can then be used to run tasks across these servers.

### Parameters
- **mcp_servers** (dict) - Required - A dictionary mapping server names to configuration dictionaries containing 'command', 'args', and 'env'.

### Usage Example
```python
from swival import Session

session = Session(
    mcp_servers={
        "brave-search": {
            "command": "npx",
            "args": ["-y", "@modelcontextprotocol/server-brave-search"],
            "env": {"BRAVE_API_KEY": "your-key-here"},
        }
    }
)
result = session.run("Search for Python async best practices")
```
```

--------------------------------

### Define a skill catalog entry

Source: https://swival.dev/pages/metaskills.html

Example of a compact catalog entry for a skill, including its name, description, and metaskill language.

```text
- test-fix: Run tests and ask the agent to fix failures. (metaskill: starlark)
```

--------------------------------

### Run Swival in Reviewer Mode

Source: https://swival.dev/pages/reviews.html

Use the --reviewer-mode flag to enable native reviewer protocol support without requiring a wrapper script.

```sh
swival "Refactor error handling in src/api.py" \
    --reviewer "swival --reviewer-mode"
```

--------------------------------

### Launch Swival in ACP Mode

Source: https://swival.dev/pages/acp.html

Starts the Swival agent in ACP mode to accept JSON-RPC requests via stdin.

```sh
swival --acp
```

--------------------------------

### Execute Swival with Google Gemini

Source: https://swival.dev/pages/getting-started.html

Set the Gemini API key and run a prompt using the Google provider.

```sh
export GEMINI_API_KEY=...
swival "Hello world" --provider google --model gemini-2.5-flash
```

--------------------------------

### Switch Profiles via CLI

Source: https://swival.dev/pages/customization.html

Use the --profile flag to select a specific configuration profile at runtime.

```sh
swival --profile gpt5 "review this patch"
swival --profile fast-local "write tests"
```

--------------------------------

### Audit Incomplete Artifact Generation Message

Source: https://swival.dev/pages/audit.html

Example output displayed when artifact generation fails, providing commands for retrying the process.

```text
Audit incomplete: artifact generation has 1 failed and 0 pending out of 10 verified finding(s). Use /audit --resume --patch-max-turns 75 to retry incomplete artifacts, or /audit --regen --finding 1 --patch-max-turns 75 to retry a specific finding.
```

--------------------------------

### Test Adapter Logic

Source: https://swival.dev/pages/command-middleware.html

Verify the adapter's behavior by piping sample JSON payloads into the script.

```sh
# git status → rtk git status
echo '{"phase":"before","tool":"run_shell_command","cwd":".","mode":"shell","command":"git status","timeout":30,"is_subagent":false}' \
  | python3 scripts/rtk-adapter.py
# → {"action": "allow", "mode": "shell", "command": "rtk git status"}

# ls -la → rtk ls -la
echo '{"phase":"before","tool":"run_command","cwd":".","mode":"argv","command":["ls","-la"],"timeout":30,"is_subagent":false}' \
  | python3 scripts/rtk-adapter.py
# → {"action": "allow", "mode": "shell", "command": "rtk ls -la"}

# echo hello → pass through (no RTK equivalent)
echo '{"phase":"before","tool":"run_command","cwd":".","mode":"argv","command":["echo","hello"],"timeout":30,"is_subagent":false}' \
  | python3 scripts/rtk-adapter.py
# → {"action": "allow"}
```

--------------------------------

### Compare sampling settings

Source: https://swival.dev/pages/reports.html

Runs the same task across different temperature settings to evaluate the impact on output.

```sh
for temp in 0.2 0.55 0.8; do
    swival "Refactor src/api.py" \
        --temperature "$temp" \
        --report "results/temp-${temp}.json"
done
```

--------------------------------

### Configure Server Metadata via CLI and TOML

Source: https://swival.dev/pages/a2a.html

Override auto-generated server names and descriptions using command-line arguments or the swival.toml configuration file.

```sh
swival --serve --serve-name "Code Review Bot" \
  --serve-description "Reviews Python code for bugs, security issues, and style"
```

```toml
serve_name = "Code Review Bot"
serve_description = "Reviews Python code for bugs, security issues, and style"
```

--------------------------------

### Run with generic OpenAI-compatible server

Source: https://swival.dev/pages/getting-started.html

Connects to any OpenAI-compatible API by specifying the base URL and model name.

```sh
swival "Hello world" \
    --provider generic \
    --base-url http://127.0.0.1:8080 \
    --model my-model
```

--------------------------------

### Configure Swival via swival.toml

Source: https://swival.dev/pages/reviews.html

Define reviewer settings in swival.toml to avoid repeating flags on every invocation.

```toml
reviewer = "swival --reviewer-mode"
verify = "verification/working.md"
review_prompt = "Focus on correctness and test coverage"
```

```toml
self_review = true
verify = "verification/working.md"
review_prompt = "Focus on correctness and test coverage"
```

--------------------------------

### Mount and test an overlay

Source: https://swival.dev/pages/agentfs.html

Mounts the overlay to a temporary directory for testing and selective file application.

```sh
mkdir -p /tmp/sandbox
agentfs mount -f --auto-unmount add-config /tmp/sandbox &

cd /tmp/sandbox
python -m pytest tests/ -v
cp src/config.py ~/my-project/src/

kill %1
```

--------------------------------

### Make Adapter Executable

Source: https://swival.dev/pages/command-middleware.html

Set the execution permissions for the adapter script.

```sh
chmod +x scripts/rtk-adapter.py
```
Tokens:
Raw