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.
A three-platform Tauri 2 Desktop foundation with generated least-authority host bindings, a verified local RPC supervisor, single-instance lifecycle, and native CI matrix.

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: generated IDL-first starweaver.host major-1 wire boundary, strict server/client codecs, typed errors/events/cursors, launch-envelope contracts, and narrow framing/projection helpers; the generated contract atomically replaces handwritten DTO authority.
starweaver-rpc: standalone JSON-RPC host process for local and external integrations and implementer of the generated single-contract server boundary; HTTP exposes only POST /rpc.
apps/starweaver-desktop: Tauri 2 shell for Linux, macOS, and Windows with a manifest-filtered renderer bridge and verified local stdio RPC supervisor; normal runtime activation remains gated on the updater/configuration owner.
packages/starweaver-py: in-process Python SDK bindings, Python tool injection, live run control, message bus facades, typed HITL helpers, deterministic test models, sessions, and Python distribution artifacts.

The canonical host protocol lives under protocol/host/. Default generation writes the bundled OpenRPC artifact, Rust server bindings, and Desktop's manifest-filtered safe bindings:

make rpc-idl-generate

External TypeScript consumers can generate complete bindings into a directory they own. Starweaver does not maintain or publish a separate TypeScript protocol package:

cargo run -p xtask -- generate-rpc-typescript --output path/to/generated-host
# or
make rpc-typescript-generate OUTPUT=path/to/generated-host

Validation

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

Build the current-platform Desktop shell without an installer:

make desktop-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, the self-contained host OpenRPC bundle and schema/profile artifacts, and Python distributions, uploads checksums, and publishes crates plus the Python package 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-cli 0.10.0