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
🔧 Custom Tools - Create custom tools for specific tasks, available to planner and/or executor agents

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:

Type any question to start chatting with the agent.
Use /help to see available commands.
Use /models to check and interactively switch available models.
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,
  "callbacks": [],
  "tools": []
}

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`
`callbacks`	List of user-level callbacks to enable	`[]`
`tools`	List of user-level custom tools to enable	`[]`

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 and create new session
`/sessions`	List and load 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.

Custom Tools

Kader supports custom tools that can be added at user-level or project-level. Custom tools extend agent capabilities beyond built-in tools.

Tool Locations

Project-level: ./.kader/custom/tools/ (always enabled)
User-level: ~/.kader/custom/tools/ (requires configuration in settings.json)

Creating a Custom Tool

Create a Python file in the tools directory that defines a class extending BaseTool:

from kader.tools.base import BaseTool, ParameterSchema, ToolCategory

class MyTool(BaseTool[str]):
    def __init__(self):
        super().__init__(
            name="my_tool",
            description="What my tool does",
            parameters=[
                ParameterSchema(
                    name="param1",
                    type="string",
                    description="Parameter description",
                    required=True,
                ),
            ],
            category=ToolCategory.UTILITY,
        )

    def execute(self, **kwargs: Any) -> str:
        param1 = kwargs.get("param1", "")
        return f"Processed: {param1}"

    async def aexecute(self, **kwargs: Any) -> str:
        return self.execute(**kwargs)

    def get_interruption_message(self, **kwargs: Any) -> str:
        return f"execute my_tool"

Agent Targeting

Custom tools can be assigned to specific agents:

For user-level tools (in settings.json):

{
  "tools": [
    {
      "name": "my_tool.MyTool",
      "enabled": "true",
      "agent": "executor"
    }
  ]
}

Agent options: planner | executor | both (default)

For project-level tools (in tool directory): Create an agent.json file in the tool directory:

{
  "agent": "both"
}

Example: DateTimeTool

Project-level tool at .kader/custom/tools/datetime_tool/:

.kader/custom/tools/datetime_tool/
├── __init__.py
└── agent.json

agent.json:

{
  "agent": "both"
}

Usage:

What time is it in Japan?

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.

Name		Name	Last commit message	Last commit date
Latest commit History 491 Commits
.github/workflows		.github/workflows
.kader		.kader
.opencode/skills/contributing-to-kader		.opencode/skills/contributing-to-kader
assets		assets
cli		cli
docs		docs
examples		examples
kader		kader
tests		tests
.gitignore		.gitignore
.python-version		.python-version
AGENTS.md		AGENTS.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
mkdocs.yml		mkdocs.yml
pyproject.toml		pyproject.toml
uv.lock		uv.lock

Folders and files

Latest commit

History

Repository files navigation

Kader

Features

Installation

Prerequisites

Using uv (recommended)

Using uv tool

Using pip

Quick Start

Running the CLI

First Steps in CLI

Configuration

Environment Variables

Memory and Sessions

Settings

Auto-Update

CLI Commands

Keyboard Shortcuts

Project Structure

Core Components

Agents

LLM Providers

Agent-As-Tool (AgentTool)

Agent Skills

Special Commands

Creating a Special Command

Example: Lint and Test Command

Custom Tools

Tool Locations

Creating a Custom Tool

Agent Targeting

Example: DateTimeTool

File System Tools with Gitignore Filtering

Memory Management

Development

Setting up for Development

Running Tests

Code Quality

Troubleshooting

Common Issues

Contributing

Quick Start for Contributors

Coding with AI

License

Acknowledgments

About

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 59

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages