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.

[!WARNING] Desktop is work in progress. apps/starweaver-desktop is experimental, is not a supported product, and is currently excluded from CI, release packaging, and active maintenance. Use the CLI, Rust/Python SDKs, or standalone RPC host for supported workflows.

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, subagents, bounded CodeAct composition, reusable recipes, and opt-in macOS Computer Use observation, pointer/keyboard input, and bounded Accessibility metadata.
• A CLI launcher with profile-based local runs, install/update flow, display messages, local storage, and release artifacts.
• An experimental, maintenance-paused Tauri 2 Desktop foundation retained as WIP source code.

Install

Install the latest public release:

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

The installer downloads all components available for the current platform and verifies checksums.txt when available. It installs starweaver, starweaver-cli, sw, and starweaver-rpc; on macOS it also installs the full-family external-harness starweaver-computer-use-mcp binary. 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.

To omit the separate Computer Use MCP binary from a macOS install:

curl -fsSL https://raw.githubusercontent.com/Wh1isper/starweaver/main/scripts/install.sh \
  | STARWEAVER_EXCLUDE_COMPONENTS=computer-use sh

Installing the binary does not enable Computer Use in CLI or RPC. Both products keep the Toolset default-disabled and use the Computer Use library in-process instead of this MCP binary. Launching the standalone MCP server is its own explicit opt-in to the full canonical observe, pointer, and keyboard family. Screen Recording and Accessibility/post-event permissions remain authoritative. Unsigned and not-notarized executables may have less stable TCC identity and additional OS warnings, but signing is not an input-availability gate. See Computer Use for configuration and security boundaries.

Update all installed components available for the current platform 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:

• Quickstart
• Agent SDK
• Python SDK
• Agents
• Models
• Tools
• Structured Output
• CLI
• Computer Use
• Testing
• Release

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-computer-use: typed current-active-desktop service, canonical tool router, deterministic fake, macOS pixel observation plus bounded Accessibility and high-level pointer/keyboard backend, and feature-gated full-family stdio MCP binary.
• 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: experimental WIP Tauri 2 shell; CI, release packaging, and active maintenance are paused.
• 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/. Maintained generation writes the bundled OpenRPC artifact, core manifest, and Rust server bindings without changing frozen Desktop projections:

make rpc-idl-core-generate

The historical full make rpc-idl-generate target is retained for a future Desktop reactivation and must not be used while the maintenance freeze is active.

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
make rpc-typescript-check

Validation

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

Desktop-specific validation and build targets are intentionally outside the maintained gate while the Desktop project is paused.

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 packages the maintained CLI/protocol, Rust crates, Python distribution, and separate macOS Computer Use MCP archives. Desktop installers and Desktop-managed runtime update assets are not published while Desktop remains WIP.

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