Usage

Swival has two operating modes. The default mode is one-shot, where you give the agent a task and let it run to completion. The second mode is an interactive REPL, where conversation history stays live across follow-up prompts.

One-Shot Mode

In one-shot mode, you pass one task on the command line and Swival keeps looping through tool calls until it reaches a final answer or hits the turn limit.

swival "Review this codebase for security issues"

The final answer is written to standard output. Diagnostics such as turn logs, timing, and tool traces are written to standard error.

If you want a clean output stream for scripting, use --quiet or -q.

swival -q "Summarize the API surface of src/" > api-summary.txt

You can grant command execution when needed by explicitly whitelisting command names.

swival --allowed-commands ls,git,python3 \
    "Create a tool that returns a random number between 0 and 42"

That whitelist changes what the agent can do. If python3 is available, it can use Python for implementation and verification. If no commands are whitelisted, run_command is unavailable unless you enable YOLO mode.

A successful run exits with code 0. A runtime or configuration failure exits with code 1. A run that reaches the turn limit before finishing exits with code 2.

Interactive Mode

REPL mode keeps a shared conversation state, so each new question can build on earlier turns.

swival --repl

You can also launch the REPL and send an initial question immediately.

swival --repl "Look at the project structure and tell me what this does"

The REPL is built on prompt-toolkit, so it supports input history, history search, and normal terminal line editing.

REPL Commands

/help prints the command reference in the terminal.

/clear drops conversation history back to the initial system state and also resets internal thinking and file-tracking state.

/compact compacts older tool output in memory. /compact --drop is more aggressive and also drops middle turns.

/add-dir <path> grants read and write access to an additional directory for the current session.

/extend doubles the current turn budget. /extend <N> sets the turn budget to an exact value.

/continue restarts the agent loop for the existing conversation without adding a new user message.

/init runs a three-pass workflow that scans your project and generates an AGENT.md file.

/exit and /quit leave the REPL. Pressing Ctrl-D exits as well.

CLI Flags

Model And Provider Flags

--provider chooses the backend provider and defaults to lmstudio. Valid values are lmstudio, huggingface, and openrouter.

--model overrides auto-discovery with a fixed model identifier.

--base-url sets a custom API base URL. For LM Studio, the default base URL is http://127.0.0.1:1234 when --base-url is not set.

--api-key provides a key directly on the command line and takes precedence over provider environment variables such as HF_TOKEN or OPENROUTER_API_KEY.

Behavior Tuning Flags

--max-turns sets the maximum number of loop iterations and defaults to 100.

--max-output-tokens sets the model output budget per call and defaults to 32768.

--max-context-tokens requests a context window size. With LM Studio, this may trigger a model reload.

--temperature controls sampling temperature and defaults to the provider default when omitted.

--top-p controls nucleus sampling and defaults to 1.0.

--seed passes a random seed for providers that support reproducible sampling.

Sandboxing Flags

--base-dir defines the base directory for file tools and defaults to the current directory.

--allowed-commands enables command execution through a comma-separated whitelist.

--allow-dir grants read and write access to additional directories and can be repeated.

--yolo disables both filesystem sandbox checks and command whitelisting, except that filesystem root access is still blocked.

--no-read-guard disables the read-before-write guard that normally prevents editing existing files before reading them.

System Prompt And Instruction Flags

--system-prompt replaces the built-in prompt with your own prompt text.

--no-system-prompt omits the system message entirely.

--no-instructions prevents loading CLAUDE.md and AGENT.md from the base directory.

--system-prompt and --no-system-prompt are mutually exclusive.

Skills Flags

--skills-dir adds external skill directories and can be passed more than once.

--no-skills disables skill discovery and removes the use_skill tool path.

Output And Reporting Flags

--quiet and -q suppress diagnostics and keep terminal output focused on final answers.

--report FILE writes a JSON run report to FILE. This flag is incompatible with --repl.

--reviewer EXECUTABLE runs an external reviewer after each answer. This flag is also incompatible with --repl.

--no-history disables writes to .swival/HISTORY.md.

--color forces ANSI color on standard error, and --no-color disables ANSI color even on TTY output.

For the full report schema and analysis workflow, see Reports. For the reviewer protocol and examples, see Reviews.