kader 1.3.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.
  • Google Gemini: Cloud-based powerful models via the Google GenAI SDK.
• 🖥️ Interactive CLI - Modern TUI interface built with Textual:
  • Lazy Loading: Efficient directory tree loading for large projects.
  • TODO Management: Integrated TODO list widget with automatic updates.
• 🛠️ 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.
• 🤝 Agent-As-Tool - Spawn sub-agents for specific tasks with isolated memory and automated context aggregation.

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 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 available models from all providers.
4. The directory tree on the left features lazy loading, expanding only when needed.
5. The TODO list on the right tracks tasks identified by the planner.

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 service (if applicable).
• GOOGLE_API_KEY: API key for Google Gemini (required for Google 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)

CLI Commands

Command	Description
/help	Show command reference
/models	Show available models (Ollama & Google)
/clear	Clear conversation
/save	Save current session
/load <id>	Load a saved session
/sessions	List saved sessions
/refresh	Refresh file tree
/exit	Exit the CLI

Keyboard Shortcuts

Shortcut	Action
Ctrl+Q	Quit
Ctrl+L	Clear conversation
Ctrl+S	Save session
Ctrl+R	Refresh file tree
Tab	Navigate panels

Project Structure

kader/
├── cli/                    # Interactive command-line interface
│   ├── app.py             # Main application entry point
│   ├── app.tcss           # Textual CSS for styling
│   ├── llm_factory.py     # Provider selection logic
│   ├── widgets/           # Custom Textual widgets
│   │   ├── conversation.py # Chat display widget
│   │   ├── loading.py     # Loading spinner widget
│   │   ├── confirmation.py # Tool/model selection widgets
│   │   └── todo_list.py    # TODO tracking widget
│   └── README.md          # CLI documentation
├── examples/              # Example implementations
│   ├── memory_example.py  # Memory management examples
│   ├── google_example.py  # Google Gemini provider examples
│   ├── planner_executor_example.py # Advanced workflow examples
│   └── README.md         # Examples documentation
├── kader/                # Core framework
│   ├── agent/            # Agent implementations (Planning, ReAct)
│   ├── memory/           # Memory management & persistence
│   ├── providers/        # LLM providers (Ollama, Google)
│   ├── 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.
• GoogleProvider: High-performance access to Gemini 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.

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 with hot reload for development
uv run textual run --dev cli.app:KaderApp

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.
• Connection errors: Verify internet access for cloud providers and local service availability for Ollama.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Run the test suite
6. Submit a pull request

License

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

Acknowledgments

• Built with Textual for the beautiful CLI interface.
• Uses Ollama for local LLM execution.
• Powered by Google Gemini for advanced cloud-based reasoning.