The AI coding assistant that thinks before it ships. Terminal-native · Browser-ready · DeepSeek-powered

✨ Why LuckyD Code?

🚀 Quick Start

Prerequisites

• Python 3.10+ – python.org or brew install python@3.12
• Rust – only needed if pip can’t find a pre‑built wheel for your platform (uncommon).

Installation

# Install from PyPI (recommended)
pip install luckyd-code

# With optional RAG support (code search & knowledge graph)
pip install luckyd-code[rag-full]

# Browser automation (for web scraping / testing)
pip install luckyd-code[browser]

Or clone and install in editable mode for development:

git clone https://github.com/Dylanchess0320/LuckyD-Code
cd LuckyD-Code
pip install -e ".[dev]"

Usage

# Start the interactive CLI
luckyd-code

# Launch the web UI (FastAPI + WebSocket)
luckyd-code --web

# Show help
luckyd-code --help

# Quick alias (same as luckyd-code)
ldc

From source:

python main.py                    # CLI
python main.py --web              # Web UI
python main.py --version          # v1.3.4

🔑 Configuration

Create a .env file in the project root or set the environment variable:

# DeepSeek API key (required)
DEEPSEEK_API_KEY=sk-your-deepseek-key-here

Get your key at platform.deepseek.com.

Optional settings (see config.py for all options):

Settings are resolved in this order: environment variable → config file → defaults.

🌟 Features

Core

• Think → Act → Verify loop – Model generates code, tools execute it, verification checks syntax, lint, and tests automatically.
• Smart model routing – Four tiers (T1–T4) from lightweight chat to deep reasoning; heuristic + LLM classifier for sub‑400ms selection.
• 40+ built‑in tools – File ops, Git operations, Docker sandbox, web fetch, code generators, browser automation, and more.

Code Intelligence

• Code Knowledge Graph (RAG) – FAISS index + sentence‑transformers for semantic code search across your entire project.
• Project Memory – Persistent context across sessions: remembers your codebase structure and conversation history.
• Autonomous Fixer – Detects errors, writes patches, runs verification, and can open a PR automatically.

Interface

• Full CLI – Rich terminal UI with syntax highlighting, streaming responses, slash commands (/help, /install-rag, etc.).
• Web UI – FastAPI + WebSocket server, same agent loop, accessible from any browser.
• Lifecycle hooks – Run custom scripts before/after actions, integrate with CI/CD pipelines.

Security & Analytics

• Docker‑sandboxed bash – All shell commands run isolated by default.
• Permission system – Granular control over file read/write, network, and tool access.
• Code analytics – Smell detection, trend tracking, and health reporting.

🏗️ Architecture

User input (CLI or Browser)
       │
       ▼
  ┌──────────────────┐      ┌──────────────────┐
  │    cli.py /       │      │  web_app.py      │
  │  cli_entry.py     │      │  (FastAPI)       │
  └────────┬─────────┘      └────────┬─────────┘
           │                         │
           └──────────┬──────────────┘
                      │
              ┌───────▼───────┐
              │   router.py    │  Prompt classification → model tier
              │ (heuristic +   │
              │  LLM fallback) │
              └───────┬───────┘
                      │
              ┌───────▼─────────┐
              │  _agent_loop.py  │  Think → Act → Verify (max N turns)
              └───────┬─────────┘
                      │
         ┌────────────┴────────────┐
         │                         │
  ┌──────▼──────┐        ┌─────────▼──────────┐
  │  api.py      │        │  tools/registry.py  │
  │ (stream SSE)│        │  40 tools + 5min TTL│
  └─────────────┘        └─────────────────────┘

For full details, see ARCHITECTURE.md.

🧪 Development & Testing

# Run all tests
pytest

# With coverage (target ≥97%)
pytest --cov=luckyd_code

# Type checking
mypy luckyd_code

# Lint with pre‑commit hooks
pre-commit run --all-files

# Scan for accidentally committed secrets
make secrets-scan   # requires gitleaks

See CONTRIBUTING.md for the full contributor guide.

🤝 Contributing

We welcome contributions! Please read the Contributing Guide for setup instructions, coding standards, and the PR process.

By contributing, you agree that your contributions will be licensed under AGPL v3. For alternative licensing, contact the maintainer.

📄 License

This project is licensed under the GNU Affero General Public License v3. See LICENSE for the full text.

Built with ❤️ by Dylan Kaye.