Vikusha

Go framework for AI assistants. Run where you need them.

An assistant has personality, tools, memory, and a transport. You define one in YAML, run it, and use it on Discord or Slack. Same binary, different YAMLs: a coding assistant, a support bot, a Discord bot. Vikusha ships with a default assistant ready to use.

What is Vikusha?

Vikusha is the harness your assistants run on. It handles the agent loop, context engineering, prompt caching, memory, tool execution, and transport wiring. You write the character YAML, the harness does the rest.

• Providers: Anthropic, OpenAI-compatible, Ollama.
• Tools: bash, file, web search, grep, glob.
• Memory: file, SQLite, pgvector.
• Transports: terminal, Discord, Slack, Telegram.
• Isolation: separate workspace and secrets per assistant.
• Scaffolder: vikusha create name spawns a new assistant.
• Observability: structured logs, tokens, cost, duration.

---

Quickstart

go install github.com/snowztech/vikusha/cmd/vikusha@latest
vikusha chat character.yaml

Or embed the harness in your own Go binary:

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/snowztech/vikusha"
)

func main() {
	a, err := vikusha.LoadAgent("character.yaml", vikusha.Options{})
	if err != nil {
		log.Fatal(err)
	}

	reply, err := a.Chat(context.Background(), "lucas", "hello")
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(reply)
}

---

Documentation

• ARCHITECTURE.md: core concepts, interfaces, directory layout.
• CHARACTER.md: full YAML spec with examples.
• ROADMAP.md: where we're headed.

---

License

MIT. Copyright (c) 2026 snowztech.