Swink Agent

A pure-Rust library for building LLM-powered agentic loops. Provider-agnostic core with pluggable streaming, concurrent tool execution, and lifecycle events.

Workspace

Feature Matrix

Key Ideas

• StreamFn is the only provider boundary — implement it to add a new LLM backend.
• AgentTool trait + JSON Schema validation for tool definitions.
• Tools execute concurrently within a turn; steering callbacks can interrupt mid-batch.
• Errors stay in the message log — the loop keeps running. Typed AgentError variants for callers.
• Events are push-only (AgentEvent stream). No inward mutation through events.
• No unsafe code. No global mutable state.
• Optional tiktoken support ships a built-in TiktokenCounter for more accurate context budgets.

Quick Reference

cargo run -p swink-agent-tui     # launch the TUI (remote/Ollama defaults)
cargo run -p swink-agent-tui --features local  # include bundled local-LLM support
cargo run -p swink-agent-eval --features cli --bin swink-eval -- --help
cargo test --workspace             # run all tests
just validate                      # formatting, clippy, tests, package preflight

Workspace-wide cargo build/test/clippy commands also compile swink-agent-local-llm. That crate currently depends on llama-cpp-sys-2, so contributor machines need LLVM/libclang available for bindgen; if auto-discovery fails, set LIBCLANG_PATH to the LLVM bin directory before running workspace checks.

For the advanced evaluation surface, see eval/README.md for evaluator/reporter usage and eval-judges/README.md for provider feature flags and credential setup.

Hot-Reloaded Script Tools

When the hot-reload feature is enabled, ScriptTool definitions use a top-level [parameters_schema] TOML section, and command interpolates runtime arguments with {param} placeholders:

name = "greet"
description = "Greet a person by name"
command = "echo 'Hello, {name}!'"

[parameters_schema]
type = "object"
required = ["name"]

[parameters_schema.properties.name]
type = "string"
description = "The name to greet"

Example: Build a Custom Agent

Wire up an LLM provider, register tools, and launch the interactive TUI — all in one file:

use swink_agent::{AgentOptions, BashTool, ModelConnections, ReadFileTool, WriteFileTool};
use swink_agent_adapters::build_remote_connection_for_model;
use swink_agent_local_llm::default_local_connection;
use swink_agent_tui::{TuiConfig, launch, restore_terminal, setup_terminal};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    dotenvy::dotenv().ok();

    let connections = ModelConnections::new(
        build_remote_connection_for_model("claude-sonnet-4-6")?,
        vec![
            build_remote_connection_for_model("gpt-4.1")?,
            default_local_connection()?,
        ],
    );
    let tools = vec![
        BashTool::new().into_tool(),
        ReadFileTool::new().into_tool(),
        WriteFileTool::new().into_tool(),
    ];

    let options =
        AgentOptions::from_connections("You are a helpful assistant.", connections)
            .with_tools(tools);

    let mut terminal = setup_terminal()?;
    let result = launch(TuiConfig::default(), &mut terminal, options).await;

    restore_terminal()?;
    result
}

More Examples

Runnable examples are in SuperSwinkAI/Swink-Agent-Examples:

See docs/getting_started.md for setup and configuration. See docs/architecture/HLD.md for system design. See docs/planning/PRD.md for product requirements.