Starweaver

Starweaver is a Rust agent SDK for building local-first AI agents, CLIs, and service runtimes. It gives you a typed agent loop, provider-neutral model protocol, function tools, structured output, durable session primitives, first-party environment tools, and a CLI product surface in one workspace.

Why Starweaver

Rust-native agent construction with AgentBuilder, AgentApp, and AgentSession.
Provider-neutral model messages, settings, profiles, streaming parts, and request audit hooks.
Typed function tools from Serde and schemars, plus toolsets, metadata, retries, approval, and deferred records.
Structured output through JSON Schema, typed parsing, output functions, and validation retry.
Runtime extension hooks for prompt preparation, request shaping, tool policy, output validation, usage, and trace recording.
Durable execution foundations: context export/restore, checkpoints, session records, replay streams, and SQLite storage adapters.
First-party SDK bundles for filesystem, shell, skills, task tracking, host search/scrape/media adapters, MCP, and subagents.
A CLI launcher with profile-based local runs, install/update flow, display messages, local storage, and release artifacts.

Install

Install the latest public release:

curl -fsSL https://raw.githubusercontent.com/Wh1isper/starweaver/main/scripts/install.sh | sh

The installer downloads the matching starweaver-cli archive, verifies checksums.txt when available, and installs starweaver, starweaver-cli, sw, and starweaver-rpc. It installs into $HOME/.local/bin for normal users and /usr/local/bin for root. Override the location when needed:

curl -fsSL https://raw.githubusercontent.com/Wh1isper/starweaver/main/scripts/install.sh \
  | STARWEAVER_INSTALL_DIR="$HOME/bin" sh

Install a pinned release or prerelease:

curl -fsSL https://raw.githubusercontent.com/Wh1isper/starweaver/main/scripts/install.sh \
  | STARWEAVER_VERSION=vX.Y.Z sh

The default latest channel uses GitHub's latest stable release first and falls back to the newest public prerelease when no stable release exists yet.

Update an installed CLI from GitHub release artifacts:

starweaver update

The update command checks the current CLI package version before invoking the installer. When the selected release is already installed it exits with status=up-to-date; pass --force to reinstall the same version.

Run from a checkout:

make cli -- -p "hello" --output text
make sw -- --help
make sw -- -p "hello" --output text
make sw -- version

SDK Quickstart

use std::sync::Arc;

use starweaver_agent::{AgentBuilder, TestModel};

# async fn example() -> Result<(), starweaver_agent::AgentError> {
let agent = AgentBuilder::new(Arc::new(TestModel::with_text("Paris")))
    .instruction("Answer concisely.")
    .build();

let result = agent.run("What is the capital of France?").await?;
assert_eq!(result.output, "Paris");
# Ok(())
# }

Add typed tools:

use std::sync::Arc;

use schemars::JsonSchema;
use serde::{Deserialize, Serialize};
use starweaver_agent::{typed_tool, AgentBuilder, TestModel, ToolContext, ToolResult};

#[derive(Clone, Debug, Deserialize, JsonSchema, Serialize)]
struct LookupArgs {
    /// City to look up.
    city: String,
}

# async fn example() -> Result<(), starweaver_agent::AgentError> {
let lookup = typed_tool::<LookupArgs, _, _>(
    "lookup_weather",
    Some("Look up weather for a city".to_string()),
    |_ctx: ToolContext, args: LookupArgs| async move {
        Ok(ToolResult::new(serde_json::json!({
            "city": args.city,
            "forecast": "clear"
        })))
    },
);

let agent = AgentBuilder::new(Arc::new(TestModel::with_text("clear")))
    .tool(Arc::new(lookup))
    .build();

let result = agent.run("What is the weather in Paris?").await?;
assert_eq!(result.output, "clear");
# Ok(())
# }

Documentation

Published docs: https://starweaver.wh1isper.top

Start here:

Architecture and product decisions live in spec/. User-facing guides live in docs/.

Workspace

Starweaver is organized as focused crates:

starweaver-agent: public SDK facade, app/session helpers, bundles, subagents, profiles, and filters.
starweaver-runtime: deterministic agent loop, graph state, tools, output, retries, capabilities, streams, traces, and checkpoints.
starweaver-model: provider-neutral model protocol, settings, profiles, transports, wrappers, OAuth-backed adapters, and replay tests.
starweaver-tools: function tools, toolsets, metadata, lifecycle, MCP foundations, approval, and deferred execution.
starweaver-context: AgentContext, typed dependencies, state, event/message buses, notes, usage, and resumable state.
starweaver-environment: local and virtual filesystem/shell providers, policies, resources, and environment snapshots.
starweaver-session, starweaver-stream, starweaver-storage: durable session, replay, display stream, and SQLite storage contracts.
starweaver-cli: local CLI product surface, launcher dispatch, profiles, TUI, storage, install, and update workflows.
starweaver-rpc-core: shared JSON-RPC host protocol helpers and stream/replay projections.
starweaver-rpc: standalone JSON-RPC host process for Desktop and local host integrations.

Validation

make fmt-check
make check
make test
make docs-check
make docs-build

Full local gate:

make ci

Release

Prepare a release:

gh workflow run prepare-release.yml -f version=X.Y.Z

The workflow pushes release/vX.Y.Z for review. After that release commit reaches main, publish vX.Y.Z as a GitHub Release; the published Release event builds CLI archives, uploads checksums, and publishes crates through the Release environment.

Acknowledgements

Thank you to the projects that helped shape Starweaver's thinking, especially Pydantic AI and Yet Another Agents / ya-mono.

License

BSD-3-Clause

starweaver-usage 0.2.0