kukicha

Kukicha

A readable language that ships as a single binary, brewed from what Go leaves on the table. Built for AI integration, cloud automation, and everyday data/CLI scripting.

kukicha.org · Cookbook · Quick Reference · Stdlib Reference

Where to start

What's it for?

• AI integration. Prompt-injection-aware LLM calls and JSON-mode decoding in examples/triage.kuki, plus MCP servers without a framework in examples/mcp_sandbox.kuki.
• Cloud & deploy automation. One static binary that drives cloud APIs from readable scripts: examples/gke-django-deploy.
• Data & CLI scripting. Pipes, concurrent.MapWithLimit, table, regex, json : examples/api-explorer.

A sip of Kukicha

Fetch GitHub issues, classify in parallel with Claude, keep the urgent ones, sort, print a colored table:

# triage.kuki  classify open issues with Claude, flag the urgent ones
import "stdlib/color"
import "stdlib/concurrent"
import "stdlib/fetch"
import "stdlib/llm/chat"
import "stdlib/llm/safe"
import "stdlib/log"
import "stdlib/slice"
import "stdlib/sort"
import "stdlib/table"

type Issue
    number int
    title string
    body string

enum Severity
    Unknown = 0
    Trivial = 1
    Minor = 2
    Normal = 3
    Urgent = 4
    OnFire = 5

type Verdict
    number int
    severity Severity
    kind string # bug | feature | docs | question
    summary string

func sevColor(s: Severity) func(string) string
    switch s
        when Severity.OnFire
            return color.BrightRed
        when Severity.Urgent
            return color.Red
        default
            return color.Yellow

func classify(issue: Issue) Verdict
    # title and body are attacker-controlled, wrap them so a crafted issue
    # can't override the system prompt
    title := safe.Wrap("title", safe.SanitizeLine(issue.title, 200))
    body := safe.Wrap("body", safe.Truncate(issue.body, 4000))

    prompt := """
        {title}

        {body}
        """

    verdict := chat.New("anthropic:claude-sonnet-4-6")
        |> chat.System("""
            {safe.UntrustedPreamble}
            Classify GitHub issues. Reply JSON: \{severity:1-5, kind, summary\}
            """)
        |> chat.AskJSON of Verdict from prompt onerr
            log.Warn("classify failed", "issue", issue.number, "err", error)
            return {number: issue.number}

    verdict.number = issue.number
    return verdict

func main()
    url := "https://api.github.com/repos/golang/go/issues?per_page=20"
    issues := fetch.GetJSON of list of Issue from url onerr
        log.Error("github fetch failed", "url", url, "err", error)
        return

    triaged := issues
        |> concurrent.MapWithLimit(4, classify)
        |> slice.Reject(v => v.kind equals "question")

    urgent := triaged
        |> slice.Filter(v => v.severity >= Severity.Urgent)
        |> sort.By((a, b) => a.severity > b.severity)

    log.Info("triaged", "count", len(triaged), "urgent", len(urgent))

    if len(urgent) equals 0
        print(color.Dim("Nothing urgent — go enjoy your tea."))
        return

    print(color.Bold("Needs attention:"))
    t := table.New({"sev", "kind", "#", "summary"})
    for v in urgent
        label := sevColor(v.severity)("P{v.severity}")
        t = t |> table.AddRow({label, color.Dim(v.kind), "#{v.number}", v.summary})
    t |> table.PrintWithStyle(table.Style.Box)

Read it top-to-bottom: wrap the untrusted issue text, classify four at a time, drop the questions, keep the urgent ones, sort, print a colored table. English operators (and, equals, isnt, if … then … else), pipes that flow left-to-right, named severities via enum, and a friendly stdlib (fetch.GetJSON, concurrent.MapWithLimit, safe.Wrap, table.PrintWithStyle). onerr keeps error handling manageable.

For a smaller, no-network sample see examples/scan.kuki: tally log levels in parallel.

Why Kukicha?

• Readable. English operators (and, equals, isnt), pipes, indentation-based blocks
• Ships as one file. kukicha build produces a static binary, copy it to a server and run.
• Batteries included. fetch, shell, files, db, llm, mcp, concurrent, crypto, html and 30+ more.
• Safe defaults. Compile-time lints that flag SQL injection, XSS, shell injection, path traversal, SSRF, and open redirects, paired with stdlib (safe.Wrap, fetch.NewExternal, http.SafeHTML) Errors are values handled with onerr.
• No lock-in. kukicha brew file.kuki converts a file back to Go.

What Kukicha isn't

• Not a replacement for gc. We transpile to Go and let the Go toolchain handle codegen, linking, and the runtime. No custom backend.
• Not a replacement for go test, go vet, or go build. kukicha build shells out to them; your existing Go tooling still applies.
• Not a sandbox or new runtime. A Kukicha binary is a Go binary. Same goroutines, same GC, same GOOS/GOARCH.
• Not trying to hide Go. If you know Go, Kukicha is thin sugar — kukicha brew shows the Go underneath any time you want to look.
• Not a new package ecosystem. Imports resolve through go.mod; any Go module works unchanged.

Quickstart

Grab a pre-built binary from GitHub Releases (Linux, macOS, Windows). Or, if you already have Go 1.26+ installed:

go install github.com/kukichalang/kukicha/cmd/kukicha@v0.48.4
mkdir myapp && cd myapp
kukicha init

kukicha init initializes a Go module (if go.mod is absent), extracts the stdlib, downloads dependencies, and writes an AGENTS.md language reference. Add .kukicha/ to your .gitignore. Re-run kukicha init after upgrading the compiler to refresh the stdlib, bump the go.mod stdlib pin, and update the embedded AGENTS.md reference.

Create hello.kuki:

function main()
    name := "World"
    print("Hello, {name}!")

kukicha run hello.kuki

Commands

Already use Go?

Kukicha is a near-superset of Go. Most Go compiles as-is: operators, pointers, if err != nil, anonymous funcs, slices, generics, interfaces. A few Go constructs (range, case/default, struct {} type literals, chan T, goto, parenthesized const ( ... )) have Kukicha replacements and won't parse in their Go form; see docs/kukicha-quick-reference.md for the full list. Kukicha reverts to standard Go before compilation, so mix and match freely. Run kukicha-blend on existing Go to see idiomatic Kukicha suggestions, and kukicha brew to convert any .kuki file back to Go.

Editor support

• VS Code: https://github.com/kukichalang/vscode-kukicha
• Zed: https://github.com/kukichalang/zed-kukicha
• Other: make install-lsp and point your editor at kukicha-lsp

More

Cookbook · Quick Reference · Stdlib · FAQ · Contributing

Version: 0.48.4 | License: MIT

[!NOTE] Portions of this codebase were written with AI assistance. Commits are reviewed by human maintainers before merge.