BetterCode

Local-first desktop AI coding workspace.

BetterCode runs on your machine, keeps workspace state local, routes tasks across coding runtimes, and gives you a desktop UI for editing, review, git workflows, generated files, and long-running CLI sessions.

---

Installation

python -m venv .venv
source .venv/bin/activate
pip install -e .

Run:

bettercode

Development mode:

bettercode --dev

Tip

BetterCode is a desktop app. You need PyQt6 and PyQt6-WebEngine available in the active Python environment.

Desktop packaging plan:

pip install -e .[packaging]
bettercode-package --dry-run

What BetterCode Does

• Local desktop shell with a native app window
• Embedded local FastAPI server on 127.0.0.1
• Project-based chat history and workspace state in local SQLite
• Auto Model Select with a local selector model
• Support for local Codex, Claude, and Gemini CLIs
• In-app git actions, code review flow, and project run commands
• Generated file handling outside the repo when the task calls for artifacts like PDFs or CSVs

How It Works

Desktop app (PyQt6)
        |
        v
Embedded web UI
        |
        v
Local FastAPI app
        |
        +--> Workspace state + chat history (SQLite)
        +--> Auto Model Select / selector runtime
        +--> Codex CLI
        +--> Claude CLI
        +--> Gemini CLI

BetterCode does not depend on a hosted BetterCode backend. The app runs locally and keeps its own state in ~/.bettercode unless you override BETTERCODE_HOME.

Requirements

• Python >=3.10
• PyQt6
• PyQt6-WebEngine
• One or more installed coding runtimes:
  • codex
  • claude
  • gemini
• Ollama for Auto Model Select

Auto Model Select

BetterCode can pre-process a request locally and choose a runtime/model for the job.

By default it expects:

ollama serve
ollama pull qwen2.5-coder:1.5b

If you do not want automatic routing, you can still choose a model directly in the app.

Features

Projects

• Multiple local projects
• Per-project chat history
• Saved context between turns
• Generated files attached to each project

Chat

• Streaming CLI passthrough while a runtime is working
• Model selection and selection reasoning
• Suggested replies
• Completion notifications when BetterCode is not the active window

Code Review

• Review page with changed files and recent files
• Select files before running review
• Primary and optional secondary reviewer
• Findings can be pushed back into chat for implementation

Git

• File selection
• Stage / unstage actions
• Commit and push from inside the app

Generated Files

BetterCode separates generated outputs from real project files.

• Real repo files stay in the project
• Generated outputs can be staged in .bettercode-generated
• BetterCode moves those outputs into:

~/.bettercode/generated-files/workspace-<id>/

• Generated files are visible per project in the sidebar
• Clicking a generated file opens it with the system default app

Configuration

Environment variables:

• BETTERCODE_HOME
• BETTERCODE_DEV
• OLLAMA_HOST
• BETTERCODE_SELECTOR_MODEL
• BETTERCODE_SELECTOR_KEEP_ALIVE
• BETTERCODE_MAX_COST_TIER
• BETTERCODE_PROXY_API_BASE
• BETTERCODE_PROXY_TOKEN

Local Data

• App state: ~/.bettercode/state.db
• Generated files: ~/.bettercode/generated-files/
• API keys: stored through keyring

Troubleshooting

Linux

Qt WebEngine may need:

sudo apt-get install libxcb-cursor0

Auto Model Select Is Not Working

Make sure Ollama is installed, running, and has the selector model:

ollama serve
ollama pull qwen2.5-coder:1.5b

Desktop App Will Not Launch

Make sure the current Python environment includes:

pip install PyQt6 PyQt6-WebEngine

Contributing

This repo is still moving fast and the UI is evolving quickly. If you want to work on it, start by reading the code in:

• bettercode/web/api.py
• bettercode/web/static/app.js
• bettercode/web/desktop.py

License

MIT