OpenAgent

I built this to replace the need for a more expensive AI ChatBot as my Directive Writer for my IDE Coding Agent. It nearly works using OpenRouter.

OpenAgent reads your codebase and generates strategic recommendations shaped to your architectural preferences and development style.

Quick Start

# Install
pip install openagent-directive

# First time setup - personalize your experience
openagent init

# Generate personalized strategic analysis
openagent analyze

# Check repository structure  
openagent inventory

What It Does

OpenAgent is a repo-aware directive generator that:

• Reads your actual codebase - understands your files, structure, and patterns
• Personalizes recommendations - uses your SOUL.md profile to shape advice to your style
• Generates strategic directives - creates actionable improvement plans
• Advises, doesn't execute - you maintain full control over all decisions

Who It's For

Developers who want to understand their codebase better:

• Solo developers working on complex projects
• Teams needing architectural guidance
• Developers transitioning between projects
• Anyone wanting strategic improvement recommendations

How It Works

1. Personalize Your Experience

openagent init

• 8-question interview captures your working style
• Creates SOUL.md with your preferences
• Shapes all future directive generation

2. Get Strategic Analysis

openagent analyze

• Analyzes your repository structure
• Considers your SOUL.md preferences
• Generates personalized recommendations

3. Take Action

OpenAgent provides clear, actionable directives. You decide what to implement.

Key Features

• Repo-aware analysis - Understands your actual code structure
• Personalized recommendations - Shaped to your working style
• Strategic guidance - Focuses on what matters most for your project
• Advisory mode only - Never executes code, always advises
• CLI-driven - Simple command-line interface

Installation

# Install with pip
pip install openagent-directive

# Or with uv  
uv add openagent-directive

Usage Examples

Basic Analysis

# Analyze current repository
openagent analyze

# Check repository structure
openagent inventory

# See system health
openagent health

Personalized Workflow

# Setup your profile
openagent init

# Get personalized advice
openagent analyze --context "Preparing for v2.0 release"

# Monitor costs
openagent costs

What OpenAgent Analyzes

• Repository Structure: File organization, architecture patterns
• Code Quality: Maintainability, complexity, technical debt
• Documentation: Completeness, consistency, alignment
• Dependencies: Security, versions, conflicts
• Test Coverage: Gaps, organization, quality metrics
• Strategic Opportunities: Missing components, improvements

Architecture

Built with:

• Google ADK for LLM orchestration
• Multi-Agent System for specialized analysis
• Personalization Engine via SOUL.md integration
• Rich CLI for developer experience

Development Status

See docs/state/current.md for current implementation status.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass
6. Submit a pull request

License

MIT License - see LICENSE file for details.

Support

• Documentation: docs/ directory
• Issues: GitHub Issues
• Discussions: GitHub Discussions MIT