TeDDy
TeDDy is an opinionated coding harness that structures AI-assisted development around Markdown documents and proven practices like Test-Driven Development and Hexagonal Architecture. It solves the problem of low-quality and misaligned code from AI by enforcing disciplined workflows and local-first, auditable processes. It is for developers who want to use AI for coding without sacrificing code quality and alignment with their intent.
✨ Key features
- Markdown as interface: all collaboration history in plain Markdown files.
- Enforces Test-Driven Development with Red-Green-Refactor cycles.
- Uses Hexagonal Architecture via Ports and Contracts.
- Local-first with Git snapshots for full traceability.
- Specialized agents (Pathfinder, Architect, Developer, etc.) with XML-defined workflows.
- Supports multiple LLM providers via OpenRouter API.
🎯 Use cases
- Generate a technical roadmap from a vague idea using the Pathfinder agent.
- Design system architecture with defined contracts and vertical slices.
- Implement features incrementally with test-first development.
- Debug issues using a scientific method with minimal reproductions.
- Create custom agents by editing XML prompt files.
📦 Installation
🧰 Requirements: Python 3.11 or later, pip or uv, and an OpenRouter API key (or other LLM provider configured in config.yaml).
uv tool install teddy-cli
Then initialize:
teddy init
🚀 Usage
teddy start
Or with automatic approval:
teddy start -y
Resume a previous session:
teddy resume
⚠️ Good to know
TeDDy is opinionated and enforces a specific workflow; experimental versions are available but may be unstable.
❓ FAQ
How do I configure the LLM?
Edit .teddy/config.yaml to set your API key and model. TeDDy defaults to OpenRouter, but you can change the model to any supported by OpenRouter.
Can I customize the agents?
Yes, each agent's workflow is defined in plain-text XML files under .teddy/prompts/. You can edit them or create new agents.
What is the browser chat usage?
You can use TeDDy with any LLM chat interface by copying the agent system prompt (teddy get-prompt) and project context (teddy context), then executing the generated plan with teddy execute.
How do I install experimental versions?
Use uv tool install teddy-cli --pre --force --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ --index-strategy unsafe-best-match.
📊 Repository
🤖 Overview, features, install steps and FAQ were generated from the project's README on Sep 4, 2026. Always check the original source before running commands.