Pre-release

This release is a pre-release and may not be stable for production use.

TeDDy

The opinionated software engineering harness

Because you should own the means of development

uv tool install teddy-cli

TeDDy TUI Demo

Why TeDDy? • TeDDy's SDLC • Owning Your SDLC • Quickstart • Usage • FAQ

Motivation

The 2025 DORA report found that AI adoption raises delivery throughput and product performance, but remains negatively related to delivery stability: code moves faster, but disproportionately more of it breaks. Any gains in raw speed are counterbalanced by increased effort needed for reviewing and reworking slop code to avoid technical defects and misalignment from compounding. Teams with fast feedback loops and loosely coupled systems see the most gain, while teams with inefficient processes and tight coupling see little or no benefit.

Bain's 2026 Technology Report reaches the same conclusion: AI has sped up coding, but that has shifted bottlenecks to review, governance, and software delivery. The limiting factor has shifted from the model to the connective architecture around it. Orchestrating and supervising AI agents is becoming an increasing part of software development at the expense of problem solving and critical thinking, which are being delegated to the machines. Better models will not by themselves fix the root causes of these structural issues.

TeDDy addresses them instead by embedding proven engineering practices like Test-Driven Development, Hexagonal Architecture, and Iterative & Incremental Delivery directly into the agentic workflow, using only local plain text files that you can read, review, and change, with nothing hidden in a proprietary database or cloud service.

Video Walkthrough

Why Not Just Use...

...Skill.md files?

Skills are designed for task-specific procedures, but stretching them to manage the entire software delivery lifecycle quickly becomes unmaintainable. Because they sit on top of your harness's built-in system prompt, upstream updates will often alter that base prompt without warning, introducing subtle conflicts or workflow drift over time. TeDDy instead organizes the full SDLC across specialized agents, where each follows a process structured into phases and concrete steps via dedicated system prompts that you fully control. Your existing skill files can still be passed to these agents as context for the task-specific jobs they were built for.

...Spec-driven development?

Spec-driven development requires you to define everything upfront before writing code. This is essentially the waterfall model under a new name, relying on the assumption that initial requirements will be completely accurate. That assumption rarely holds, as non-trivial systems always uncover edge cases and evolving requirements during development. TeDDy still uses specifications, but treats them as living documents within an iterative process more akin to Agile, allowing the design to adapt as you build.

...Automation?

TeDDy integrates automated pre-commit hooks, local test suites, and CI/CD pipelines directly into the agent workflow. Even so, automated tests alone cannot prevent misalignment or verify intent. As Bain's report notes, speeding up code generation without redesigning the surrounding process does not compound gains; it just redistributes the pain to the slowest human checkpoint. TeDDy pairs these automated quality gates with a human-in-the-loop workflow mediated through specific Markdown documents across each phase of the software delivery lifecycle.

What Makes TeDDy Special

Markdown as the interface. Inspired by Obsidian, living documents such as specs, architecture contracts, and vertical slices mediate every part of the SDLC. All agent responses and tool calls are also plain Markdown, fully controllable via the built-in TUI while leveraging your native editor instead of restricting the means of development to a chat window.
Local-first architecture. Inspired by the UNIX philosophy of small, sharp tools, TeDDy runs entirely inside your existing workspace with no cloud dependencies, proprietary databases, or background telemetry. It integrates cleanly with standard developer environments, allowing your terminal, local Git hooks, and preferred editor to drive the workflow.
Auditable by design. Inspired by Git's ledger model, every session maintains an immutable history of what the agent intended and what actually executed. Each plan enforces a structured rationale covering synthesis, justification, and expected outcomes, making agent reasoning fully traceable, searchable, and easy to parse with your own scripts for analysis.

Why Working Code Is Not Enough

LLMs are pre-trained on next-token prediction and fine-tuned with reinforcement learning to solve discrete and well-defined tasks, making them effective at writing code that works in isolation, but poorly equipped to navigate uncertainty or keep code and intent aligned over time. LLMs are also evaluated and trained on generating the final solution in one shot instead of working iteratively and incrementally, which, if left unchecked, leads to defects compounding on top of each other over time.

Defects in software come in two kinds: technical defects, where code matches your intent but breaks on edge cases or introduces bugs, and misalignment, where the code technically works but is not what you actually wanted. Most coding harnesses do little to address either one, forcing teams to patch extra tools and components into their software development lifecycle just to keep code on track. TeDDy instead tackles both types of defects directly within the harness, preventing them before they happen and mitigating them as early as possible when they do.

For technical defects, TeDDy prevents structural failures through Design by Contract, enforcing Hexagonal Architecture through ports and adapters. To mitigate bugs during development, it uses a strict Test-Driven (Red-Green-Refactor) cycle to write tests first and commit code in small units to surface errors early.

For misalignment, TeDDy prevents building the wrong thing by using spikes and prototypes to de-risk uncertain solutions before committing to an architecture. During implementation, it mitigates drift by delivering features through small vertical slices. Specific Markdown documents mediate every phase transition, anchoring the agents and providing a high-level steering interface to keep humans in the loop.

Workflow Matrix

TeDDy's Software Delivery Lifecycle

Instead of winging the process on the go or taking the shortest path to generate code, agents follow a structured delivery process mediated by plain Markdown documents:

TeDDy Workflow

Strategic Alignment & Roadmapping: The Pathfinder aligns incoming requests with the product vision, roadmap, and permanent system invariant specifications.
Contract-First Architecture: The Architect enforces Ports & Adapters boundaries, drafts component contracts, and decomposes milestones into vertical slices that deliver complete end-to-end functionality across all layers.
Sandbox De-Risking: The Prototyper conducts isolated spikes to de-risk technical and functional unknowns before any production code is touched.
Atomic Test-Driven Delivery: The Developer implements vertical slices through test-driven (Red-Green-Refactor) cycles, committing one atomic deliverable at a time to maintain a continuous green state.
Empirical Diagnostics: When bugs or regressions occur, the Debugger isolates root causes using Minimal Reproducible Examples (MREs) and validates fixes against isolated replicas before touching production code.
Automated Quality Gates & CI/CD: Local pre-commit hooks catch formatting, secret, and merge issues on staged files, while continuous integration automatically validates test suites and quality checks across platforms.
Tactical Chores: The Assistant handles one-off scripts, simple refactors, and ad-hoc maintenance through a fast feedback loop without heavy ceremonial overhead.

Owning Your SDLC

TeDDy is built on the belief that you should own your software delivery lifecycle. Even though TeDDy comes with opinionated defaults handcrafted from my own engineering preferences and daily development experience, every part of the process is designed to be easily tailored to your team's workflow without touching any application code:

High-Level Governance Rules (PROJECT.md & ARCHITECTURE.md): The simplest way to guide agents. Define product roadmaps, engineering principles, system laws, and component boundaries in living Markdown documents that agents read on every turn.
Artifact Templates (docs/templates/): Standardize the artifacts produced during development. Customize the Markdown templates for vertical slices, specifications, case files, and milestones to match your documentation standards.
Agent Prompts (.teddy/prompts/): To change the process itself, customize the agent prompts. Each agent's workflow is broken down into structured phases and individual steps, defined entirely in Markdown. You can tweak instructions, add domain-specific quality gates, or introduce brand-new agent personas to match how your team builds software.
Command Automation (Makefile): Instead of hardcoding shell commands inside agent prompts, common development and verification operations are routed through the Makefile. When you need to change a flag, runner, or environment setup, you change it once in the Makefile instead of updating instructions across multiple agent prompts.

Getting Started

Prerequisites

Python 3.11 or later
uv (recommended) or pip (included with Python)

Install TeDDy

uv tool install teddy-cli

Installing Experimental Versions

To install or upgrade to the latest development pre-release directly from PyPI:

uv tool install teddy-cli --pre --force

Initialize

teddy init

Use subcommands to overwrite specific defaults:

teddy init prompts: Overwrite bundled prompt Markdown files in .teddy/prompts/ (useful after upgrades).
teddy init config: Overwrite config.yaml, .gitignore, and init.context with defaults. Preserves existing .env files.
teddy init templates: Overwrite bundled Markdown templates in docs/templates/ with defaults.

Configuration

The first execution of teddy start runs an interactive setup to configure your API key and preferred editor. For deeper customization, edit .teddy/config.yaml. All llm.* settings pass directly through to LiteLLM, allowing you to route to cloud providers or local endpoints (Ollama, llama.cpp, or any OpenAI-compatible server via api_base). The config file also lets you adjust your external editor, command execution timeouts, diff similarity thresholds, and automated context pruning budgets.

Environment Variables

TeDDy checks the following process environment variables at startup and during a session.

Variable	Purpose
`TEDDY_LLM_API_KEY`	The LLM API key. The bundled `config.yaml` default references it as `llm.api_key: "${TEDDY_LLM_API_KEY}"`. A shell value wins over the `.teddy/.env` value.
`EDITOR`	Fallback editor command when `editor` is unset in `.teddy/config.yaml`.
`TEDDY_DIFF_TOOL`	Overrides the auto-detected diff viewer.
`TEDDY_MAX_TURNS`	Overrides the maximum number of turns for a non-interactive run.
`TEDDY_MAX_SESSION_COST`	Overrides the maximum session cost in dollars for a non-interactive run.

TeDDy also interpolates any ${VAR} or ${VAR:-default} token in .teddy/config.yaml against .teddy/.env layered under the process environment, so you can reference your own secrets from config values.

Using TeDDy in CI

TeDDy is safe to run in non-interactive environments. When stdin is not a terminal, TeDDy skips the API-key and editor setup prompts automatically, so no command blocks waiting for input.

To run TeDDy in a pipeline, set TEDDY_LLM_API_KEY in the environment and pass --pipeline (-p), which auto-approves actions, requires -m, exits after the first message turn, and defaults to the assistant agent.

TEDDY_LLM_API_KEY="$OPENROUTER_API_KEY" teddy start --pipeline -m "do the thing"

Usage

Starting and Resuming Sessions

# Start an interactive session (defaults to Pathfinder)
teddy start

# Start with automatic action approval (non-interactive)
teddy start -y

# Start with a specific agent and prompt
teddy start -a architect -m "Plan the auth module"

# Resume the most recent session
teddy resume

# Resume a specific session by slug or path
teddy resume my-feature-branch
teddy resume .teddy/sessions/20260825_151900-my-feature-branch

# Resume an ongoing session with a different agent persona
teddy resume -a developer

Interrupt a running session with q or Ctrl+C at any time. The action currently in flight will stop immediately, remaining actions will be skipped, and the report will be written to preserve the audit trail.

Resume with additional instructions:

teddy resume -m "your next instruction"

Optional Flags

--agent / -a: Select agent persona (pathfinder, architect, developer, debugger, assistant). Default: pathfinder (assistant in pipeline mode).
--context / -c: Supply additional context files or directories. Repeatable (-c a.py -c b.md) or comma-separated (-c "a.py,b.md").
--model: Override the default configured model.
--yolo / -y: Auto-approve all actions. To make this default, set yolo_default: true in .teddy/config.yaml.
--no-yolo / -n: Force interactive mode for a single run.
--message / -m: Initial instruction to pass directly to the agent.
--pipeline / -p: Pipeline mode. Auto-approves actions, requires -m, exits immediately after the first message turn, and defaults to the assistant agent.
--max-turns: Maximum turns for a non-interactive run. Overrides guardrails.max_turns in .teddy/config.yaml.
--max-cost: Maximum session cost in dollars for a non-interactive run. Overrides guardrails.max_session_cost in .teddy/config.yaml.

Chat-Oriented Workflow (CHOP)

You do not need API keys or per-token billing to use TeDDy. If you already have an active subscription (ChatGPT, Claude, Gemini, etc.), you can also use TeDDy to practice Chat-Oriented Programming (CHOP) from your web browser.

TeDDy packages your workspace context into a single clipboard payload, and the agent prompts instruct the model to automatically format its response as an executable, self-contained Markdown plan.

Set the system instructions: Copy your chosen agent persona's prompt with teddy get-prompt <agent_name> and paste it into your web interface's system prompt or custom instructions field.
Bundle project context: Export your workspace context to the clipboard with teddy context. This bundles system information, current git status, project structure, and the full verbatim contents of all files listed in .teddy/init.context into a single Markdown payload.
Prompt the AI: Paste the context payload into the chat alongside your task request. Guided by the system instructions, the model will automatically structure its response as an executable Markdown plan.
Apply changes: Copy the full Markdown plan to your clipboard and run teddy execute to validate, review diffs, and apply approved changes automatically, or copy and run individual snippets manually as you would in standard CHOP.
Report back: When teddy execute finishes, it automatically copies a concise execution report back to your clipboard to paste into the chat.

Command Reference

Command	Description
`init`	Initialize `.teddy` workspace with defaults and pre-warm dependencies.
`init prompts`	Overwrite bundled prompt Markdown files in `.teddy/prompts/` with defaults.
`init config`	Overwrite `config.yaml`, `.gitignore`, and `init.context` with defaults.
`init templates`	Overwrite bundled Markdown templates in `docs/templates/` with defaults.
`start`	Start an interactive agent session.
`resume`	Resume an existing session.
`update`	Check for updates and display upgrade instructions.
`execute`	Execute a Markdown plan (reads from clipboard if no path is provided).
`context`	Export context payload (system info, git status, file tree, `init.context`).
`get-prompt`	Retrieve agent system prompts (respects overrides in `.teddy/prompts/`).

Frequently Asked Questions

Does TeDDy collect telemetry or phone home?

No. TeDDy collects zero telemetry, zero analytics, and runs no background tracking. All requests go directly to whichever LLM provider or local endpoint you configure in your local config file.

Which models and providers are supported?

TeDDy uses LiteLLM under the hood. You can route to any provider supported by LiteLLM, including OpenRouter, Anthropic, OpenAI, and Google Gemini. For local models, it supports Ollama, vLLM, LM Studio, llama.cpp, and any OpenAI-compatible endpoint.

Do I need to migrate my existing codebase to use this?

No. TeDDy is designed to run inside existing repositories. It only creates a .teddy/ directory in your project root to hold prompts, configuration, and session history.

How do teams collaborate with TeDDy?

All strategic artifacts created by agents (roadmaps in docs/project/, component designs, and vertical slices) are saved directly in your repository's docs/ directory and committed to Git like regular code. The internal .teddy/ directory is ignored by default, keeping private session logs and environment credentials local to each developer.

Are there hidden fees? How is TeDDy licensed and monetized?

There are no subscriptions, hidden fees, or token markups. You bring your own API keys or local models and pay providers directly at standard rates with zero middleman.

TeDDy is completely free software under the AGPL-3.0 license. As a copyleft license, if you modify and distribute TeDDy itself, your changes must also be open-sourced under the AGPL. However, using TeDDy as a development harness to write your own software does not affect your codebase; you fully own all code generated by the agents under whatever license you choose.

The tool itself is not monetized. If your team needs custom agent architectures, workflow design, or dedicated onboarding support, professional consulting is available at raphael@atteritano.ch.

Learn More

Star TeDDy on GitHub

If you find TeDDy useful for your workflow, consider giving it a star. It helps other developers find the project.

Need custom agent architectures or team onboarding? Let's get in touch!

Metadata

Release files for teddy-cli 0.1.17.dev1325

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for teddy-cli 0.1.17.dev1325
File	Size	Uploaded
teddy_cli-0.1.17.dev1325.tar.gz	250.8 kB	Oct 16, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for teddy-cli 0.1.17.dev1325
File	Interpreter	ABI	Platform	Reset
teddy_cli-0.1.17.dev1325-py3-none-any.whl 332.6 kB Oct 16, 2026	Python 3	none	any	Details

Total release size: 583.4 kB

Release files / teddy_cli-0.1.17.dev1325.tar.gz

Download URL	teddy_cli-0.1.17.dev1325.tar.gz
Size	250.8 kB
Tags	Source
SHA-256 checksum How to use checksums	`c055eafe976f1770b59c054d4cf964fda7d5cabd8b558c632264c0bfa948da8d`
BLAKE2b-256 checksum How to use checksums	`81ddc42db27551bebbbf528064b42189becd9203a617a7978df2828d1e0c8e13`
Upload date	Oct 16, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/atte500/TeDDy
Publishing commit: github.com/atte500/TeDDy/tree/f589688b573d62720f6d3a754969e061f0a02655

Workflow

Publishing configuration: github.com/atte500/TeDDy/blob/f589688b573d62720f6d3a754969e061f0a02655/.github/workflows/publish.yml
Publishing logs: github.com/atte500/TeDDy/actions/runs/38915954632/attempts/1

Artifact

Subject: teddy_cli-0.1.17.dev1325.tar.gz
SHA-256 checksum: c055eafe976f1770b59c054d4cf964fda7d5cabd8b558c632264c0bfa948da8d Verifying attestations

Release files / teddy_cli-0.1.17.dev1325-py3-none-any.whl

Download URL	teddy_cli-0.1.17.dev1325-py3-none-any.whl
Size	332.6 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`6f09bf3de9c92f88ed19730bcda30176377851f323983a407c27340d211a992d`
BLAKE2b-256 checksum How to use checksums	`7adb2e223977823369875e98f4f6c7b8c1638949fcb52e8cb733e2775809c0be`
Upload date	Oct 16, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/atte500/TeDDy
Publishing commit: github.com/atte500/TeDDy/tree/f589688b573d62720f6d3a754969e061f0a02655

Workflow

Publishing configuration: github.com/atte500/TeDDy/blob/f589688b573d62720f6d3a754969e061f0a02655/.github/workflows/publish.yml
Publishing logs: github.com/atte500/TeDDy/actions/runs/38915954632/attempts/1

Artifact

Subject: teddy_cli-0.1.17.dev1325-py3-none-any.whl
SHA-256 checksum: 6f09bf3de9c92f88ed19730bcda30176377851f323983a407c27340d211a992d Verifying attestations