CODECTL

SDD is all you need

English documentation. 中文版请见：README.zh-cn.md

Local Web UI for Spec‑Driven Development that maximizes the effective use of Codex and other coding agents.

Features

• Spec‑Driven Development workflow (Spec → Task → Coding)
• Local Web UI for everyday workflows (embedded SPA)
• Manage CLI coding agents (Codex / Claude Code / Gemini CLI)
• Manage MCP and third‑party models
• Provider catalog v2 at ~/.codectl/provider.json with JSON Schema
• CLI helpers: interactive usage and scriptable integration

Why Spec‑Driven Development

• Spec: define specs in vibe-docs/spec/
• Task: define tasks in vibe-docs/task/
• Coding: execute implementation via LLMs

Quick Start

1. Build and run codectl (starts local Web UI by default):

# Run locally for development
go run . -o   # start server and open browser

# Or build a binary
go build -o codectl
./codectl -o  # start server and open browser

Usage

codectl                         # Start embedded Web UI server (default)
codectl -a 127.0.0.1:8787 -o    # Bind address and open browser
codectl webui -o                # Same as above, explicit subcommand

# Spec workflow helpers
codectl spec                    # Open Spec UI in the Web UI
codectl spec new "<desc>"       # Generate a spec draft via Codex into vibe-docs/spec
codectl check [--json]          # Validate *.spec.mdx frontmatter under vibe-docs/spec

# Configuration & providers
codectl config                  # Initialize ~/.codectl (provider/models/mcp) and print path
codectl config -w               # Run interactive config wizard
codectl provider sync           # Create/normalize ~/.codectl/provider.json (v2)
codectl provider schema         # Print JSON Schema for provider.json (v2)

# Utilities
codectl codex [args...]         # Shorthand to launch Codex (gpt-5, high reasoning)
codectl version                 # Print version (numeric only; script-friendly)
codectl update                  # Self-update (planned; placeholder)

Notes:

• The default server binds to 127.0.0.1:8787. Use -a to change.
• codectl cli remains as a compatibility alias that opens the Web UI.

Roadmap

• 1. Prototype
• 2. Better Spec TUI
• 3. Config Wizard (MCP/Custom Provider)

Config Directory

Default location: ~/.codectl/

• provider.json (v2): provider catalog; edit to add providers/models. See schema via codectl provider schema.
• models.json: seeded from provider catalog if missing.
• mcp.json: example generated by codectl config if missing.

Development & Build

Requirement: Go 1.25+ (latest stable recommended)

# Fetch deps (first run will pull automatically)
go mod download

# Run locally
go run .

# Build binary
go build -o codectl

Make targets:

• make start – hot reload dev (requires go install github.com/air-verse/air@latest)
• make format – go fmt ./...
• make lint – golangci-lint run or fallback go vet ./...
• make test – writes coverage to coverage.out
• make docker-test – run tests in Docker (e.g., GO_TEST_FLAGS='-v -run TestLoad')

Contributions welcome: please consider updating specs in vibe-docs/spec/ first, then submit implementation + docs.

Disclaimer

codectl helps you install, check, and configure third‑party tools; it does not provide model inference itself. The capabilities, stability, and terms of third‑party CLIs/MCPs are governed by their respective providers—review and follow their usage policies as needed.

Security & Environment

• Do not commit secrets. Respect OPENAI_API_KEY, ANTHROPIC_API_KEY, GOOGLE_API_KEY, and proxy env vars.
• The app runs locally; review provider terms before use.

License

MIT License. See LICENSE.