### Generate session guide

Source: https://github.com/ojuschugh1/sqz/blob/main/docs/doc/src/sqz_engine/session_continuity.rs.html

Creates a structured XML-wrapped guide from snapshot events, categorized by type and capped by character limits.

```rust
    pub fn generate_guide(&self, snapshot: &Snapshot) -> SessionGuide {
        // Collect events grouped by category label, preserving priority order.
        // We use an ordered list of (label, entries) to keep output deterministic.
        let category_order: &[SnapshotEventType] = &[
            SnapshotEventType::LastPrompt,
            SnapshotEventType::Error,
            SnapshotEventType::Decision,
            SnapshotEventType::PendingTask,
            SnapshotEventType::ActiveFile,
            SnapshotEventType::GitOp,
            SnapshotEventType::Rule,
            SnapshotEventType::ToolUse,
            SnapshotEventType::Warning,
            SnapshotEventType::Learning,
            SnapshotEventType::Progress,
            SnapshotEventType::Context,
            SnapshotEventType::Environment,
            SnapshotEventType::Dependency,
            SnapshotEventType::Summary,
        ];

        // Group events by type.
        let mut groups: std::collections::HashMap<SnapshotEventType, Vec<&str>> =
            std::collections::HashMap::new();
        for event in &snapshot.events {
            groups
                .entry(event.event_type)
                .or_default()
                .push(&event.content);
        }

        // Build the inner body, respecting the char budget.
        // Reserve space for the XML wrapper (~50 chars).
        let wrapper_overhead = "<session_knowledge>\n</session_knowledge>\n".len();
        let body_budget = MAX_GUIDE_CHARS.saturating_sub(wrapper_overhead);
        let mut body = String::with_capacity(body_budget);

        for &cat in category_order {
            if let Some(entries) = groups.get(&cat) {
                let label = cat.label();
                // Format: <label>: entry1; entry2; ...\n
```

--------------------------------

### Install Extension via CLI

Source: https://github.com/ojuschugh1/sqz/blob/main/docs/integrations/level3/vscode-marketplace.md

Install the published extension directly from the command line.

```sh
code --install-extension sqz.sqz
```

--------------------------------

### Install sqz and rtk, Run Benchmark

Source: https://github.com/ojuschugh1/sqz/blob/main/docs/benchmark-vs-rtk.md

Installs both sqz and rtk command-line tools and executes the benchmark suite for sqz. Use this to reproduce performance numbers.

```sh
cargo install --git https://github.com/rtk-ai/rtk
cargo install sqz-cli
```

```sh
cargo test -p sqz-engine benchmarks -- --nocapture
```

--------------------------------

### install

Source: https://github.com/ojuschugh1/sqz/blob/main/docs/doc/sqz/shell_hook/enum.ShellHook.html

Installs the hook into the shell RC file.

```APIDOC
## install

### Description
Installs the hook into the shell RC file. Returns Ok(true) when the hook was written, Ok(false) when it was already present. On failure the error is logged and the function returns Err.

### Response
- **Success Response (200)**
  - **result** (bool) - Returns true if the hook was written, false if it was already present.
```

--------------------------------

### Install sqz CLI

Source: https://github.com/ojuschugh1/sqz/blob/main/npm/README.md

Installation instructions for the sqz CLI tool using cargo.

```sh
# Confirmed working:
cargo install sqz-cli

# Coming soon (scaffolded, not yet live):
# curl -fsSL https://raw.githubusercontent.com/ojuschugh1/sqz/main/install.sh | sh
# brew install sqz
# npm install -g sqz-cli
# pip install sqz
```

--------------------------------

### Development Setup

Source: https://github.com/ojuschugh1/sqz/blob/main/README.md

Commands to clone the repository, run tests, and build the project.

```sh
git clone https://github.com/ojuschugh1/sqz.git
cd sqz
cargo test --workspace
cargo build --release
```

--------------------------------

### Default Configuration File

Source: https://github.com/ojuschugh1/sqz/blob/main/README.md

Example configuration file located at ~/.sqz/presets/default.toml.

```toml
# ~/.sqz/presets/default.toml
[preset]
name = "default"
version = "1.0"

[compression.condense]
enabled = true
max_repeated_lines = 3

[compression.strip_nulls]
enabled = true

[budget]
warning_threshold = 0.70
default_window_size = 200000
```

--------------------------------

### Development Setup

Source: https://github.com/ojuschugh1/sqz/blob/main/npm/README.md

Instructions for cloning the repository, setting up the development environment, and running tests and builds.

```APIDOC
## Development

Follow these steps to set up the development environment and build the project.

### Cloning the Repository

```sh
git clone https://github.com/ojuschugh1/sqz.git
cd sqz
```

### Running Tests and Builds

```sh
# Run all tests across the workspace
cargo test --workspace

# Build the release (optimized) binary
cargo build --release
```
```

--------------------------------

### Start MCP Server

Source: https://context7.com/ojuschugh1/sqz/llms.txt

Start the MCP server to expose sqz compression over the Model Context Protocol. Supports stdio and SSE transports.

```bash
# Start on stdio (default for local tool integration)
sqz-mcp --preset-dir ~/.sqz/presets
```

```bash
# Start on SSE for network access
sqz-mcp --preset-dir ~/.sqz/presets --transport sse --port 3002
```

--------------------------------

### Install sqz CLI

Source: https://github.com/ojuschugh1/sqz/blob/main/README.md

Install the sqz command-line interface using Cargo. This is the first step to enable context compression for your AI tools.

```sh
cargo install sqz-cli
```

--------------------------------

### Install Shell Completions

Source: https://github.com/ojuschugh1/sqz/blob/main/docs/doc/src/sqz/main.rs.html

Installs shell-specific completion scripts to the appropriate system directories.

```rust
fn install_completions(hook: &ShellHook) {
    let home = std::env::var("HOME")
        .or_else(|_| std::env::var("USERPROFILE"))
        .map(std::path::PathBuf::from)
        .unwrap_or_else(|_| std::path::PathBuf::from("."));

    let (dest, content): (std::path::PathBuf, &str) = match hook {
        ShellHook::Fish => (
            home.join(".config").join("fish").join("completions").join("sqz.fish"),
            include_str!("../completions/sqz.fish"),
        ),
        ShellHook::Zsh => (
            home.join(".zsh").join("completions").join("_sqz"),
            include_str!("../completions/sqz.zsh"),
        ),
        ShellHook::Bash => (
            home.join(".local").join("share").join("bash-completion").join("completions").join("sqz"),
            include_str!("../completions/sqz.bash"),
        ),
        ShellHook::Nushell => (
            home.join(".config").join("nushell").join("completions").join("sqz.nu"),
            include_str!("../completions/sqz.nu"),
        ),
        ShellHook::PowerShell => {
            // Append to PowerShell profile
            let profile = std::env::var("PROFILE")
                .map(std::path::PathBuf::from)
                .unwrap_or_else(|_| {
                    home.join("Documents")
                        .join("PowerShell")
                        .join("Microsoft.PowerShell_profile.ps1")
                });
            (profile, include_str!("../completions/sqz.ps1"))
        }
    };

    if let Some(parent) = dest.parent() {
        if std::fs::create_dir_all(parent).is_err() {
            return; // silently skip if we can't create the dir
        }
    }

    // For PowerShell, append to profile rather than overwrite
    let write_result = if matches!(hook, ShellHook::PowerShell) {
        let existing = std::fs::read_to_string(&dest).unwrap_or_default();
        if existing.contains("Register-ArgumentCompleter -Native -CommandName sqz") {
            return; // already installed
        }
        use std::io::Write;
        std::fs::OpenOptions::new()
            .create(true)
            .append(true)
            .open(&dest)
            .and_then(|mut f| writeln!(f, "\n{content}"))
    } else {
        std::fs::write(&dest, content)
    };
}
```

--------------------------------

### Test guide generation performance

Source: https://github.com/ojuschugh1/sqz/blob/main/docs/doc/src/sqz_engine/session_continuity.rs.html

Verifies that guide generation completes within a 50ms threshold.

```rust
let snapshot = Snapshot { events };

let start = std::time::Instant::now();
let _guide = mgr.generate_guide(&snapshot);
let elapsed = start.elapsed();

assert!(
    elapsed.as_millis() < 50,
    "generate_guide took {}ms, expected <50ms",
    elapsed.as_millis()
);
```

--------------------------------

### Initialize Command Implementation

Source: https://github.com/ojuschugh1/sqz/blob/main/docs/doc/src/sqz/main.rs.html

Handles shell hook installation, completion generation, and default preset creation.

```rust
/// `sqz init` — detect shell, install hook, create default preset.
fn cmd_init() {
    let hook = ShellHook::detect();
    println!("[sqz] detected shell: {:?}", hook);

    match hook.install() {
        Ok(true) => println!("[sqz] hook installed to {}", hook.rc_path().display()),
        Ok(false) => println!("[sqz] hook already present in {}", hook.rc_path().display()),
        Err(e) => {
            // Requirement 1.5: log error and continue without aborting.
            eprintln!("[sqz] warning: {e}");
            eprintln!("[sqz] shell hook installation failed; output will pass uncompressed.");
        }
    }

    // Install shell completions
    install_completions(&hook);

    // Create default preset directory and file.
    let preset_dir = default_preset_dir();
    if let Err(e) = std::fs::create_dir_all(&preset_dir) {
        eprintln!("[sqz] warning: could not create preset dir {}: {e}", preset_dir.display());
    } else {
        let preset_path = preset_dir.join("default.toml");
        if !preset_path.exists() {
            match std::fs::write(&preset_path, DEFAULT_PRESET_TOML) {
                Ok(()) => println!("[sqz] default preset written to {}", preset_path.display()),
                Err(e) => eprintln!("[sqz] warning: could not write preset: {e}"),
            }
        } else {
            println!("[sqz] default preset already exists at {}", preset_path.display());
        }
    }

    // Install AI tool hooks (Claude Code, Cursor, Windsurf, Cline)
    let sqz_path = std::env::current_exe()
        .map(|p| p.to_string_lossy().to_string())
        .unwrap_or_else(|_| "sqz".to_string());
```

--------------------------------

### Install Shell Completions

Source: https://github.com/ojuschugh1/sqz/blob/main/docs/doc/sqz/fn.install_completions.html

Installs shell completions for the detected shell using the provided ShellHook.

```APIDOC
## POST /sqz/install_completions

### Description
Install shell completions for the detected shell.

### Method
POST

### Endpoint
/sqz/install_completions

### Parameters
#### Request Body
- **hook** (ShellHook) - Required - The shell hook to use for installing completions.

### Request Example
{
  "hook": {
    "shell": "bash",
    "path": "/path/to/completion/script"
  }
}

### Response
#### Success Response (200)
- **message** (string) - A confirmation message indicating successful installation.

#### Response Example
{
  "message": "Shell completions installed successfully for bash."
}
```

--------------------------------

### Start sqz-mcp on stdio

Source: https://github.com/ojuschugh1/sqz/blob/main/docs/doc/sqz_mcp/index.html

Starts the sqz-mcp server using stdio transport, which is the default for MCP tool integration. Specify the directory containing TOML preset files.

```bash
sqz-mcp --preset-dir ~/.sqz/presets
```

--------------------------------

### Test SessionContinuityManager Guide Generation

Source: https://github.com/ojuschugh1/sqz/blob/main/docs/doc/src/sqz_engine/session_continuity.rs.html

Verifies that all 15 category labels are correctly included in the generated guide text.

```rust
                SnapshotEvent::new(SnapshotEventType::GitOp, "commit abc123".into()),
                SnapshotEvent::new(SnapshotEventType::Rule, "No unwrap in prod".into()),
                SnapshotEvent::new(SnapshotEventType::ToolUse, "read_file".into()),
                SnapshotEvent::new(SnapshotEventType::Warning, "Deprecated API".into()),
                SnapshotEvent::new(SnapshotEventType::Learning, "Project uses ESM".into()),
                SnapshotEvent::new(SnapshotEventType::Progress, "Auth module done".into()),
                SnapshotEvent::new(SnapshotEventType::Context, "REST API project".into()),
                SnapshotEvent::new(SnapshotEventType::Environment, "Rust 1.75".into()),
                SnapshotEvent::new(SnapshotEventType::Dependency, "serde 1.0".into()),
                SnapshotEvent::new(SnapshotEventType::Summary, "Working on auth".into()),
            ],
        };

        let guide = mgr.generate_guide(&snapshot);

        // All 15 category labels should appear.
        assert!(guide.text.contains("last_request:"));
        assert!(guide.text.contains("errors:"));
        assert!(guide.text.contains("decisions:"));
        assert!(guide.text.contains("tasks:"));
        assert!(guide.text.contains("files:"));
        assert!(guide.text.contains("git:"));
        assert!(guide.text.contains("rules:"));
        assert!(guide.text.contains("tools:"));
        assert!(guide.text.contains("warnings:"));
        assert!(guide.text.contains("learnings:"));
        assert!(guide.text.contains("progress:"));
        assert!(guide.text.contains("context:"));
        assert!(guide.text.contains("environment:"));
        assert!(guide.text.contains("dependencies:"));
        assert!(guide.text.contains("summary:"));
    }
```

--------------------------------

### Start sqz-mcp on SSE

Source: https://github.com/ojuschugh1/sqz/blob/main/docs/doc/sqz_mcp/index.html

Starts the sqz-mcp server using SSE transport for network access. Specify the preset directory, transport mode, and port.

```bash
sqz-mcp --preset-dir ~/.sqz/presets --transport sse --port 3002
```

--------------------------------

### Sqz-MCP Server Configuration

Source: https://github.com/ojuschugh1/sqz/blob/main/docs/doc/src/sqz_mcp/lib.rs.html

Instructions on how to start the sqz-mcp server with different transport options and preset directories.

```APIDOC
## Sqz-MCP Server Configuration

### Description

The sqz-mcp server can be started with different transport modes and configured to load presets from a specified directory.

### Usage

**Start on stdio (default for MCP tool integration):**
```bash
sqz-mcp --preset-dir ~/.sqz/presets
```

**Start on SSE for network access:**
```bash
sqz-mcp --preset-dir ~/.sqz/presets --transport sse --port 3002
```

### Parameters

- `--preset-dir` (string) - Required - The directory to load preset `.toml` files from.
- `--transport` (string) - Optional - The transport mode. Can be `stdio` (default) or `sse`.
- `--port` (number) - Optional - The port to use when `transport` is `sse`.
```

--------------------------------

### Install VSCE CLI

Source: https://github.com/ojuschugh1/sqz/blob/main/docs/integrations/level3/vscode-marketplace.md

Install the Visual Studio Code Extension Manager globally to enable publishing commands.

```sh
npm install -g @vscode/vsce
```

--------------------------------

### Server Configuration

Source: https://github.com/ojuschugh1/sqz/blob/main/docs/doc/sqz_mcp/index.html

Command line interface usage for starting the sqz-mcp server.

```APIDOC
# Start on stdio (default for MCP tool integration)
sqz-mcp --preset-dir ~/.sqz/presets

# Start on SSE for network access
sqz-mcp --preset-dir ~/.sqz/presets --transport sse --port 3002
```

--------------------------------

### Format NPM Install Output

Source: https://github.com/ojuschugh1/sqz/blob/main/docs/doc/src/sqz_engine/cmd_formatters.rs.html

Formats the output of an npm install command. Asserts that the result contains specific package information.

```rust
let result = format_npm_install(output);
assert!(result.contains("added 42 packages"));
```

--------------------------------

### GET /summary

Source: https://github.com/ojuschugh1/sqz/blob/main/docs/doc/sqz_engine/dependency_mapper/struct.DependencyMapper.html

Produces a compact dependency summary string for a given file path.

```APIDOC
## GET /summary

### Description
Produce a compact dependency summary string suitable for inclusion in file read output.

### Parameters
#### Path Parameters
- **path** (Path) - Required - The file path to summarize.

### Response
#### Success Response (200)
- **summary** (String) - A compact string representation of the dependencies.
```

--------------------------------

### Run API Proxy

Source: https://context7.com/ojuschugh1/sqz/llms.txt

Start a transparent HTTP proxy to compress API requests to major AI providers.

```bash
sqz proxy --port 8080
```

```bash
export OPENAI_BASE_URL=http://127.0.0.1:8080/v1
python my_app.py
```

--------------------------------

### DashboardServer::run

Source: https://github.com/ojuschugh1/sqz/blob/main/docs/doc/sqz_engine/dashboard/struct.DashboardServer.html

Start listening. This blocks the calling thread.

```APIDOC
## pub fn run(&self) -> Result<()>

### Description

Start listening. This blocks the calling thread.

For each incoming connection the server reads the HTTP request line, then either:

*   `GET /` → responds with the full HTML page
*   `GET /events` → responds with an SSE stream (pushes metrics JSON every 5 seconds until the client disconnects)
*   anything else → 404

### Method

GET

### Endpoint

/api/dashboard/server/run

### Response

#### Success Response (200)

- **status** (string) - Indicates the server has started successfully.
```

--------------------------------

### sqz init

Source: https://context7.com/ojuschugh1/sqz/llms.txt

Initializes the sqz environment by installing shell hooks and configuring integrations for AI coding tools.

```APIDOC
## sqz init

### Description
Installs shell hooks and configures AI tool integrations (Claude Code, Cursor, Windsurf, Cline, Gemini CLI). It detects the user's shell, installs completion scripts, and creates default presets.

### Method
CLI Command

### Parameters
None
```

--------------------------------

### Add Kotlin File and Get Dependencies

Source: https://github.com/ojuschugh1/sqz/blob/main/docs/doc/src/sqz_engine/dependency_mapper.rs.html

Adds a Kotlin file and checks if 'com/example/MyClass' is listed as a dependency.

```rust
let source = "import com.example.MyClass\nimport kotlin.collections.List\n";
        mapper.add_file(Path::new("src/Main.kt"), source);
        let deps = mapper.dependencies_of(Path::new("src/Main.kt"));
        assert!(deps.iter().any(|p| p.to_string_lossy().contains("com/example/MyClass")));
```

--------------------------------

### Add Swift File and Get Dependencies

Source: https://github.com/ojuschugh1/sqz/blob/main/docs/doc/src/sqz_engine/dependency_mapper.rs.html

Adds a Swift file and verifies that 'Foundation' and 'UIKit' are recognized as dependencies.

```rust
let source = "import Foundation\nimport UIKit\n";
        mapper.add_file(Path::new("Sources/App.swift"), source);
        let deps = mapper.dependencies_of(Path::new("Sources/App.swift"));
        assert!(deps.iter().any(|p| p.to_string_lossy() == "Foundation"));
        assert!(deps.iter().any(|p| p.to_string_lossy() == "UIKit"));
```

--------------------------------

### Get Shell Hook Sentinel

Source: https://github.com/ojuschugh1/sqz/blob/main/docs/doc/src/sqz/shell_hook.rs.html

Provides a unique sentinel comment string used to detect if the hook is already installed, preventing duplicate installations.

```rust
    /// A unique sentinel comment used to detect whether the hook is already
    /// installed, preventing duplicate entries.
    pub fn sentinel(&self) -> &'static str {
        "# sqz — context intelligence layer (auto-installed)"
    }
```

--------------------------------

### Verify Claude Code Installation

Source: https://github.com/ojuschugh1/sqz/blob/main/docs/integrations/level2/claude-code.md

Execute this command to verify that shell hooks are active and the MCP server is listed. This confirms the setup is complete.

```sh
sqz status
```

--------------------------------

### Initialize TokenPruner with Default Configuration

Source: https://github.com/ojuschugh1/sqz/blob/main/docs/doc/src/sqz_engine/token_pruner.rs.html

Creates a new TokenPruner instance using the default configuration and loads built-in trigram patterns. This is the simplest way to get started.

```rust
pub fn new() -> Self {
        Self::with_config(PrunerConfig::default())
    }
```

--------------------------------

### Install Hook to File

Source: https://github.com/ojuschugh1/sqz/blob/main/docs/doc/sqz/shell_hook/index.html

Appends the sqz script to a specified file unless a sentinel is already present.

```APIDOC
## POST /api/shell_hook/install

### Description
Appends `script` to `path` unless `sentinel` is already present.

### Method
POST

### Endpoint
`/api/shell_hook/install`

### Parameters
#### Query Parameters
- **path** (string) - Required - The file path to install the hook into.
- **script** (string) - Required - The script content to append.
- **sentinel** (string) - Required - A string to check for the presence of the hook.

### Request Example
```json
{
  "path": "~/.bashrc",
  "script": "eval \"$(sqz --hook bash)\"",
  "sentinel": "# sqz hook"
}
```

### Response
#### Success Response (200)
- **message** (string) - Indicates the success of the operation.

#### Response Example
```json
{
  "message": "Hook installed successfully."
}
```
```

--------------------------------

### Initialize and use SqzEngine

Source: https://github.com/ojuschugh1/sqz/blob/main/docs/doc/sqz_engine/index.html

Demonstrates how to instantiate the engine and compress both plain text and JSON strings.

```rust
use sqz_engine::SqzEngine;

let engine = SqzEngine::new().expect("failed to init engine");

// Compress some text
let result = engine.compress("hello world").unwrap();
println!("compressed: {}", result.data);
println!("tokens: {} → {}", result.tokens_original, result.tokens_compressed);

// JSON gets TOON-encoded automatically
let json_result = engine.compress(r#"{"name": "Alice", "age": 30}"#).unwrap();
assert!(json_result.data.starts_with("TOON:"));
```

--------------------------------

### Install AI Tool Hooks

Source: https://github.com/ojuschugh1/sqz/blob/main/docs/doc/src/sqz/main.rs.html

Installs AI tool hooks for the current project directory. It checks if any tools were installed and prints a confirmation message.

```rust
let project_dir = std::env::current_dir().unwrap_or_else(|_| std::path::PathBuf::from("."));
    let installed_tools = sqz_engine::install_tool_hooks(&project_dir, &sqz_path);
    if !installed_tools.is_empty() {
        println!("[sqz] AI tool hooks installed for: {}", installed_tools.join(", "));
    }

    println!("[sqz] init complete. Restart your shell or source the RC file.");
```

--------------------------------

### Initialize SqzEngine

Source: https://github.com/ojuschugh1/sqz/blob/main/docs/doc/src/sqz_engine/engine.rs.html

Opens or creates session and pin stores, then initializes the SqzEngine with various components including preset, pipeline, model router, session store, cache manager, budget tracker, cost calculator, AST parser, terse mode, pin manager, confidence router, and plugin loader.

```rust
let cache_store = SessionStore::open_or_create(store_path)?;
let pin_store = SessionStore::open_or_create(store_path)?;

Ok(SqzEngine {
    preset: Arc::new(Mutex::new(preset.clone())),
    pipeline: Arc::new(Mutex::new(pipeline)),
    model_router: Arc::new(Mutex::new(ModelRouter::new(&preset))),
    session_store,
    cache_manager: CacheManager::new(cache_store, 512 * 1024 * 1024),
    budget_tracker: BudgetTracker::new(window_size, &preset),
    cost_calculator: CostCalculator::with_defaults(),
    ast_parser: AstParser::new(),
    terse_mode: TerseMode,
    pin_manager: PinManager::new(pin_store),
    confidence_router: ConfidenceRouter::new(),
    _plugin_loader: PluginLoader::new(Path::new("plugins")),
})
```

--------------------------------

### GET /compression_stats

Source: https://github.com/ojuschugh1/sqz/blob/main/docs/doc/sqz_engine/session_store/struct.SessionStore.html

Get cumulative compression stats from the log.

```APIDOC
## GET /compression_stats

### Description
Get cumulative compression stats from the log.
```

--------------------------------

### GET /sessions/{session_id}/cost

Source: https://github.com/ojuschugh1/sqz/blob/main/docs/doc/src/sqz_engine/engine.rs.html

Get the cost summary for a specific session.

```APIDOC
## GET /sessions/{session_id}/cost

### Description
Get cost summary for a session.

### Method
GET

### Endpoint
/sessions/{session_id}/cost

### Parameters
#### Path Parameters
- **session_id** (string) - Required - The ID of the session.
```

--------------------------------

### Generate Session Guide API

Source: https://github.com/ojuschugh1/sqz/blob/main/docs/doc/src/sqz_engine/session_continuity.rs.html

Generates a SessionGuide from a Snapshot, organizing events into categories for context window injection.

```APIDOC
## POST /api/snapshots/guide

### Description
Generates a structured session guide from a given snapshot. The guide organizes snapshot events into labeled categories and formats them as an XML directive suitable for context window injection.

### Method
POST

### Endpoint
/api/snapshots/guide

### Parameters
#### Request Body
- **snapshot** (Snapshot) - Required - The snapshot object from which to generate the guide.

### Request Example
```json
{
  "snapshot": {
    "events": [
      {
        "event_type": "Error",
        "content": "Failed to process request."
      },
      {
        "event_type": "Learning",
        "content": "Learned about error handling."
      }
    ]
  }
}
```

### Response
#### Success Response (200)
- **session_guide** (SessionGuide) - The generated session guide, formatted as an XML directive.

#### Response Example
```xml
<session_knowledge>
Error: Failed to process request.;
Learning: Learned about error handling.;
</session_knowledge>

```

--------------------------------

### Access CompressedContent results

Source: https://github.com/ojuschugh1/sqz/blob/main/docs/doc/sqz_engine/types/struct.CompressedContent.html

Example usage showing how to retrieve and print information from a CompressedContent instance returned by the engine.

```rust
let engine = SqzEngine::new().unwrap();
let result = engine.compress("hello world").unwrap();

println!("output: {}", result.data);
println!("ratio: {:.0}%", (1.0 - result.compression_ratio) * 100.0);
println!("stages: {:?}", result.stages_applied);
```

--------------------------------

### MCP JSON-RPC Command-Line Examples

Source: https://context7.com/ojuschugh1/sqz/llms.txt

Illustrates basic MCP JSON-RPC interactions using `sqz-mcp` via standard input and output, including initialization, listing tools, and calling a tool.

```bash
# Initialize connection
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' | sqz-mcp
# {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2024-11-05","capabilities":{"tools":{}},"serverInfo":{"name":"sqz-mcp","version":"0.5.0"}}}
```

```bash
# List available tools
echo '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' | sqz-mcp
# {"jsonrpc":"2.0","id":2,"result":{"tools":[{"name":"read_file","description":"Read the contents of a file..."}]}}
```

```bash
# List tools with intent filtering
echo '{"jsonrpc":"2.0","id":3,"method":"tools/list","params":{"intent":"search files"}}' | sqz-mcp
```

```bash
# Call a tool
echo '{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"read_file","arguments":{"path":"/tmp/test.json"}}}' | sqz-mcp
# {"jsonrpc":"2.0","id":4,"result":{"content":[{"type":"text","text":"TOON:{...}"}]}}
```

--------------------------------

### GET /daily_gains

Source: https://github.com/ojuschugh1/sqz/blob/main/docs/doc/sqz_engine/session_store/struct.SessionStore.html

Get daily compression gains for the last N days.

```APIDOC
## GET /daily_gains

### Description
Get daily compression gains for the last N days.

### Parameters
#### Query Parameters
- **days** (u32) - Required - Number of days to retrieve.
```

--------------------------------

### Initialize and Search SessionStore

Source: https://github.com/ojuschugh1/sqz/blob/main/docs/doc/sqz_engine/session_store/struct.SessionStore.html

Demonstrates opening or creating a session store and performing a full-text search.

```rust
use sqz_engine::SessionStore;
use std::path::Path;

let store = SessionStore::open_or_create(Path::new("~/.sqz/sessions.db")).unwrap();
let results = store.search("authentication refactor").unwrap();
for session in &results {
    println!("{}: {}", session.id, session.compressed_summary);
}
```

--------------------------------

### Initialize and Compress Text with SqzEngine

Source: https://github.com/ojuschugh1/sqz/blob/main/docs/doc/src/sqz_engine/lib.rs.html

Demonstrates basic usage of SqzEngine for compressing arbitrary text. It initializes the engine, compresses a string, and prints the compressed data along with original and compressed token counts. Ensure the engine is initialized successfully before use.

```rust
use sqz_engine::SqzEngine;

let engine = SqzEngine::new().expect("failed to init engine");

// Compress some text
let result = engine.compress("hello world").unwrap();
println!("compressed: {}", result.data);
println!("tokens: {} → {}", result.tokens_original, result.tokens_compressed);
```

--------------------------------

### Compress Data in Browser with SqzWasm

Source: https://context7.com/ojuschugh1/sqz/llms.txt

JavaScript example demonstrating how to initialize SqzWasm, compress JSON, code, and logs, estimate token counts, and manage session persistence using local storage.

```javascript
import init, { SqzWasm } from './pkg/sqz_wasm.js';

async function main() {
    await init();

    // Create compressor with preset: "minimal", "default", or "aggressive"
    const sqz = new SqzWasm("default");

    // Compress JSON — gets TOON-encoded, nulls stripped
    const json = '{"name": "Alice", "debug": null, "trace_id": null}';
    const compressed = sqz.compress(json);
    console.log(compressed); // TOON:{name:"Alice"}

    // Compress code — comments stripped, blank lines collapsed
    const code = "\
        // This is a comment
        fn main() {
            let x = 42;
        }
    ";
    console.log(sqz.compress(code));

    // Compress logs — repeated lines condensed
    const logs = "[INFO] Connected\n[INFO] Connected\n[INFO] Connected\n[ERROR] Timeout";
    console.log(sqz.compress(logs));

    // Estimate token count
    const tokens = sqz.estimate_tokens(compressed);
    console.log(`Estimated tokens: ${tokens}`);

    // Session export/import for persistence
    const ctx = sqz.export_ctx();
    localStorage.setItem('sqz_session', ctx);

    // Later: restore session
    const savedCtx = localStorage.getItem('sqz_session');
    if (savedCtx) {
        sqz.import_ctx(savedCtx);
    }
}

main();
```

--------------------------------

### SqzEngine::new

Source: https://github.com/ojuschugh1/sqz/blob/main/docs/doc/sqz_engine/engine/struct.SqzEngine.html

Creates a new instance of the SqzEngine with default presets and persistent session storage.

```APIDOC
## pub fn new()

### Description
Create a new engine with the default preset and a persistent session store. Sessions are stored in ~/.sqz/sessions.db for cross-session continuity, falling back to a temp-file store if the home directory is unavailable.

### Method
Rust Constructor

### Response
- **Result<Self>** - Returns a Result containing the new SqzEngine instance or an error if initialization fails.
```

--------------------------------

### Define sqz Configuration Structures

Source: https://github.com/ojuschugh1/sqz/blob/main/docs/doc/src/sqz_engine/preset.rs.html

Example of initializing configuration structs including budget, terse mode, and model settings.

```rust
                similarity_threshold: 0.7,
                default_tools: vec![
                    "read_file".to_string(),
                    "write_file".to_string(),
                    "search".to_string(),
                ],
            },
            budget: BudgetConfig {
                warning_threshold: 0.70,
                ceiling_threshold: 0.85,
                default_window_size: 200_000,
                agents: {
                    let mut m = HashMap::new();
                    m.insert("parent".to_string(), 0.60);
                    m.insert("child".to_string(), 0.20);
                    m
                },
            },
            terse_mode: TerseModeConfig {
                enabled: true,
                level: TerseLevel::Moderate,
            },
            model: ModelConfig {
                family: "anthropic".to_string(),
                primary: "claude-sonnet-4-20250514".to_string(),
                local: "llama-3.1-8b".to_string(),
                complexity_threshold: 0.4,
                pricing: Some(ModelPricingConfig {
                    input_per_1k: 0.003,
                    output_per_1k: 0.015,
                    cache_read_discount: 0.9,
                }),
            },
        }
    }
}
```

--------------------------------

### Format NPM Install Output

Source: https://github.com/ojuschugh1/sqz/blob/main/docs/doc/src/sqz_engine/cmd_formatters.rs.html

Parses npm install output to extract package counts or vulnerability reports.

```rust
fn format_npm_install(output: &str) -> String {
    let mut vulns = String::new();
    for line in output.lines() {
        if line.contains("added") && line.contains("packages") {
            return line.trim().to_string();
        }
        if line.contains("vulnerabilities") {
            vulns = line.trim().to_string();
        }
    }
    if !vulns.is_empty() {
        return format!("ok ({})", vulns);
    }
    "ok".to_string()
}
```

--------------------------------

### Initialize and Run MCP Server in Rust

Source: https://context7.com/ojuschugh1/sqz/llms.txt

Demonstrates setting up an MCP server in Rust, watching for preset hot-reloads, handling tool calls programmatically, listing tools with intent filtering, and starting the server on stdio.

```rust
use sqz_mcp::{McpServer, McpTransport, ToolCallRequest};
use std::path::Path;

fn main() {
    // Create MCP server
    let mut server = McpServer::new(Path::new("~/.sqz/presets")).unwrap();

    // Watch for preset hot-reload
    let _watcher = server.watch_presets().unwrap();

    // Handle tool call programmatically
    let request = ToolCallRequest {
        tool_id: "read_file".to_string(),
        input: serde_json::json!({"path": "/tmp/test.json"}),
        intent: None,
    };
    let response = server.handle_tool_call(request).unwrap();
    println!("Compressed: {} → {} tokens",
        response.tokens_original,
        response.tokens_compressed
    );

    // List tools with intent-based filtering
    let all_tools = server.list_tools(None).unwrap();
    println!("Available tools: {}", all_tools.len());

    let filtered = server.list_tools(Some("read file contents")).unwrap();
    println!("Matching tools: {}", filtered.len());

    // Start server on stdio
    server.start(McpTransport::Stdio).unwrap();
}
```

--------------------------------

### Install Shell Completions in sqz - Rust

Source: https://github.com/ojuschugh1/sqz/blob/main/docs/doc/sqz/fn.install_completions.html

Installs shell completions for the detected shell. This function is part of the sqz project.

```rust
pub(crate) fn install_completions(hook: &ShellHook)
```

--------------------------------

### sqz init Command

Source: https://github.com/ojuschugh1/sqz/blob/main/docs/doc/sqz/fn.cmd_init.html

The `sqz init` command is used to set up the SQZ environment. It automatically detects your current shell, installs necessary hooks for integration, and generates a default configuration preset.

```APIDOC
## sqz init

### Description
Detect shell, install hook, create default preset.

### Method
CLI Command

### Endpoint
N/A (CLI Command)

### Parameters
This command does not accept any parameters.

### Request Example
```bash
sqz init
```

### Response
#### Success Response
Upon successful execution, `sqz init` configures the environment and may provide output indicating the steps taken (e.g., shell detected, hook installed).

#### Response Example
```
Shell detected: bash
Installing hook...
Default preset created.
```
```

--------------------------------

### Get Chunk Count

Source: https://github.com/ojuschugh1/sqz/blob/main/docs/doc/src/sqz_engine/url_indexer.rs.html

Helper function to get the number of chunks indexed for a given URL. This is a private helper method.

```rust
fn chunk_count(&self, url: &str) -> Result<usize> {
```

--------------------------------

### Initialize SqzEngine

Source: https://github.com/ojuschugh1/sqz/blob/main/docs/doc/src/sqz_engine/engine.rs.html

Methods for creating a new engine instance, including default path resolution and custom configuration.

```rust
    pub fn new() -> Result<Self> {
        let preset = Preset::default();
        let store_path = Self::default_store_path();
        Self::with_preset_and_store(preset, &store_path)
    }
```

```rust
    fn default_store_path() -> std::path::PathBuf {
        if let Some(home) = dirs_next::home_dir() {
            let sqz_dir = home.join(".sqz");
            if std::fs::create_dir_all(&sqz_dir).is_ok() {
                return sqz_dir.join("sessions.db");
            }
        }
        // Fallback: temp dir with unique name
        let dir = std::env::temp_dir();
        dir.join(format!(
            "sqz_session_{}_{}.db",
            std::process::id(),
            std::time::SystemTime::now()
                .duration_since(std::time::UNIX_EPOCH)
                .map(|d| d.as_nanos())
                .unwrap_or(0)
        ))
    }
```

```rust
    pub fn with_preset_and_store(preset: Preset, store_path: &Path) -> Result<Self> {
        let pipeline = CompressionPipeline::new(&preset);
        let window_size = preset.budget.default_window_size;

        // One connection per consumer. SQLite WAL mode handles concurrency.
        let session_store = SessionStore::open_or_create(store_path)?;
```

--------------------------------

### Test Session Guide Generation

Source: https://github.com/ojuschugh1/sqz/blob/main/docs/doc/src/sqz_engine/session_continuity.rs.html

Tests the generation of session knowledge guides, ensuring correct formatting and content organization.

```rust
    #[test]
    fn test_generate_guide_empty_snapshot() {
        let store = in_memory_store();
        let mgr = SessionContinuityManager::new(&store);
        let snapshot = Snapshot { events: vec![] };

        let guide = mgr.generate_guide(&snapshot);
        assert!(guide.text.contains("<session_knowledge>"));
        assert!(guide.text.contains("</session_knowledge>"));
        assert!(guide.token_count <= MAX_GUIDE_TOKENS);
    }
```

```rust
    #[test]
    fn test_generate_guide_contains_session_knowledge_directive() {
        let store = in_memory_store();
        let mgr = SessionContinuityManager::new(&store);
        let snapshot = Snapshot {
            events: vec![
                SnapshotEvent::new(SnapshotEventType::LastPrompt, "Fix auth bug".into()),
            ],
        };

        let guide = mgr.generate_guide(&snapshot);
        assert!(guide.text.starts_with("<session_knowledge>\n"));
        assert!(guide.text.ends_with("</session_knowledge>\n"));
    }
```

```rust
    #[test]
    fn test_generate_guide_organizes_by_category() {
        let store = in_memory_store();
        let mgr = SessionContinuityManager::new(&store);
        let snapshot = Snapshot {
            events: vec![
                SnapshotEvent::new(SnapshotEventType::LastPrompt, "Fix auth".into()),
                SnapshotEvent::new(SnapshotEventType::Error, "panic at line 42".into()),
                SnapshotEvent::new(SnapshotEventType::Decision, "Use JWT".into()),
                SnapshotEvent::new(SnapshotEventType::PendingTask, "Refactor module".into()),
                SnapshotEvent::new(SnapshotEventType::ActiveFile, "src/auth.rs".into()),
```

--------------------------------

### Initialize sqz CLI

Source: https://context7.com/ojuschugh1/sqz/llms.txt

Run this command to initialize sqz for zero-configuration integration. Restart your AI tool after initialization.

```bash
sqz init
```

--------------------------------

### Handle Shell Completion Installation

Source: https://github.com/ojuschugh1/sqz/blob/main/docs/doc/src/sqz/main.rs.html

Processes the result of a completion installation attempt, silently ignoring errors as completions are considered optional.

```rust
match write_result {
        Ok(()) => println!("[sqz] completions installed to {}", dest.display()),
        Err(_) => {} // silently skip — completions are optional
    }
}
```

--------------------------------

### CompressionPipeline - new

Source: https://github.com/ojuschugh1/sqz/blob/main/docs/doc/sqz_engine/pipeline/struct.CompressionPipeline.html

Constructs a new CompressionPipeline from a preset, initializing all built-in stages and post-processing components.

```APIDOC
## new

### Description
Construct the pipeline from a preset, creating all built-in stages sorted by priority, plus the token pruner, dictionary compressor, and entropy truncator.

### Method
`new`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **Self** (CompressionPipeline) - A new instance of CompressionPipeline.

#### Response Example
None
```

--------------------------------

### Test guide category priority ordering

Source: https://github.com/ojuschugh1/sqz/blob/main/docs/doc/src/sqz_engine/session_continuity.rs.html

Ensures that generated guide text follows the expected priority order for different event types.

```rust
#[test]
fn test_generate_guide_category_order_matches_priority() {
    let store = in_memory_store();
    let mgr = SessionContinuityManager::new(&store);
    let snapshot = Snapshot {
        events: vec![
            // Insert in reverse priority order.
            SnapshotEvent::new(SnapshotEventType::Summary, "sum".into()),
            SnapshotEvent::new(SnapshotEventType::LastPrompt, "prompt".into()),
            SnapshotEvent::new(SnapshotEventType::GitOp, "commit".into()),
            SnapshotEvent::new(SnapshotEventType::Error, "err".into()),
        ],
    };

    let guide = mgr.generate_guide(&snapshot);
    // last_request should appear before errors, errors before git, git before summary.
    let pos_prompt = guide.text.find("last_request:").unwrap();
    let pos_error = guide.text.find("errors:").unwrap();
    let pos_git = guide.text.find("git:").unwrap();
    let pos_summary = guide.text.find("summary:").unwrap();
    assert!(pos_prompt < pos_error);
    assert!(pos_error < pos_git);
    assert!(pos_git < pos_summary);
}
```

--------------------------------

### Dashboard Server Initialization and Metrics Handling

Source: https://github.com/ojuschugh1/sqz/blob/main/docs/doc/src/sqz_engine/dashboard.rs.html

Details on creating and managing the DashboardServer, including how to obtain a metrics handle for external updates.

```APIDOC
## DashboardServer

### Description
A minimal HTTP server that serves the dashboard HTML and an SSE endpoint. It uses a shared `Arc<Mutex<DashboardMetrics>>` to allow external threads to update metrics while the server pushes them to clients.

### Methods
- **new(config: DashboardConfig, metrics: Arc<Mutex<DashboardMetrics>>) -> DashboardServer**
  Creates a new server instance with the provided configuration and a shared metrics handle.

- **metrics_handle(&self) -> Arc<Mutex<DashboardMetrics>>**
  Returns a clone of the shared metrics handle, allowing external callers to update the metrics.

- **run(&self) -> crate::error::Result<()>**
  Starts the server and listens for incoming connections. This method blocks the calling thread.
```

--------------------------------

### Define TeeAction Enum

Source: https://github.com/ojuschugh1/sqz/blob/main/docs/doc/sqz/enum.TeeAction.html

Defines the TeeAction enum with variants for List and Get operations. The Get variant includes an 'id' field of type String.

```rust
pub(crate) enum TeeAction {
    List,
    Get {
        id: String,
    },
}
```

--------------------------------

### Initialize Engine Helper

Source: https://github.com/ojuschugh1/sqz/blob/main/docs/doc/src/sqz/main.rs.html

Initializes the SqzEngine and exits the process if initialization fails.

```rust
fn require_engine() -> SqzEngine {
    SqzEngine::new().unwrap_or_else(|e| {
        eprintln!("[sqz] failed to initialise engine: {e}");
        std::process::exit(1);
    })
}
```

--------------------------------

### Command-line Usage for sqz compress

Source: https://github.com/ojuschugh1/sqz/blob/main/docs/doc/sqz/fn.cmd_compress.html

Illustrates how to use the `sqz compress` command from the command line, specifying optional text input and compression modes.

```bash
sqz compress [text] [--mode safe|default|aggressive|auto] [--verify]
```

--------------------------------

### Start SQZ MCP Server

Source: https://github.com/ojuschugh1/sqz/blob/main/docs/doc/src/sqz_mcp/lib.rs.html

Starts the SQZ MCP server on the given transport. Supports `Stdio` for JSON-RPC over stdin/stdout and `Sse` for a minimal HTTP server.

```APIDOC
## Start SQZ MCP Server

### Description
Starts the SQZ MCP server on the given transport. For `Stdio`, it reads JSON-RPC messages from stdin and writes responses to stdout. For `Sse`, it starts a minimal HTTP server on the specified port.

### Method
`pub fn start(self, transport: McpTransport) -> Result<()>`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```rust
// Example for starting with Stdio transport
let mcp = Mcp::new(...);
mcp.start(McpTransport::Stdio)?;

// Example for starting with Sse transport on port 8080
let mcp = Mcp::new(...);
mcp.start(McpTransport::Sse { port: 8080 })?;
```

### Response
#### Success Response (200)
Returns `Ok(())` on successful start.

#### Response Example
None (as this is a function call, not an HTTP response)
```

--------------------------------

### Install Shell Hook

Source: https://github.com/ojuschugh1/sqz/blob/main/docs/doc/src/sqz/shell_hook.rs.html

Installs the hook into the shell's RC file. Returns Ok(true) if written, Ok(false) if already present. Errors are logged.

```rust
    /// Install the hook into the shell RC file.
    ///
    /// Returns `Ok(true)` when the hook was written, `Ok(false)` when it was
    /// already present.  On failure the error is logged and the function
    /// returns `Err`.
    pub fn install(&self) -> Result<bool, HookError> {
        let rc = self.rc_path();
        install_hook_to_file(&rc, self.hook_script(), self.sentinel())
    }
```

--------------------------------

### Initialize SqzWasm with Preset String

Source: https://github.com/ojuschugh1/sqz/blob/main/docs/doc/src/sqz_wasm/lib.rs.html

Demonstrates initializing SqzWasm with a preset name provided as a string. Accepts "default" and any other string, defaulting to default.

```rust
let result = SqzWasm::new("default");
assert!(result.is_ok());
let result2 = SqzWasm::new("not a preset");
assert!(result2.is_ok());
```

--------------------------------

### sqz CLI Argument Parsing

Source: https://github.com/ojuschugh1/sqz/blob/main/docs/doc/src/sqz/main.rs.html

Sets up the main CLI structure using clap, including the command name, version, and description, with the banner displayed before help messages.

```rust
#[derive(Parser)]
#[command(
    name = "sqz",
    version,
    about = "sqz — universal context intelligence layer",
    before_help = SQZ_BANNER,
)]
struct Cli {
    #[command(subcommand)]
    command: Option<Command>,
}
```

--------------------------------

### Initialize sqz

Source: https://context7.com/ojuschugh1/sqz/llms.txt

Installs shell hooks and configures AI tool integrations. Detects your shell, installs completion scripts, creates default presets, and configures hooks for supported AI tools. Restart your shell or source the RC file after execution.

```bash
# Install sqz and initialize
car go install sqz-cli
sqz init

# Output:
# [sqz] detected shell: Zsh
# [sqz] hook installed to /Users/you/.zshrc
# [sqz] completions installed to /Users/you/.zsh/completions/_sqz
# [sqz] default preset written to /Users/you/.sqz/presets/default.toml
# [sqz] AI tool hooks installed for: Claude Code, Cursor, Windsurf, Cline, Gemini CLI
# [sqz] init complete. Restart your shell or source the RC file.
```

--------------------------------

### SessionStore Initialization

Source: https://github.com/ojuschugh1/sqz/blob/main/docs/doc/src/sqz_engine/session_store.rs.html

Methods for opening and creating a SessionStore instance.

```APIDOC
## SessionStore Initialization

### `open(path: &Path) -> Result<Self>`

Opens an existing database at the specified path. Returns an error if the file does not exist or cannot be opened.

### `open_or_create(path: &Path) -> Result<Self>`

Opens the database at the specified path, creating it if it does not exist. If the database is corrupted, a new one is created at the same path, and a warning is logged. Prior session data will be lost in case of corruption.

### `from_connection(conn: Connection) -> Self`

Constructs a `SessionStore` from an already-open `Connection`. This method is intended for testing purposes, such as using in-memory databases.
```

--------------------------------

### GET /sessions/search

Source: https://github.com/ojuschugh1/sqz/blob/main/docs/doc/src/sqz_engine/engine.rs.html

Search for sessions based on a keyword query.

```APIDOC
## GET /sessions/search

### Description
Search sessions by keyword.

### Method
GET

### Endpoint
/sessions/search

### Parameters
#### Query Parameters
- **query** (string) - Required - The keyword to search for in sessions.
```

--------------------------------

### Initialize In-Memory Database Store

Source: https://github.com/ojuschugh1/sqz/blob/main/docs/doc/src/sqz_engine/session_store.rs.html

Sets up an in-memory SQLite database connection and applies the necessary schema. Returns a `SessionStore` instance.

```rust
fn in_memory_store() -> SessionStore {
        let conn = Connection::open_in_memory().unwrap();
        apply_schema(&conn).unwrap();
        SessionStore { db: conn }
    }
```