Codely

A model-agnostic coding agent — the Claude Code concept, without the lock-in. Bring your own model: Anthropic, OpenAI, OpenRouter, DeepSeek, local Ollama, or anything OpenAI-compatible. BYOK by default; no vendor enforcement.

The full Claude Code teardown that informed this build is in claude-code-research.md.

Features

• Any model, one UI — switch providers/models mid-session from the picker.
• Streaming agent loop with tools: read_file, list_files, write_file, edit_file, run_bash, spawn_subagent.
• Permission modes (cycle with Shift+Tab): Ask · Auto-edit (auto-approve edits) · Plan (read-only, proposes a plan) · Bypass.
• Diff/command approval — sensitive actions prompt with a Rust-rendered diff or the exact command; "Always allow" remembers per tool.
• Sessions — auto-saved, listed in the sidebar, resume any time.
• Rewind — every turn is a checkpoint; one click restores files and conversation.
• Sub-agents — delegate read-only investigation to a nested agent to keep context lean.
• MCP — connect stdio MCP servers; their tools join the agent's toolset.

Architecture

┌─────────────────────────┐   WebSocket    ┌──────────────────────────────┐
│  Electron + React (TS)   │ ◄───ws://───►  │  Python backend (FastAPI)    │
│  frontend/               │   :8765/ws     │  backend/codely_backend/     │
│  • chat + markdown       │                │  • agent loop + modes        │
│  • session sidebar       │                │  • provider abstraction      │
│  • diff / permission UI  │                │  • tools · sessions · MCP    │
│  • rewind                │                │            │                 │
└─────────────────────────┘                │            ▼ PyO3            │
                                            │  ┌────────────────────────┐  │
                                            │  │ Rust core (codely_core)│  │
                                            │  │ core/  token · walk    │  │
                                            │  │        unified diff    │  │
                                            │  └────────────────────────┘  │
                                            └──────────────────────────────┘

• core/ — Rust → Python extension codely_core via PyO3 + maturin (token estimation, gitignore-aware repo walk, diff rendering).
• backend/ — Python FastAPI engine: a provider abstraction streams normalized events from any model (Anthropic Messages API or OpenAI-compatible /chat/completions); agent loop with permission gating, session persistence, checkpoints, sub-agents, and an MCP client; a WebSocket streams everything to the UI.
• frontend/ — Electron + React + Vite desktop app over a local WebSocket.

Prerequisites

Python ≥ 3.10 + uv · Rust (rustup) · Node ≥ 20 + npm.

Setup & run

make setup          # build Rust core + backend venv, install frontend deps
cp .env.example .env   # add provider keys (or just run Ollama locally)
make dev            # launches backend + Vite + Electron together

Or piecemeal:

make backend                       # backend only (127.0.0.1:8765)
cd frontend && npm run dev:renderer   # renderer in a browser (http://localhost:5173)
make test                          # backend test suite (21 tests)
make build                         # type-check + build the renderer

Only models whose provider has a usable key/endpoint are selectable. Ollama needs no key — just have it running on localhost:11434.

Configuration

• Providers/models — defaults in backend/codely_backend/config.py; extend without code via ./.codely/config.json or ~/.codely/config.json (see examples/config.json).
• MCP servers — ./.codely/mcp.json or ~/.codely/mcp.json (see examples/mcp.json).
• Sessions persist to ~/.codely/sessions/ (override with CODELY_HOME).

Package as a desktop app

make package    # → frontend/release/Codely-<ver>-arm64.dmg (+ .zip)

This freezes the Python backend (with the Rust core) into a standalone binary via PyInstaller, builds the renderer, and bundles both into a real macOS .app with electron-builder — no Python/Node needed to run it. The app auto-spawns the bundled backend; add your API key in Settings → Providers & keys on first launch.

Builds are unsigned (identity: null), so first launch needs right-click → Open (or xattr -dr com.apple.quarantine Codely.app). Add an Apple Developer identity to build.mac in frontend/package.json to ship signed/notarized.

Auth note (by design)

Codely uses your own API keys (or local models). It deliberately does not reuse Claude Pro/Max subscription OAuth — that violates Anthropic's terms. OpenAI (ChatGPT/Codex) and Google (Gemini) subscription auth are friendlier and are candidates for a future opt-in login; see the research doc.

Status

Working app: Rust core ✓, Anthropic + OpenAI-compatible providers ✓, streaming agent loop with tools + 4 permission modes ✓, diff approval ✓, session persistence + resume ✓, checkpoints/rewind ✓, sub-agents ✓, MCP stdio client ✓, 21 passing backend tests ✓, Electron UI (markdown, sidebar, rewind) ✓, CI ✓.

Roadmap: packaged binaries (bundle the backend via PyInstaller + electron-builder), remote/HTTP MCP transport, plan-mode plan rendering, model usage cost tracking.