What Is the DuckDB Mirror and the Quack Protocol in agentsview?

The DuckDB mirror is a read-only analytical copy of agentsview's SQLite session data, while the Quack protocol is an HTTP-based extension that exposes DuckDB as a remote catalog accessible via quack: URIs.

agentsview maintains SQLite as its primary write-store for session data, but creates a separate DuckDB mirror to enable fast analytical queries without complicating the write path. The repository implements the Quack protocol to allow remote access to this mirror, turning the local DuckDB file into an HTTP-accessible service that other processes can attach to as a remote catalog.

What Is the DuckDB Mirror in agentsview?

The DuckDB mirror is a push-sync copy of the primary SQLite archive stored in a .duckdb file. According to the source code in internal/duckdb/sync.go, the mirror copies sessions, messages, tool-calls, and analytics from the SQLite primary to DuckDB using a read-only synchronization process.

This architecture separates write-heavy operational workloads (handled by SQLite) from read-heavy analytical workloads (handled by DuckDB). The sync logic preserves project include/exclude filters and watermark handling, mirroring the same patterns used in the PostgreSQL push implementation.

Key characteristics of the mirror:

• Read-only: The mirror never accepts direct writes; it only reflects data pushed from the primary SQLite store
• Analytical focus: Optimized for full-text search, aggregations, and trend analysis
• File-based: Stored as a local .duckdb file specified in the configuration

What Is the Quack Protocol?

The Quack protocol leverages DuckDB's Quack extension to transform a local DuckDB instance into an HTTP-accessible service. In internal/duckdb/connect.go, agentsview implements support for quack: URIs that allow remote attachment to DuckDB catalogs.

The protocol specification includes:

• URI scheme: quack: (e.g., quack:127.0.0.1:9494)
• Default port: 9494
• Transport: HTTP for loopback, HTTPS for remote hosts
• Authentication: Token-based via secrets or TOKEN= parameters
• Attachment: ATTACH 'quack:host' AS remote makes remote tables visible locally
• Transaction forwarding: Client writes are forwarded to the server

When you run agentsview duckdb quack serve, the CLI (implemented in cmd/agentsview/duckdb.go) loads the extension, installs it, and calls quack_serve() to bind the local DuckDB file to the specified endpoint.

How the Architecture Works Together

The agentsview storage architecture follows a hierarchical pattern:

1. SQLite serves as the single source of truth, handling all file-watch sync and parser writes
2. DuckDB mirror receives push-sync data from SQLite via internal/duckdb/sync.go, providing a lightweight analytics store queryable via the standard db.Store interface
3. Quack protocol exposes the local mirror as a remote endpoint, enabling collaboration or testing without sharing the original SQLite archive

This separation allows the application to maintain ACID compliance on the write path while supporting complex analytical queries on the read path.

Configuration and Usage Examples

Configuring the DuckDB Mirror

Create a configuration file at ~/.agentsview/config.toml to specify the mirror location and Quack connection details:

[duckdb]
path = "~/.agentsview/sessions.duckdb"
url  = "quack:localhost"
token = "$AGENTSVIEW_DUCKDB_TOKEN"
machine_name = "my-machine"
allow_insecure = false
projects = []          # optional whitelist

exclude_projects = []  # optional blacklist

Starting a Quack Server

Launch a Quack server to expose your DuckDB mirror via HTTP:

agentsview duckdb quack serve \
    --bind quack:127.0.0.1:9494 \
    --token my-secret-token

The server installs and loads the Quack extension, then calls quack_serve to bind the local DuckDB file to the specified URI.

Connecting to a Remote Quack Endpoint

Attach to a remote Quack server from Go code by loading the extension and using the ATTACH command:

import (
    "context"
    "database/sql"
    _ "github.com/duckdb/duckdb-go/v2"
)

func openRemoteDuckDB(uri string) (*sql.DB, error) {
    // uri must start with "quack:"
    db, err := sql.Open("duckdb", uri)
    if err != nil { 
        return nil, err 
    }

    // Load the extension (no-op if already loaded)
    if _, err = db.Exec(`INSTALL quack`); err != nil { 
        return nil, err 
    }
    if _, err = db.Exec(`LOAD quack`); err != nil { 
        return nil, err 
    }

    // Attach the remote catalog
    _, err = db.ExecContext(context.Background(),
        `ATTACH '`+uri+`' AS remote`)
    return db, err
}

Querying via the Read-Store Interface

Access the mirror through agentsview's storage abstraction:

store, err := duckdb.NewStore("quack:localhost", cfg.DuckDB.Token)
if err != nil { 
    log.Fatal(err) 
}

sessions, err := store.ListSessions(context.Background(), nil)
if err != nil { 
    log.Fatal(err) 
}
fmt.Printf("Found %d sessions in DuckDB mirror\n", len(sessions))

Key Implementation Files

The DuckDB mirror and Quack protocol implementation spans these critical files in the agentsview repository:

• internal/duckdb/sync.go – Implements push-only synchronization from the SQLite primary archive to the DuckDB mirror, handling project filters and watermarks
• internal/duckdb/connect.go – Manages connection setup, Quack extension installation, and URI validation for quack: endpoints
• cmd/agentsview/duckdb.go – CLI entry points for duckdb push, duckdb status, duckdb serve, and duckdb quack serve commands
• docs/duckdb-backend-plan.md – Design documentation describing the mirror concept and Quack integration strategy
• internal/duckdb/quack_smoke_duckdbtest_test.go – Smoke tests that verify Quack server startup, client attachment, and round-trip reads/writes

Summary

• The DuckDB mirror is a read-only, push-sync copy of agentsview's SQLite data optimized for analytical queries
• The Quack protocol exposes DuckDB via HTTP using quack: URIs, enabling remote catalog attachment
• Synchronization logic lives in internal/duckdb/sync.go and follows the same watermark patterns as the PostgreSQL implementation
• Remote connectivity is handled in internal/duckdb/connect.go with token-based authentication
• This dual-database architecture keeps SQLite as the write-optimized source of truth while providing DuckDB's analytical capabilities for complex queries

Frequently Asked Questions

Why does agentsview use both SQLite and DuckDB instead of just one database?

agentsview keeps SQLite as the primary write-store because it handles file-watch synchronization and parser writes with minimal complexity. DuckDB serves as a specialized read-only mirror for analytical workloads like full-text search and aggregations. This separation prevents analytical queries from impacting write performance while giving users advanced SQL capabilities for data exploration.

Is the DuckDB mirror read-write or read-only?

The DuckDB mirror is strictly read-only regarding direct writes. All data flows into the mirror through the push-sync process defined in internal/duckdb/sync.go, which copies data from the SQLite primary. When using the Quack protocol, writes initiated on the client are forwarded to the server, but they modify the DuckDB file itself rather than the primary SQLite archive.

How does authentication work with the Quack protocol?

Authentication uses token-based validation. When starting a Quack server with agentsview duckdb quack serve, you specify a --token parameter. Clients must provide this token either through the TOKEN= URI parameter or via environment variables like $AGENTSVIEW_DUCKDB_TOKEN. The implementation in internal/duckdb/connect.go validates these tokens before establishing the connection.

Can I use the Quack protocol without the DuckDB mirror?

No, the Quack protocol in agentsview is designed specifically to expose the DuckDB mirror. The mirror must exist first (created via the sync process in internal/duckdb/sync.go) before you can serve it via Quack. The CLI command agentsview duckdb quack serve binds to the DuckDB file specified in your configuration, which assumes the mirror has been initialized and populated with data from the primary SQLite store.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}