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 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.

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.

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 writer creates a named assistant.
• Observability: structured logs, tokens, cost, duration.

---

Quickstart

Install the CLI:

curl -sSL https://raw.githubusercontent.com/snowztech/vikusha/main/install.sh | bash
vikusha version

Go users can also install from source:

go install github.com/snowztech/vikusha/cmd/vikusha@latest

Character YAML

Create character.yaml.

name: Helper
model: gpt-4o-mini
system_prompt: You are a concise assistant.
provider:
  name: openai
  api_key_env: OPENAI_API_KEY

export OPENAI_API_KEY=...
vikusha chat character.yaml

Named agents are loaded from ~/.vikusha/agents/<name>/character.yaml.

vikusha create writer
vikusha chat writer

Named agents get their own workspace/. Built-in file tools read from that workspace and reject paths outside it.

For structured turn logs, pass -log-json. Named agents append logs to ~/.vikusha/agents/<name>/logs/turns.jsonl; path-based agents write logs to stderr.

vikusha chat -log-json writer

For readable turn logs during a terminal session, pass -log-terminal.

vikusha chat -log-terminal writer

You can load the same character from Go.

a, err := vikusha.LoadAgent("character.yaml", vikusha.BuildOptions{})
reply, err := a.Chat(ctx, "lucas", "hello")
_ = reply

// From another goroutine or transport command:
a.Cancel("lucas")

For advanced Go usage where you want to wire provider instances, tool registries, or memory yourself, use agent.New; see examples/file_read.

YAML Fields

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
context:
  history_token_budget: 30000
tools:
  - file_list
  - file_read
  - file_edit
tool_config:
  file_read:
    timeout: 5s
    result_cap: 8000
logging:
  terminal: true
  color: true

If 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: load a character and run one turn.
• examples/file_read: advanced manual construction with registered file tools.

---

Documentation

• 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.

---

License

MIT. Copyright (c) 2026 snowztech.