kader 2.10.0

kader coding agent

Kader

Kader is an intelligent coding agent designed to assist with software development tasks. It provides a comprehensive framework for building AI-powered agents with advanced reasoning capabilities and tool integration.

Features

• 🤖 AI-powered Code Assistance - Support for multiple LLM providers:
  • Ollama: Local LLM execution for privacy and speed.
  • Ollama Cloud: Cloud-based models via ollama.com.
  • Google Gemini: Cloud-based powerful models via the Google GenAI SDK.
  • Anthropic: High-quality Claude models via the Anthropic SDK.
• 🖥️ Interactive CLI - Modern terminal interface built with Rich & prompt_toolkit:
  • Beautiful Output: Markdown rendering, styled panels, and dynamic tables.
  • Interactive Tools: Built-in interactive prompts for model selection and tool confirmation.
• 🛠️ Tool Integration - File system, command execution, web search, and more.
• 🧠 Memory Management - State persistence, conversation history, and isolated sub-agent memory.
• 🔁 Session Management - Save and load conversation sessions.
• ⌨️ Keyboard Shortcuts - Efficient navigation and operations.
• 📝 YAML Configuration - Agent configuration via YAML files.
• 🔄 Planner-Executor Framework - Sophisticated reasoning and acting architecture using task planning and delegation.
• 🗂️ File System Tools - Read, write, search, and edit files with automatic .gitignore filtering.
• 🤝 Agent-As-Tool - Spawn sub-agents for specific tasks with isolated memory and automated context aggregation.
• 🎯 Agent Skills - Modular skill system for specialized domain knowledge and task-specific instructions.
• ⚡ Special Commands - Create custom command agents from CONTENT.md files in ~/.kader/commands

Installation

Prerequisites

• Python 3.11 or higher
• Ollama (optional, for local LLMs)
• uv package manager (recommended) or pip

Using uv (recommended)

# Clone the repository
git clone https://github.com/your-repo/kader.git
cd kader

# Install dependencies with uv
uv sync

# Run the CLI
uv run python -m cli

Using uv tool

With uv tool, you can install Kader globally and run it directly with the kader command:

# Install Kader globally using uv tool
uv tool install kader

# Run the CLI
kader

Using pip

# Clone the repository
git clone https://github.com/your-repo/kader.git
cd kader

# Install in development mode
pip install -e .

# Run the CLI
python -m cli

Quick Start

Running the CLI

# Run the Kader CLI using uv
uv run python -m cli

# Or using pip
python -m cli

First Steps in CLI

Once the CLI is running:

1. Type any question to start chatting with the agent.
2. Use /help to see available commands.
3. Use /models to check and interactively switch available models.
4. Run terminal commands directly by prefixing with ! (e.g. !ls -la).

Configuration

When the kader module is imported for the first time, it automatically creates a .kader directory in your home directory and a .env file.

Environment Variables

The application automatically loads environment variables from ~/.kader/.env:

• OLLAMA_API_KEY: API key for Ollama Cloud (for cloud models at ollama.com). Get your key from https://ollama.com/settings
• GOOGLE_API_KEY: API key for Google Gemini (required for Google Provider).
• ANTHROPIC_API_KEY: API key for Anthropic Claude (required for Anthropic Provider).
• Additional variables can be added to the .env file and will be automatically loaded.

Memory and Sessions

Kader stores data in ~/.kader/:

• Sessions: ~/.kader/memory/sessions/
• Configuration: ~/.kader/
• Memory files: ~/.kader/memory/
• Checkpoints: ~/.kader/memory/sessions/<session-id>/executors/ (Aggregated context from sub-agents)

Settings

User preferences are stored in ~/.kader/settings.json, created automatically on first run:

{
  "main-agent-provider": "ollama",
  "sub-agent-provider": "ollama",
  "main-agent-model": "glm-5:cloud",
  "sub-agent-model": "glm-5:cloud",
  "auto-update": false
}

Field	Description	Default
main-agent-provider	LLM provider for the planner agent	ollama
sub-agent-provider	LLM provider for executor sub-agents	ollama
main-agent-model	Model name for the planner agent	glm-5:cloud
sub-agent-model	Model name for executor sub-agents	glm-5:cloud
auto-update	Automatically update Kader on startup	false

Auto-Update

When auto-update is set to true, Kader will automatically check for and install updates on every startup using uv tool upgrade kader. The update is performed silently.

You can also manually check for updates using the /update command. If a newer version is available, it will upgrade Kader and restart the CLI. If you're already on the latest version, it will display a confirmation message.

CLI Commands

Command	Description
/help	Show command reference
/models	Show available models (Ollama local & cloud, Google & Anthropic)
/clear	Clear conversation
/save	Save current session
/load <id>	Load a saved session
/sessions	List saved sessions
/skills	List loaded skills
/commands	List special commands
/cost	Show usage costs
/init	Initialize .kader directory with KADER.md
/update	Check for updates and update Kader if newer version available
/exit	Exit the CLI
!cmd	Run terminal command

Keyboard Shortcuts

Shortcut	Action
Ctrl+C	Cancel current operation
Ctrl+D	Exit the CLI

Project Structure

kader/
├── cli/                    # Interactive command-line interface
│   ├── app.py             # Main application entry point (Rich + prompt_toolkit)
│   ├── utils.py           # Constants and helpers
│   ├── llm_factory.py     # Provider selection logic
│   ├── __init__.py        # Package exports
│   └── commands/          # CLI command handlers
│       ├── base.py        # Base command class
│       └── initialize.py  # /init command
│   └── README.md          # CLI documentation
├── examples/              # Example implementations
│   ├── memory_example.py  # Memory management examples
│   ├── google_example.py  # Google Gemini provider examples
│   ├── anthropic_example.py # Anthropic Claude provider examples
│   ├── planner_executor_example.py # Advanced workflow examples
│   ├── skills/           # Agent skills examples
│   │   ├── hello/        # Greeting skill with instructions
│   │   ├── calculator/   # Math calculation skill
│   │   └── react_agent.py # Skills demo with ReAct agent
│   └── README.md         # Examples documentation
├── kader/                # Core framework
│   ├── agent/            # Agent implementations (Planning, ReAct)
│   ├── memory/           # Memory management & persistence
│   ├── providers/        # LLM providers (Ollama, Google, Anthropic)
│   ├── tools/            # Tools (File System, Web, Command, AgentTool)
│   ├── prompts/          # Prompt templates (Jinja2)
│   └── utils/            # Utilities (Checkpointer, ContextAggregator)
├── pyproject.toml        # Project dependencies
├── README.md             # This file
└── uv.lock               # Dependency lock file

Core Components

Agents

Kader provides a robust agent architecture:

• ReActAgent: Reasoning and Acting agent that combines thoughts with actions.
• PlanningAgent: High-level agent that breaks complex tasks into manageable plans.
• BaseAgent: Abstract base class for creating custom agent behaviors.

LLM Providers

Kader supports multiple backends:

• OllamaProvider: Connects to locally running Ollama instances.
• OllamaProvider (Cloud): Connects to cloud models at ollama.com (requires OLLAMA_API_KEY).
• GoogleProvider: High-performance access to Gemini models.
• AnthropicProvider: Full support for Claude models.

Agent-As-Tool (AgentTool)

The AgentTool allows a PlanningAgent (Architect) to delegate work to a ReActAgent (Worker). It features:

• Persistent Memory: Sub-agent conversations are saved to JSON.
• Context Aggregation: Sub-agent research and actions are automatically merged into the main session's checkpoint.md via ContextAggregator.

Agent Skills

Kader supports a modular skill system for domain-specific knowledge and specialized instructions:

• Skill Structure: Skills are defined as directories containing SKILL.md files with YAML frontmatter
• Skill Loading: Skills are loaded from ~/.kader/skills (high priority) and ./.kader/ directories
• Skill Injection: Available skills are automatically injected into the system prompt
• Skills Tool: Agents can load skills dynamically using the skills_tool

Special Commands

Kader supports special commands — custom command agents that can be invoked from the CLI:

• Command Structure: Commands can be defined as either:
  • Directory: <command-name>/CONTENT.md (can include additional files like templates, assets)
  • Direct file: <command-name>.md (simple command without extra files)
  • Sub-commands: <command-name>/<subcommand>.md (multiple commands in one directory)
• Command Loading: Commands are loaded from ./.kader/commands/ (higher priority) and ~/.kader/commands/
• Command Invocation: Use /<command-name> <task> or /<command-name>/<subcommand> <task> to execute a command
• Memory Persistence: Command executions are saved to ~/.kader/memory/sessions/<session-id>/executors/<command-name>-<uuid>/conversation.json

Creating a Special Command

Option 1: Directory format (with additional files)

~/.kader/commands/mycommand/
├── CONTENT.md          # Required - command instructions
├── templates/          # Optional - templates, scripts
└── assets/            # Optional - files

Option 2: Simple file format

~/.kader/commands/mycommand.md

Option 3: Directory with sub-commands

~/.kader/commands/mycommand/
├── CONTENT.md           # Main command (/mycommand)
├── subcommand1.md       # Sub-command (/mycommand/subcommand1)
├── subcommand2.md       # Sub-command (/mycommand/subcommand2)
├── templates/           # Optional - shared templates
└── assets/             # Optional - shared assets

CONTENT.md or .md file format:

---
description: What this command does
---

# Command Instructions

Your command agent instructions here...

## Guidelines
- Guideline 1
- Guideline 2

Example: Lint and Test Command

~/.kader/commands/lint-test/
└── CONTENT.md

---
description: Lint and test the codebase
---

You are a Lint and Test Agent. Run linting and tests when requested.

## Instructions

1. Run: uv run ruff check .
2. Run: uv run ruff format --check .
3. Run: uv run pytest -v
4. Report results

Usage:

/lint-test
/lint-test run full check

Use /commands to list all available special commands.

File System Tools with Gitignore Filtering

The file system tools (read_directory, grep, glob) automatically filter out files and directories that match patterns defined in .gitignore files.

You can disable this filtering by passing apply_gitignore_filter=False when creating tools:

from pathlib import Path
from kader.tools.filesys import get_filesystem_tools

# With filtering (default)
tools = get_filesystem_tools(base_path=Path.cwd())

# Without filtering
tools = get_filesystem_tools(base_path=Path.cwd(), apply_gitignore_filter=False)

Example skill structure:

~/.kader/skills/hello/
├── SKILL.md
└── scripts/
    └── hello.py

Example skill (SKILL.md):

---
name: hello
description: Skill for ALL greeting requests
---

# Hello Skill

This skill provides the greeting format you must follow.

## How to greet

Always greet the user with:
- A warm welcome
- Their name if mentioned
- A friendly emoji

Memory Management

• SlidingWindowConversationManager: Maintains context within token limits.
• PersistentSlidingWindowConversationManager: Auto-saves sub-agent history.
• Checkpointer: Generates markdown summaries of agent actions.

Development

Setting up for Development

# Clone the repository
git clone https://github.com/your-repo/kader.git
cd kader

# Install in development mode with uv
uv sync

# Run the CLI
uv run python -m cli

Running Tests

# Run tests with uv
uv run pytest

# Run tests with specific options
uv run pytest --verbose

Code Quality

Kader uses various tools for maintaining code quality:

# Run linter
uv run ruff check .

# Format code
uv run ruff format .

Troubleshooting

Common Issues

• No models found: Ensure your providers are correctly configured. For Ollama, run ollama serve. For Google, ensure GOOGLE_API_KEY is set. For Anthropic, ensure ANTHROPIC_API_KEY is set.
• Connection errors: Verify internet access for cloud providers and local service availability for Ollama.

Contributing

We welcome contributions! Please see CONTRIBUTING.md for detailed guidelines on:

• Setting up your development environment
• Code style guidelines
• Running tests
• Submitting pull requests

Quick Start for Contributors

# Fork and clone
git clone https://github.com/your-username/kader.git
cd kader

# Install dependencies
uv sync

# Run tests
uv run pytest

# Run linter
uv run ruff check .

Coding with AI

This project includes a specialized skill for AI coding agents. When working with AI assistants on this codebase, they should use the contributing-to-kader skill located in .kader/skills/contributing-to-kader. This skill provides AI agents with essential guidelines including:

• Core development rules (linting, formatting, testing)
• Key commands for development workflow
• Project structure overview
• Best practices for contributing

AI assistants can load this skill using the skills_tool to get specialized instructions for working with this project.

License

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

Acknowledgments

• Built with Rich and prompt_toolkit for the beautiful CLI interface.
• Uses Ollama for local LLM execution.
• Powered by Google Gemini for advanced cloud-based reasoning.
• Enhanced by Anthropic Claude for high-quality coding assistance.