Z-Code

A beautiful terminal-based AI coding assistant with multi-provider support.

Not affiliated with Z.AI's ZCode. This is an old personal experiment, last touched in
January 2026, that happens to share a similar name. If you are looking for the ZCode terminal
agent, that is a different project: https://zcode.z.ai. Bug reports about that project do not
belong here.

Features

• Interactive TUI - Beautiful terminal interface built with Bubble Tea
• Multi-Provider Support - Use OpenAI API, OpenRouter, or LiteLLM (100+ models)
• Native Tool Calling - Reliable structured tool calls via OpenAI-compatible API
• Self-Healing Loop - Automatic retry when tool calls fail
• Streaming Responses - See AI responses as they're generated
• Built-in Tools - File operations, directory listing, and shell commands
• Custom Agents - Define specialized AI agents with markdown files
• Workflows - Chain agents together with YAML workflow definitions
• Handoff Mode - Agents can transfer control to other agents with context
• Slash Commands - Quick actions with /help, /config, /clear, and more
• Configuration Management - Store API keys and defaults securely

Screenshot

┌──────────────────────────────────────────────────────────────┐
│  Z-Code TUI  v0.1.0                              ~/projects  │
├──────────────────────────────────────────────────────────────┤
│                                                              │
│    ███████╗       ██████╗ ██████╗ ██████╗ ███████╗          │
│    ╚══███╔╝      ██╔════╝██╔═══██╗██╔══██╗██╔════╝          │
│      ███╔╝ █████╗██║     ██║   ██║██║  ██║█████╗            │
│     ███╔╝  ╚════╝██║     ██║   ██║██║  ██║██╔══╝            │
│    ███████╗      ╚██████╗╚██████╔╝██████╔╝███████╗          │
│    ╚══════╝       ╚═════╝ ╚═════╝ ╚═════╝ ╚══════╝          │
│                                                              │
│  YOU                                                         │
│  What files are in this directory?                           │
│                                                              │
│  CLAUDE                                                      │
│  Let me check that for you...                                │
│                                                              │
├──────────────────────────────────────────────────────────────┤
│ ╭────────────────────────────────────────────────────────╮   │
│ │ Describe your task...                                  │   │
│ ╰────────────────────────────────────────────────────────╯   │
│ Enter to send · Ctrl+C to quit                      claude   │
└──────────────────────────────────────────────────────────────┘

Installation

Prerequisites

• Go 1.24 or later
• One of the following AI backends:
  • OpenAI API key
  • OpenRouter API key
  • LiteLLM proxy (unified interface to 100+ models)

Build from Source

# Clone the repository
git clone https://github.com/simonyos/Z-CODE.git
cd z-code

# Build
go build -o zcode .

# Run
./zcode

Install Go Binary

go install github.com/simonyos/Z-CODE@latest

Usage

Basic Usage

# Start with default provider (LiteLLM)
zcode

# Use a specific provider
zcode -p openai
zcode -p openrouter
zcode -p litellm

# Specify a model
zcode -p openai -m gpt-4-turbo
zcode -p litellm -m anthropic/claude-3.5-sonnet
zcode -p openrouter -m google/gemini-flash-1.5

Providers

Using Claude and Gemini Models

With v2.0, Claude and Gemini models are accessed through API providers:

# Claude via LiteLLM
zcode -p litellm -m anthropic/claude-3.5-sonnet

# Claude via OpenRouter
zcode -p openrouter -m anthropic/claude-3.5-sonnet

# Gemini via LiteLLM
zcode -p litellm -m google/gemini-flash-1.5

# Gemini via OpenRouter
zcode -p openrouter -m google/gemini-1.5-flash

Configuration

Z-Code stores configuration in ~/.config/zcode/config.json.

# View current configuration
zcode config

# Set OpenAI API key
zcode config set openai sk-your-api-key

# Set default provider
zcode config set provider gemini

# Set default model
zcode config set model gpt-4o

# Remove a configuration
zcode config delete openai

# Show config file path
zcode config path

Slash Commands

Type these commands in the chat:

Custom Agents

Create specialized AI agents by adding markdown files with YAML frontmatter.

Creating an Agent

Create a file in .zcode/agents/ (project-local) or ~/.config/zcode/agents/ (global):

---
name: code-reviewer
description: Reviews code for best practices
tools:
  - read_file
  - grep
  - glob
max_iterations: 5
handoff_to: code-fixer
---

You are an expert code reviewer. Your task is to analyze code for:
1. Code Quality
2. Best Practices
3. Potential Bugs
...

Using Custom Agents

# Invoke by name
/code-reviewer "Review the auth module"

# List available agents
/agents

Agent Configuration

Skills

Skills are lightweight reusable prompt templates - simpler than agents.

Creating a Skill

Create a file in .zcode/skills/ (project-local) or ~/.config/zcode/skills/ (global):

---
name: explain-code
description: Explains code in simple terms
tags:
  - learning
  - documentation
variables:
  - language
---

You are a helpful programming instructor. Explain the following code in simple terms.

Language preference: {language}

Code to explain:
{user_input}

Using Skills

# Invoke a skill
/skill:explain-code "func main() { fmt.Println(\"Hello\") }"

# With variables
/skill:write-tests framework=jest "function add(a, b) { return a + b }"

# List available skills
/skills

Skill Configuration

Built-in Example Skills

• explain-code - Explains code in simple terms
• write-tests - Generates unit tests
• refactor - Suggests refactoring improvements
• debug - Helps debug code issues
• document - Generates documentation

Workflows

Chain multiple agents together with YAML workflow definitions.

Creating a Workflow

Create a file in .zcode/workflows/ (project-local) or ~/.config/zcode/workflows/ (global):

name: review-and-fix
description: Reviews code and fixes issues

steps:
  - name: review
    agent: code-reviewer
    output: review_results
    prompt: "Review: {user_input}"

  - name: fix
    agent: code-fixer
    input: review_results
    condition: "review_results.success"
    prompt: "Fix issues: {review_results.output}"

  - name: test
    agent: test-runner
    loop_until: "test_results.success == true"
    max_loops: 3

Using Workflows

# Run a workflow
/run:review-and-fix "Fix issues in src/api"

# List available workflows
/workflows

Workflow Step Options

Handoff Mode

Agents can transfer control to other agents using XML handoff tags:

<handoff agent="code-fixer" reason="Found issues to fix">
  <context key="issues">List of issues here</context>
</handoff>

Keyboard Shortcuts

Project Structure

z-code/
├── cmd/
│   ├── root.go           # CLI entry point
│   └── config.go         # Config subcommand
├── internal/
│   ├── agent/            # AI agent orchestration
│   ├── agents/           # Custom agent system
│   │   ├── definition.go # Agent definition types
│   │   ├── loader.go     # Markdown parser
│   │   ├── registry.go   # Agent discovery
│   │   ├── executor.go   # Agent execution
│   │   └── handoff.go    # Handoff parsing
│   ├── skills/           # Skills system
│   │   ├── definition.go # Skill definition types
│   │   ├── loader.go     # Markdown parser
│   │   ├── registry.go   # Skill discovery
│   │   └── executor.go   # Skill execution
│   ├── workflows/        # Workflow engine
│   │   ├── definition.go # Workflow/step types
│   │   ├── loader.go     # YAML parser
│   │   ├── engine.go     # Workflow execution
│   │   ├── context.go    # Shared state
│   │   └── handoff.go    # Handoff management
│   ├── config/           # Configuration management
│   ├── llm/              # LLM providers
│   │   ├── provider.go   # Provider interface
│   │   ├── types.go      # OpenAI-compatible types
│   │   ├── openai.go     # OpenAI API implementation
│   │   ├── openrouter.go # OpenRouter implementation
│   │   └── litellm.go    # LiteLLM implementation (with native tool calling)
│   ├── tools/            # Built-in tools
│   │   ├── read_file.go
│   │   ├── write_file.go
│   │   ├── edit.go
│   │   ├── list_dir.go
│   │   ├── glob.go
│   │   ├── grep.go
│   │   └── bash.go
│   └── tui/              # Terminal UI
│       ├── app.go        # Main Bubble Tea model
│       ├── components/   # UI components
│       ├── layout/       # Layout management
│       └── theme/        # Color themes
├── .zcode/               # Project-local agents/skills/workflows
│   ├── agents/
│   ├── skills/
│   └── workflows/
├── main.go
├── go.mod
└── README.md

Adding a New Provider

1. Create a new file in internal/llm/ implementing the Provider interface:

type Provider interface {
    Generate(ctx context.Context, messages []Message) (string, error)
    GenerateStream(ctx context.Context, messages []Message) (<-chan StreamChunk, error)
}

1. For native tool calling support, also implement ToolProvider:

type ToolProvider interface {
    Provider
    GenerateWithTools(ctx context.Context, messages []Message, tools []OpenAITool) (*ToolCallResponse, error)
    GenerateStreamWithTools(ctx context.Context, messages []Message, tools []OpenAITool) (<-chan ToolStreamChunk, error)
}

1. Add the provider to the switch statement in cmd/root.go
2. Update the help text and documentation

Built With

• Bubble Tea - TUI framework
• Lip Gloss - Style definitions
• Bubbles - TUI components
• Glamour - Markdown rendering
• Cobra - CLI framework

Contributing

Contributions are welcome! Here's how you can help:

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Commit your changes: git commit -m 'Add amazing feature'
4. Push to the branch: git push origin feature/amazing-feature
5. Open a Pull Request

Development Setup

# Clone your fork
git clone https://github.com/YOUR_USERNAME/z-code.git
cd z-code

# Install dependencies
go mod download

# Run in development
go run .

# Run tests
go test ./...

Ideas for Contributions

• Add more LLM providers (Ollama, etc.)
• Session persistence (save/resume conversations)
• Custom themes
• Plugin system for tools
• Vim keybindings
• Multi-file context
• Code syntax highlighting in responses
• Dual-brain mode (fast/smart model switching)

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Inspired by Claude Code and Aider
• Built with the amazing Charm ecosystem

Made with :heart: by Simon Yos