Metadata-Version: 2.3
Name: cdd-agent
Version: 0.0.2
Summary: AI coding assistant with structured CDD workflows - LLM agnostic terminal agent
License: MIT
Keywords: ai,llm,coding-assistant,anthropic,openai,cli,agent
Author: Guilherme Gouw
Author-email: guilherme.gouw@gmail.com
Requires-Python: >=3.10,<4.0
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Code Generators
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Dist: anthropic (>=0.40.0,<0.41.0)
Requires-Dist: click (>=8.1.7,<9.0.0)
Requires-Dist: httpx (>=0.27.0,<0.28.0)
Requires-Dist: openai (>=1.55.0,<2.0.0)
Requires-Dist: pydantic (>=2.10.0,<3.0.0)
Requires-Dist: python-dotenv (>=1.0.0,<2.0.0)
Requires-Dist: pyyaml (>=6.0.1,<7.0.0)
Requires-Dist: rich (>=13.7.0,<14.0.0)
Requires-Dist: textual (>=0.87.1,<0.88.0)
Project-URL: Homepage, https://github.com/guilhermegouw/context-driven-development-agent
Project-URL: Repository, https://github.com/guilhermegouw/context-driven-development-agent
Description-Content-Type: text/markdown

# CDD Agent

**LLM-agnostic AI coding assistant with structured CDD (Context-Driven Development) workflows**

---

## What is CDD Agent?

CDD Agent is a terminal-based AI coding assistant that lets you use **any LLM provider** - Anthropic (Claude), OpenAI (GPT), or custom endpoints - without vendor lock-in. It implements the Context-Driven Development workflow: **Spec → Plan → Execute**, creating a virtuous cycle where development generates documentation that provides perfect context for AI assistance.

**Unlike vendor-specific tools** (Claude Code, Cursor), CDD Agent gives you:
- Freedom to choose your LLM provider
- Structured workflows that maintain context
- Local configuration and control
- No subscription lock-in

---

## Current Status: v0.0.1 (Experimental)

This is an **early experimental release**. Currently functional:
- Multi-provider configuration (Anthropic, OpenAI, custom endpoints)
- Authentication system with credential management
- CLI interface for setup and testing
- Model tier abstraction (small/mid/big)

**Coming soon:**
- Conversational agent loop
- Tool execution system
- Specialized CDD workflow agents (Socrates, Planner, Executor)
- Rich terminal UI with streaming responses

See [ROADMAP.md](ROADMAP.md) for the full development plan.

---

## Installation

```bash
pip install cdd-agent
```

**Requirements:**
- Python 3.10 or higher
- API keys for your chosen LLM provider(s)

---

## Quick Start

### 1. Configure your LLM provider

```bash
# Interactive setup wizard
cdd-agent auth setup

# Or set environment variables
export CDD_ANTHROPIC_API_KEY="your-api-key"
export CDD_OPENAI_API_KEY="your-api-key"
```

### 2. Verify your configuration

```bash
# Check configured providers
cdd-agent auth status

# Test API credentials
cdd-agent auth test
```

### 3. Start coding (coming in v0.1.0)

```bash
# Interactive conversation mode
cdd-agent chat

# CDD workflow modes
cdd-agent socrates  # Spec generation
cdd-agent plan      # Task planning
cdd-agent execute   # Implementation
```

---

## Features

### Multi-Provider Support
- **Anthropic**: Claude Haiku, Sonnet, Opus
- **OpenAI**: GPT-4o, GPT-4, GPT-3.5
- **Custom**: Any OpenAI-compatible endpoint (local models, proxies, alternative providers)

### Model Tier Abstraction
Configure models by tier instead of specific versions:
- **Small**: Fast, cheap operations (file searches, quick queries)
- **Mid**: Balanced performance (general coding, planning)
- **Big**: Maximum capability (complex reasoning, refactoring)

### Secure Configuration
- Local settings file: `~/.cdd-agent/settings.json`
- Environment variable overrides
- No telemetry or data collection
- Your code stays on your machine

---

## Configuration

CDD Agent uses a local configuration file at `~/.cdd-agent/settings.json`:

```json
{
  "providers": {
    "anthropic": {
      "api_key": "your-key",
      "models": {
        "small": "claude-haiku-4-5-20250929",
        "mid": "claude-sonnet-4-5-20250929",
        "big": "claude-opus-4-5-20250929"
      }
    },
    "openai": {
      "api_key": "your-key",
      "models": {
        "small": "gpt-4o-mini",
        "mid": "gpt-4o",
        "big": "gpt-4o"
      }
    }
  },
  "default_provider": "anthropic"
}
```

**Environment variables** (override settings file):
- `CDD_ANTHROPIC_API_KEY`
- `CDD_OPENAI_API_KEY`
- `CDD_CUSTOM_ENDPOINT`
- `CDD_DEFAULT_PROVIDER`

---

## Why CDD Agent?

### The Problem
Existing AI coding assistants lock you into a single vendor:
- Claude Code → Anthropic only
- Cursor → OpenAI only
- GitHub Copilot → GitHub/OpenAI only

### The Solution
CDD Agent provides:
- **Provider freedom**: Switch between Claude, GPT, or local models anytime
- **No lock-in**: Your workflows work with any LLM
- **Local control**: Configuration stays on your machine
- **Structured workflows**: CDD methodology keeps AI assistance contextual and effective

---

## Development

CDD Agent is built with:
- **Python 3.10+** for developer productivity
- **Click** for CLI framework
- **Rich** for beautiful terminal UI
- **Pydantic** for configuration management
- **Poetry** for dependency management

### Contributing

This is an early-stage project! Contributions welcome:
1. Check [ROADMAP.md](ROADMAP.md) for planned features
2. Open an issue to discuss your idea
3. Submit a PR with tests

### Running from source

```bash
git clone https://github.com/guilhermegouw/context-driven-development-agent.git
cd context-driven-development-agent
poetry install
poetry run cdd-agent --help
```

---

## Roadmap

**v0.0.x**: Foundation (auth, config, CLI) ✅
**v0.1.x**: Basic agent loop (conversation, tool execution)
**v0.2.x**: CDD workflows (Socrates, Planner, Executor)
**v0.3.x**: Rich TUI and streaming
**v1.0.0**: Stable API, full CDD workflow

See [ROADMAP.md](ROADMAP.md) for detailed milestones.

---

## License

MIT License - see [LICENSE](LICENSE) for details.

---

## About Context-Driven Development

CDD Agent implements the Context-Driven Development methodology, where development creates documentation that provides perfect context for AI assistance. Learn more: [Context-Driven Documentation Framework](https://github.com/guilhermegouw/context-driven-documentation)

---

**Built by developers, for developers. No vendor lock-in. Your code, your choice.**

