Zana.jl

Zana is a REPL-based AI coding copilot for Julia. It connects to LLMs (OpenAI, Anthropic Claude, Ollama, or any OpenAI-compatible API) and gives them tools to read, write, edit, and search your codebase — all from an interactive terminal session.

Zana — Kurdish for "wise/scholar", embodies the pursuit of intelligent assistance through language models. Like a knowledgeable companion at your side, Zana brings the reasoning power of modern AI directly into your Julia development workflow.

This site documents the development version. After your first tagged release, see stable docs for the latest release.

About TAFS

TAFS (Time Series Analysis and Forecasting Society) is a non-profit association ("Verein") in Vienna, Austria. It connects academics, experts, practitioners, and students focused on time-series, forecasting, and decision science. Contributions remain fully open source. Learn more at taf-society.org.

Installation

Zana is under active development. For the latest dev version:

using Pkg
Pkg.add(url="https://github.com/taf-society/Zana.jl")

For local development:

] dev /path/to/Zana.jl

REPL Interface (Primary Usage)

Zana provides an interactive REPL that gives an LLM full access to your codebase through 7 built-in tools. This is the recommended approach for most users.

Quick Example: Ollama

using Zana

zana(ollama=true, model="qwen3")

Quick Example: Anthropic Claude

using Zana

# Reads ANTHROPIC_API_KEY from environment
zana(claude=true)

Quick Example: OpenAI

using Zana

# Reads OPENAI_API_KEY from environment
zana()

# Or pass the key directly
zana(api_key="sk-...")

Quick Example: Any OpenAI-Compatible API

using Zana

zana(api_key="your-key", base_url="https://api.example.com/v1", model="your-model")

Once inside the REPL, the LLM can autonomously read files, search code, run commands, and make edits to help you with any coding task.

Available Commands

Type /help inside the Zana REPL to see all available commands. Use /exit to quit.

Programmatic Usage (Agent API)

For integration into scripts or custom workflows, use ZanaAgent and process_turn directly:

using Zana

config = ZanaConfig(
    ollama = OllamaConfig(model="qwen3")
)

agent = ZanaAgent(config, pwd())
result = process_turn(agent, "List all Julia files in this project")

# Access the response
println(result.response)

# Inspect tool executions
for exec in result.tool_executions
    println("  $(exec.tool_name) ($(exec.duration_ms)ms)")
end

Available Tools

Zana equips the LLM with 7 coding tools:

Tool	Description	Use Case
`read_file`	Read file contents with line numbers	Inspecting code, understanding structure
`write_file`	Create or overwrite files	Generating new modules, configs, scripts
`edit_file`	Exact string replacement	Targeted code modifications
`run_bash`	Execute shell commands with timeout	Running tests, git operations, builds
`glob_files`	Find files by glob pattern	Discovering project structure
`grep_code`	Regex search across files	Finding usages, patterns, definitions
`list_directory`	List directory contents with sizes	Exploring directory layout

For detailed documentation on each tool, see the Tools Guide.

Key Features

Multiple LLM Backends — OpenAI, Anthropic Claude, Ollama, or any OpenAI-compatible API
7 Built-in Tools — Read, write, edit, search, and run commands
Interactive REPL — Conversational coding with full context
Programmatic API — Use ZanaAgent directly in scripts
Minimal Dependencies — Only HTTP, JSON3, UUIDs
Multi-line Input — Backslash continuation for complex prompts
Token Tracking — Monitor LLM usage across the session

License

MIT License.

What's next

Quick Start — Get started quickly with Ollama or OpenAI
User Guide pages:
- REPL Interface — Commands, multi-line input, and session management
- Tools — Detailed documentation for all 7 coding tools
- Configuration — ZanaConfig, LLMConfig, OllamaConfig, ClaudeConfig
- Ollama Integration — Local model setup, utilities, and tips
- Claude Integration — Anthropic Claude setup and usage
API Reference — Complete API documentation