An assistant has personality, tools, memory, and a transport. You define one in YAML, run it from the terminal today, and later attach transports like Discord or Slack. Same binary, different YAMLs: a coding assistant, a support bot, an ops assistant.
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.
The long-term direction is always-on assistants: define an assistant once, then run it wherever people need it.
- 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 writercreates a named assistant. - Observability: structured logs, tokens, cost, duration.
Install the CLI:
curl -sSL https://raw.githubusercontent.com/snowztech/vikusha/main/install.sh | bash
vikusha versionGo users can also install from source:
go install github.com/snowztech/vikusha/cmd/vikusha@latestCreate character.yaml.
name: Helper
model: gpt-4o-mini
system_prompt: You are a concise assistant.
provider:
name: openai
api_key_env: OPENAI_API_KEYexport OPENAI_API_KEY=...
vikusha chat character.yamlYou can load the same YAML from Go.
a, err := vikusha.LoadAgent("character.yaml", vikusha.Options{})
reply, err := a.Chat(ctx, "lucas", "hello")Use agent.New when you want to pass the provider and tools yourself.
reg := tool.NewRegistry()
reg.Register(file.NewRead())
a, err := agent.New(agent.Options{
Name: "Helper",
Model: "gpt-4o-mini",
SystemPrompt: "You are helpful.",
Provider: llm.NewOpenAI(os.Getenv("OPENAI_API_KEY")),
Tools: reg,
})Both paths return an *agent.Agent; call Chat(ctx, userID, msg) to run a turn.
The fields implemented today are:
name: Helper
model: gpt-4o-mini
system_prompt: You are helpful.
provider:
name: openai # openai, openrouter, anthropic
api_key_env: OPENAI_API_KEY
# base_url: http://localhost:1234/v1
memory:
backend: file
path: .vikusha/helper/memory
tools:
- file_readIf provider is omitted, Vikusha infers Anthropic for models beginning with claude; otherwise it uses OpenAI-compatible chat completions. The default env vars are ANTHROPIC_API_KEY, OPENAI_API_KEY, OPENROUTER_API_KEY, and GROQ_API_KEY, depending on the provider.
See:
- examples/from_yaml: create an agent from YAML.
- examples/hello: create the smallest agent with
agent.New. - examples/file_read: create an agent with a registered tool.
- NORTHSTAR.md: product direction and target experience.
- ARCHITECTURE.md: core concepts, interfaces, directory layout.
- CHARACTER.md: full YAML spec with examples.
- RELEASING.md: release and install process.
- ROADMAP.md: where we're headed.
MIT. Copyright (c) 2026 snowztech.