Architecture - Weaver AI Codebase Tooling

System Topology

The Weaver architecture separates the ephemeral nature of CLI commands from the persistent state of the analysis daemon. This split ensures speed for user interactions while maintaining deep, semantic context in the background.

CLI Client (Ephemeral)
Weaver Daemon (Persistent)
LSP / Tree-sitter Integrations

FIG 3.0

System-topology illustration showing the Weaver CLI shell, daemon, semantic fusion core, JSONL output, and analysis engines.

CORE COMPONENT

Semantic Fusion Engine

The heart of Weaver is the Fusion Engine. It ingests raw code, syntax-tree data, and LSP diagnostics to build the internal semantic structures behind every read, query, and change command.

Multi-Source Ingestion

Combines static analysis (Tree-sitter) with dynamic runtime data (LSP) to resolve references that static analysis misses.

Provenance Tagging

Every piece of data carries a provenance trail. We know exactly why the AI thinks a function is relevant.

INTERNAL TELEMETRY: FUSION_OUTPUT ● LIVE

{"timestamp": "2026-03-15T10:00:01Z", "type": "scan_start", "target": "src/"}

{
"type": "semantic_node",
"id": "fn::process_data",
"provenance": {
"source": "tree-sitter-rust",
"confidence": 0.98
},
"relationships": [
"calls::validate_input",
"uses::DataStruct"
]
}

{"timestamp": "2026-03-15T10:00:02Z", "type": "scan_complete", "nodes": 142}

Figure 3.1: Internal fusion telemetry, not the public CLI and daemon JSONL envelope.

ARCHITECTURE

Client–Daemon Model

Decoupling the user interface from the intelligence engine allows for persistent context and faster CLI response times.

The Daemon

weaver daemon

Hosts LSP child processes (rust-analyzer, pyrefly lsp, etc.).
Dispatches JSONL requests from the CLI and streams responses.
Uses a Unix domain socket by default on Unix; the prototype retains loopback-only TCP for non-Unix compatibility.
Auto-starts when a domain command is issued — no manual launch needed.

Manual lifecycle:

$ weaver daemon start

The Client

weaver <resource> <verb>

Parses config (--config-path, XDG, env vars) and CLI flags.
Sends JSONL requests to the daemon, streams the response.
Renders readable output on a TTY; --json is the one switch to the stable machine contract.

Usage example:

$ weaver definitions get --uri file:///src/main.rs --position 10:5

Planned — RFC 0002

One Daemon, Many Workspaces

One local, per-user weaverd serves every repository. Each request carries a workspace locator; the daemon – never the client – canonicalizes it into the key that owns caches, language servers, and the mutation coordinator. A client path is untrusted input, not filesystem authority.

Isolated by identity

Language servers are keyed by their full execution identity: language, command, resolved toolchain, and workspace roots. Unrelated repositories never share a process, and a missing rustup component returns structured installation guidance rather than a silent fallback.

Concurrent by default

No daemon-wide mutex. Unrelated workspaces and languages progress in parallel under bounded admission at daemon, workspace, and server scope. Saturation returns a structured, retryable overload result naming the scope and the wait – not a dropped connection.

Local and quiet

Single-user and local-only: no remotely reachable endpoint or remote authentication. The prototype's loopback-only TCP compatibility path does not turn the planned per-user model into a network service. Logs and metrics carry bounded, opaque workspace identifiers – never raw paths, environment values, source contents, or patch bodies.

Data Flow & Provenance

Weaver ensures that every insight provided to the AI agent can be traced back to a source of truth.

Ingestion & Parsing

When a file is observed, the Daemon invokes Tree-sitter to generate a Concrete Syntax Tree (CST).

source.rs CST

Sempai Pattern Matching

The Sempai Engine runs structural queries against the CST to identify high-level constructs (functions, classes, API endpoints).

LSP Enrichment

If available, the Language Server is queried for type definitions, references, and documentation, enriching the static nodes with semantic context.

Graph Fusion

All data points merge into the semantic graph. Every node carries its evidence: an LSP-confirmed edge outranks a purely syntactic one, and the provenance says which is which.

Graph Integrity 75% Confirmed

Explore the Toolkit

Now that you understand the architecture, see how to wield it.

Command Reference Quick Start

The Loom of Structured Intelligence.