codegenie-agent 0.1.0

Code Genie — a terminal coding agent (read, edit, and run your project from the CLI).

Code Genie — MVP (Runnable, $0-cost-by-default)

This is a real, working implementation, not a mockup. It has been tested end-to-end: upload → scan → diagnose → (optional) sandbox verify, with automated tests proving the rule engine actually matches and scores correctly.

What's real here vs. what's still a roadmap item

✅ Working now:

• ZIP upload with safety checks (zip-bomb ratio, path traversal, size/type limits, empty-zip handling)
• Project scanner (package.json, requirements.txt, Dockerfile, README, monorepo detection)
• Free rule-based diagnosis engine — 10 starter known-issues, matches log patterns + dependency version ranges, $0 cost, no API key needed
• Optional LLM fallback (only fires when the rule engine finds nothing) — defaults to none, supports free-tier Groq/Gemini/OpenRouter if you choose to add a key
• Docker-based sandbox build verification (network-disabled, memory/CPU/time capped, non-root)
• Basic auth header, naive rate limiting, session TTL + cleanup
• A working frontend (plain HTML/JS, no build step)

🚧 Not yet built (be honest about this with users):

• GitHub OAuth / private repo scanning
• Multi-language support beyond Node/Next.js and basic Python
• A production-grade job queue (current version runs analysis synchronously — fine for low volume, will need Celery/Redis before real concurrent load)
• Hardened sandboxing (this uses plain Docker, not Firecracker/gVisor — fine for a trusted beta, not for hostile public traffic at scale)
• Persistent database (sessions are in-memory — restarting the server loses session state; swap in Postgres/Redis before real users)

Terminal coding agent (NEW)

Code Genie now ships an interactive terminal agent (like Codebuff) that works directly inside your project. It can read files, list directories, write/overwrite files, and run shell commands via LLM tool-calling — asking for confirmation before any mutating action.

cd codegenie-app
python3 -m venv venv && source venv/bin/activate
pip install -e .          # installs Code Genie + the `codegenie` command

# Configure a tool-calling provider (Groq or OpenRouter):
export LLM_PROVIDER=groq
export LLM_API_KEY=your_groq_key_here
export LLM_MODEL=llama-3.1-8b-instant   # optional override

# Run the agent in the current directory (your project):
codegenie
# ...or point it at another project:
codegenie --dir /path/to/project
# (equivalently: python -m codegenie.cli)

In-session commands: /help, /wishes, /reset, /exit.

🧞 The magic of 3 wishes (monetization)

Like a genie, Code Genie grants 3 free wishes per login user. A wish is consumed only on a successful feature build — i.e. a turn where the agent actually wrote a file or ran a command you approved. Pure read/answer turns (reading code, listing files, asking questions) are free and never burn a wish.

• After each build you'll see: ✨ Wish granted! You have N wishes remaining.
• After the 3rd, further requests are refused with an upgrade prompt: 🧞 You've used all 3 free wishes. Upgrade to Code Genie Pro: https://codegenie.dev/pro
• Check your balance any time with /wishes.
• Usage is tracked per OS login user and persisted to ~/.codegenie/wishes.json, so it survives restarts (a real gate, not a per-session reset).
• Pro tier: set CODEGENIE_PRO=1 to unlock unlimited wishes.

This is a real, enforced gate built for launch. The upgrade URL is a placeholder until a payment system is wired up — swap UPGRADE_URL in codegenie/wishes.py when you have a checkout page.

How it works (all under the codegenie/ package)

• codegenie/tools.py — the agent's tools (read_file, list_dir, write_file, run_command), sandboxed to the working directory.
• codegenie/llm_client.py — chat_with_tools() speaks OpenAI-compatible function calling (Groq / OpenRouter).
• codegenie/cli_agent.py — the agent loop: send messages + tool schemas, execute requested tool calls, feed results back until a final answer.
• codegenie/cli.py — the interactive REPL, which prompts you before any file write or shell command.

Note: the agent loop uses OpenAI-compatible tool calling, so set LLM_PROVIDER=groq or openrouter. Gemini and none are not supported for the agent (they remain available for the web app's diagnosis fallback).

Production behavior (no surprises)

• Rate limits: free-tier providers (especially Groq) return HTTP 429 under load. The agent automatically retries with exponential backoff (honouring Retry-After), then reports a clear message instead of crashing. Tune with LLM_MAX_RETRIES.
• Secrets: your API key is sent only in the Authorization header and is never written to disk or included in any error message.
• Long sessions: if the conversation outgrows the model's context window the provider returns a 400; the agent tells you to /reset. (A v2 improvement is automatic history trimming.)
• Confirmation: every write_file and run_command prompts for y/N before running. There is no auto-approve mode yet — by design, for a safe first release.
• Sandbox: file tools are restricted to the working directory (path-traversal attempts are refused). run_command runs real shell commands in that directory, so only point the agent at projects you trust.

Publishing it (single-command install for everyone) See DEPLOY.md for publishing to PyPI so anyone can run:

pip install codegenie-agent
codegenie

Quick start (local) — web diagnostic app

cd codegenie-app
python3 -m venv venv && source venv/bin/activate
pip install -r requirements.txt

cp .env.example .env   # edit if you want to set an API key or LLM provider

pip install -e ".[web]"   # install the optional web-app dependencies
uvicorn codegenie.main:app --reload --port 8000

Open http://localhost:8000 — the frontend is served at the root.

Run the real tests

python test_core.py

This proves the rule engine matches known issues correctly and degrades confidence appropriately when dependency versions don't confirm a log-pattern match — no mocking, real fixture projects.

Enabling the LLM fallback (optional, still mostly free)

By default LLM_PROVIDER=none — the app runs at $0 forever, just with lower coverage on novel/project-specific bugs (it'll honestly say "couldn't diagnose confidently" instead of guessing).

To add free-tier coverage for the long tail:

# .env
LLM_PROVIDER=groq
LLM_API_KEY=your_groq_key_here
LLM_MODEL=llama-3.1-8b-instant

Groq, Gemini Flash, and OpenRouter's free-tier open models all work with the same plug in backend/llm_client.py — swap the provider name and key.

Enabling sandbox verification (Wish 3)

Requires Docker installed on whatever host runs this (a $5-6/mo VPS like Hetzner/Contabo is enough to start). No paid sandbox service required. If Docker isn't found, Wish 3 returns a clear "skipped" message instead of crashing — it never blocks Wishes 1 and 2.

⚠️ This uses plain Docker with hardening flags (--network none, memory/CPU caps, non-root, timeout), not microVMs. That's a real, intentional tradeoff for a $0-cost MVP — don't expose this directly to hostile public internet traffic at scale without upgrading to gVisor or a dedicated low-privilege host first.

Growing the known-issues database

data/known_issues.json has 10 starter rules. This is genuinely the highest-leverage thing you can spend time on — every new rule you add is permanent, free diagnostic coverage that never needs an LLM call. Format:

{
  "id": "KI011",
  "name": "short label",
  "tech": "node | python | docker | any",
  "log_patterns": ["regex1", "regex2"],
  "dependency_check": { "package": "x", "version_range": ">=1.0,<2.0" },  // optional
  "confidence": 85,
  "root_cause": "...",
  "fix_commands": ["..."],
  "prevention_tip": "..."
}

Deploying for real (next steps, in order)

1. Set CODEGENIE_API_KEY and put this behind real auth before any public exposure.
2. Move sessions from the in-memory dict in storage.py to Redis or Postgres.
3. Move analysis from synchronous request handling to a background job queue (Celery/RQ) once you have concurrent users.
4. Add the malware-scan step mentioned in your original test plan (ClamAV is free and self-hostable) before processing uploaded ZIPs in production.
5. Expand known_issues.json based on real beta-user failures — track which rule IDs fire most, and which logs hit "no match," to prioritize what to add next.