luckydofficial-code 1.3.5

LuckyD Code — AI coding assistant powered by DeepSeek

LuckyD Code

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

---

✨ Why LuckyD Code?

	LuckyD Code	Other Assistants
🧠 Reasoning-first	Self-verifies every write/edit automatically	Hope the LLM gets it right
🔀 Smart routing	Picks the right model tier per prompt	Same model for everything
🐝 Multi-Agent Swarms	Spawn parallel specialist agents that coordinate via shared tasks	Single-agent only
🗺️ Code Knowledge Graph	Indexes your codebase; semantic + keyword search	Blind to your project
🕸️ Web + Terminal	Full CLI and browser UI from the same binary	CLI-only or browser-only
🔒 Sandboxed	Docker-isolated command execution	Raw shell access
🔭 LSP integration	Go-to-definition, references, rename across files via pylsp/pyright	None
📊 Analytics	Built-in code health, smell detection, trend tracking	None
🔧 Autonomous Fixer	Diagnoses bugs → generates patches → validates → opens PR	Manual triage
📓 Notebook editing	Cell-level Jupyter .ipynb read/write with execution-count clearing	None
📋 Plan Mode	Read-only exploration & design phase before writing any code	Blind edits
🧩 Plugin system	Drop a .py file, auto-loads as an AI tool — no restart	Limited or no extensibility

---

🚀 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 luckydofficial-code

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

# Browser automation (Playwright-powered web scraping / testing)
pip install luckydofficial-code[browser]

# Game generation (Pygame)
pip install luckydofficial-code[game]

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

---

🔑 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):

Variable	Description
DEEPSEEK_API_KEY	Primary API key
OPENAI_API_KEY	Fallback/alternative provider
LUCKYD_CONFIG_DIR	Custom config directory
LOG_LEVEL	DEBUG, INFO, WARNING, ERROR

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

---

🌟 Features

Core Agent Loop

• Think → Act → Verify – The model generates code, tools execute it, and verification checks syntax, lint, and tests automatically.
• Stuck-loop detection – Identical tool-call batches are detected and broken automatically with a nudge message.
• Smart model routing – Four tiers (T1–T4) from lightweight chat to deep reasoning; heuristic + LLM classifier for sub‑400ms selection.
• Mid-loop model escalation – Automatically upgrades to a stronger model tier when verification keeps failing.
• Verification nudge – Warns the model when it makes multiple consecutive write batches without running any tests or lint.
• Streaming responses – Real-time SSE streaming in both CLI and web UI.
• Cost tracking – Token usage and cost estimation per session.

Multi-Agent & Orchestration

• Swarm Teams (TeamCreate/TeamStatus/TeamDelete) – Spawn up to 8 parallel specialist agents with shared tasks. Each agent runs its own full agent loop with independent tool access.
• Agent Handoff – Chain specialist agents: researcher → coder → reviewer → tester. Each role gets its own context and tools.
• Sub-Agents – Fork an isolated agent for a self-contained subtask without polluting the main conversation.
• Smart Orchestrator – An agentic coordinator that decides which workers to spawn, collects their results, and synthesizes findings.
• Task System – Persistent cross-session tasks with status tracking (pending → in_progress → completed → blocked), dependencies, tags, and priority levels.
• Forked Skills – Run built-in skills (review, security, test-gen, docs, refactor) in isolated sub-agents with dedicated token budgets.

Plan Mode

• Read-only exploration phase – Before writing any code, LuckyD explores your codebase, identifies patterns, considers trade-offs, and designs a concrete implementation strategy.
• User approval gate – Plans are presented for review before any file is modified.
• Structured questions – Clarify ambiguous requirements with multiple-choice prompts during planning.

🛠️ 50+ Built-in Tools

File & Code Operations

Tool	Description
Read	Read files with line offsets and limits
Write	Create or overwrite files with dry-run diff preview
Edit	Exact-string replacement with replace-all support
Diff	Unified diff — file vs proposed, file vs file, string vs string
Glob	Recursive file pattern matching (e.g. src/**/*.ts)
Grep	Regex search via ripgrep with file/content/count modes
Brief	AI-powered file/directory/text summaries

Git & Version Control

Tool	Description
GitStatus	Working tree status
GitDiff	Staged/unstaged diffs
GitLog	Recent commit history
GitCommit	Create commits
GitAdd	Stage files
GitBranch	List and manage branches
GitPush	Push to remote
GitPR	Push + create draft PR
GitWorktree	Isolated git worktrees for safe experimentation

LSP / Code Intelligence

Tool	Description
LspDefinition	Go-to-definition
LspReferences	Find all references across project
LspHover	Type info and docstrings
LspRename	Safe symbol rename (all references)
LspDocumentSymbols	File outline (classes, functions, variables)
LspWorkspaceSymbols	Project-wide symbol search
LspImplementation	Find concrete implementations of abstract methods
LspIncomingCalls	Who calls this function?
LspOutgoingCalls	What does this function call?

Browser & Web

Tool	Description
BrowserNavigate	Navigate to URL
BrowserClick	Click elements via CSS selector
BrowserType	Type text into inputs
BrowserSnapshot	Text snapshot of page elements
BrowserScreenshot	Capture screenshots (PNG)
BrowserEvaluate	Run JavaScript on page
BrowserIntercept	Mock/block network requests
BrowserTrace	Record screenshots + network + DOM traces
BrowserEmulate	Emulate mobile devices (iPhone, Pixel, iPad)
WebFetch	Fetch and extract text from URLs
WebSearch	Web search with result extraction
Http	HTTP client (GET/POST/PUT/PATCH/DELETE with JSON, forms, auth)
OpenInBrowser	Open URLs in user's system browser
YouTubePlaylist	Build YouTube playlists from video URLs

Shell & Process

Tool	Description
Bash	Execute shell commands
PowerShell	Execute PowerShell commands (Windows)
Process	Background process manager (start/read/status/kill)
ShellHistory	Read recent bash/zsh/fish/PowerShell history
Watch	Watch files for changes (exists/changed/contains/deleted)

Data & Databases

Tool	Description
SQLite	Query, execute, schema, tables on SQLite files
NotebookRead	Read Jupyter .ipynb cells
NotebookEdit	Cell-level edit (replace/insert/delete) on notebooks
Repl	Persistent Python REPL with namespace across calls
ImageAnalyze	Analyze images (JPEG/PNG/GIF/BMP/WebP)

Memory & Knowledge

Tool	Description
Memory	Persistent key-value store (set/get/list/delete/search)
BrainSearch	Semantic codebase search via FAISS + sentence-transformers
BrainStatus	Index stats and knowledge graph health

Task & Team Coordination

Tool	Description
TaskCreate	Create tracked tasks with dependencies and tags
TaskUpdate	Update task status and output
TaskGet	Retrieve full task details
TaskList	List tasks filtered by status/tag
TaskOutput	Read task output (blocking or non-blocking)
TeamCreate	Spawn parallel multi-agent swarm
TeamStatus	Poll live agent progress
TeamDelete	Shut down and clean up a team
SendMessage	Inter-agent messaging (broadcast or direct)
ReceiveMessage	Read pending messages from agent inbox

Code Generation

Tool	Description
ProjectGen	Generate full project scaffolds from plain English
DockerfileGen	Auto-detect stack → generate Dockerfile + docker-compose.yml
ReadmeGen	Scan project → generate professional README.md
GameGen	Generate runnable Pygame games from descriptions

Automation & Scheduling

Tool	Description
CronCreate	Schedule recurring or one-shot prompts
CronList	List active cron jobs
CronDelete	Cancel scheduled jobs
AutoCommit	Automatic git commits with generated messages
Backup	Session backup and restore

Utilities

Tool	Description
Secrets	Read .env keys or system keychain (never dumps all secrets)
Notify	Desktop toast notifications on task completion
DateTime	Current local date/time
Sleep	Pause agent (0.1–300s)
SkillList / ForkedSkill	List and run reusable skills in isolated agents
ToolSearch	Search available tools by keyword
Config	Read/write agent settings mid-session
EnterPlanMode / ExitPlanMode	Read-only design phase gate
EnterWorktree / ExitWorktree	Isolated git worktrees for risky changes

Interface

• Full CLI – Rich terminal UI with syntax highlighting, streaming responses, slash commands (/help, /doctor, /share, /pr-comments, /plugins, /brain, /audit, /sessions, /budget, /config, /effort, /background).
• Web UI – FastAPI + WebSocket server, same agent loop, accessible from any browser. Full session management, file browser, settings panel, cost dashboard.
• Keybindings – emacs-style navigation, Ctrl+R history search, multi-line editing.
• Themes – Configurable Rich color themes for terminal output.

Security & Quality

• Docker‑sandboxed bash – All shell commands run isolated by default (configurable).
• Permission system – Granular control over file read/write, network, and tool access.
• Secrets scanning – Built-in gitleaks integration for pre-commit secret detection.
• 96% test coverage – Strict coverage threshold enforced in CI.
• Full mypy type coverage – All core modules are fully typed and mypy-clean.
• Pre-commit hooks – Ruff formatting, type checking, secret scanning on every commit.

Analytics & Self-Improvement

• Code analytics – Smell detection, trend tracking, and health reporting.
• Autonomous fixer – Error detection → patch generation → validation → PR creation.
• Feedback analyzer – Learns from corrections and adjusts behavior.
• Self-improve – Internal self-critique and improvement loop.
• Audit daemon – Background watcher for codebase health.

Extensibility

• Plugin system – Drop a .py file into ~/.luckyd-code/plugins/, run /plugins reload, and it auto-loads as a new AI tool. No restart needed.
• Lifecycle hooks – Run custom scripts before/after actions; integrate with CI/CD pipelines.
• MCP client – Model Context Protocol support for connecting external tools.
• Custom skills – Add .md files to .luckyd-code/skills/ for reusable agent behaviors.

---

📚 Documentation

Document	Description
ARCHITECTURE.md	Full system architecture and data flow
SKILLS.md	Built-in skills: review, security analysis
PLUGINS.md	Plugin development guide
CONTRIBUTING.md	Contributor setup and guidelines
TODO.md	Roadmap and improvement tracker

---

🧪 Development & Testing

# Run all tests
pytest

# With coverage (threshold ≥96%)
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

---

🤝 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.

---

📦 Roadmap

See TODO.md for the full roadmap. Short-term priorities:

• Multi-provider support (OpenAI, Groq, Together natively alongside DeepSeek)
• VS Code and JetBrains extension
• Test coverage for the new v1.3.5 tool suite
• Plugin marketplace for third-party tools

---

Built with ❤️ by Dylan Kaye.