v0.0.3
zoobzio January 18, 2026 Edit this page

Quickstart

Installation

Install the core package:

go get github.com/zoobz-io/chisel

Install providers for the languages you need:

# Zero-dependency providers
go get github.com/zoobz-io/chisel/golang
go get github.com/zoobz-io/chisel/markdown

# Tree-sitter providers
go get github.com/zoobz-io/chisel/typescript
go get github.com/zoobz-io/chisel/python
go get github.com/zoobz-io/chisel/rust

Requires Go 1.24+.

Basic Usage

package main

import (
    "context"
    "fmt"

    "github.com/zoobz-io/chisel"
    "github.com/zoobz-io/chisel/golang"
)

func main() {
    // Create a provider
    provider := golang.New()

    source := []byte(`package math

// Add returns the sum of two integers.
func Add(a, b int) int {
    return a + b
}

// Calculator performs arithmetic operations.
type Calculator struct {
    value int
}

// Add adds n to the calculator's value.
func (c *Calculator) Add(n int) {
    c.value += n
}
`)

    // Chunk the source
    chunks, err := provider.Chunk(context.Background(), "math.go", source)
    if err != nil {
        panic(err)
    }

    // Inspect the results
    for _, chunk := range chunks {
        fmt.Printf("[%s] %s (lines %d-%d)\n",
            chunk.Kind, chunk.Symbol, chunk.StartLine, chunk.EndLine)
    }
}

Output:

[function] Add (lines 3-6)
[class] Calculator (lines 8-11)
[method] Calculator.Add (lines 13-16)

Multiple Languages

Use the Chunker to route files to the appropriate provider:

import (
    "github.com/zoobz-io/chisel"
    "github.com/zoobz-io/chisel/golang"
    "github.com/zoobz-io/chisel/typescript"
    "github.com/zoobz-io/chisel/python"
)

// Create a chunker with multiple providers
c := chisel.New(
    golang.New(),
    typescript.New(),
    typescript.NewJavaScript(),
    python.New(),
)

// Chunk by language
goChunks, _ := c.Chunk(ctx, chisel.Go, "main.go", goSource)
tsChunks, _ := c.Chunk(ctx, chisel.TypeScript, "app.ts", tsSource)
pyChunks, _ := c.Chunk(ctx, chisel.Python, "utils.py", pySource)

See Providers Guide for language-specific details.

Context Chains

Methods and nested definitions include their parent context:

source := []byte(`class UserService {
    async getUser(id: string): Promise<User> {
        return this.db.find(id);
    }
}`)

chunks, _ := typescript.New().Chunk(ctx, "service.ts", source)

for _, c := range chunks {
    if c.Kind == chisel.KindMethod {
        fmt.Printf("%s in %v\n", c.Symbol, c.Context)
        // getUser in [class UserService]
    }
}

See Concepts for more on context preservation.

Embedding Pipeline

A typical pipeline: chunk → embed → store → search.

// 1. Chunk the code
chunks, _ := provider.Chunk(ctx, filename, source)

// 2. Embed each chunk (using your embedder of choice)
for _, chunk := range chunks {
    embedding := embedder.Embed(chunk.Content)

    // 3. Store with metadata
    store.Insert(Document{
        Content:   chunk.Content,
        Embedding: embedding,
        Metadata: map[string]any{
            "symbol":    chunk.Symbol,
            "kind":      chunk.Kind,
            "file":      filename,
            "startLine": chunk.StartLine,
            "endLine":   chunk.EndLine,
            "context":   chunk.Context,
        },
    })
}

// 4. Search by meaning
results := store.Search(embedder.Embed("authentication logic"))

Next Steps

© 2026 Alexander Thorwaldson