What is Code Turtle?

Code Turtle (codeturtle) is an npm-distributed CLI/TUI that reviews GitHub PRs and GitLab MRs with any OpenAI-compatible LLM — cloud or local. There is no server and no webhooks: reviews run entirely on the user's machine, triggered by pasting a PR link in the TUI or by polling watched repos.

It's not another SaaS bot. It's a single binary you install once, point at the model of your choice, and let it watch your repos. Findings land as inline comments plus a single summary review on the PR, deduped across runs so re-reviews only post what changed.

Why Code Turtle?

| Aspect | SaaS code-review bots | Code Turtle | | ------------------- | ------------------------- | ------------------------------------------------------- | | Where it runs | Vendor cloud | Your machine — local-first | | Where code goes | Uploaded to a third party | Never leaves your laptop | | Model choice | Locked to vendor's model | Any OpenAI-compatible endpoint (cloud or local) | | Forge support | GitHub only, usually | GitHub & GitLab, first-class | | Auth | OAuth + webhook install | OAuth / gh CLI / PAT / GitHub App / GitLab token | | Posting backend | Vendor proxy | GitHub's official MCP server (default) or REST fallback | | Offline capable | No | Yes — fully usable with Ollama or LM Studio | | Custom review rules | Vendor UI | Drop-in .codeturtle.yml + global norm packs | | Cost model | Per-seat subscription | Pay only for the model calls you make |

Key Features

• Multi-provider out of the box — Gemini, Claude, OpenAI, OpenRouter, Groq, Ollama, LM Studio, or any custom OpenAI-compatible endpoint. Local servers get live model detection.
• GitHub + GitLab, first-class — GitHub I/O goes through the official GitHub remote MCP server; GitLab I/O is REST v4. Both have soft-fail and lock-aware pipelines.
• Smart context, not just diffs — pulls changed files, their imports, callers, and tests from the repo at the head commit, ranked and budgeted.
• One native review per run — inline comments + a single summary review (create → add → submit pending), with labels and dedup via hidden HTML markers.
• Idempotent re-reviews — pushes only post new findings; markers carry a ±3 line tolerance for LLM anchor jitter.
• Idempotent push reviews — the same marker scheme works for commit comments on plain branch pushes, deduped per head commit.
• Custom norms, layered — built-in defaults ← your personal global norms ← the repo's .codeturtle.yml (project wins). Package reusable rule sets as packs (.yml) or, for power users, code transforms (.mjs); repos opt into packs by name via extends. Reviewer/key overrides and code execution from repo files are ignored for security. See the Custom Norms Guide.
• GitHub App identity — reviews can post as <app-slug>[bot] (RS256 JWT → installation token, all on your machine). Still no server.
• Watch + dashboard — pick repos, get a live TUI: open/closed PR tabs, auto-watch, events feed, manual refresh (R). Open posted reviews to browse findings, toggle summaries (S), filter by file (F), and switch focus (Tab) to the code context pane to scroll up/down the codebase (↓/↑ or j/k). Watching runs inside the TUI session (a detached background daemon is on the roadmap).
• Strict reviewer validation — hostile LLM output is filtered, not trusted; findings below the configured confidence threshold are dropped before posting.

Installation

npm install -g code-turtle

Or run without installing:

npx code-turtle

Requires Node.js ≥ 22.12 (the floor set by commander@15 and ink@7).

Quick Start

codeturtle          # opens the TUI — first run walks you through setup

First run walks you through three steps:

1. Pick a provider & model — Gemini, Claude, OpenAI, OpenRouter, Groq, Ollama (local), LM Studio (local), or any custom OpenAI-compatible endpoint. Local servers get live model detection. The model must be a chat / instruct LLM (text in → text out) — reviews go through the chat-completions API. Avoid rerank, embedding, vision-only, or image/audio-generation models; they fail with 404 / no endpoints. Use the most capable model you can: gemini-2.5-flash is a reliable default; small models miss subtle cross-line bugs.
2. Connect a forge (once) — one menu: sign in with GitHub (OAuth device flow, set GITHUB_CLIENT_ID), use your gh CLI session, paste a GitHub PAT, or paste a GitLab token. One is enough; you can optionally connect another afterwards.
3. Pick repos to watch — github:owner/repo gitlab:12345

Scripting

The bare command opens the TUI. For scripting there are three subcommands — review, status, and reset:

codeturtle review https://github.com/owner/repo/pull/42      # one-off review (paste a link)
codeturtle review --forge github --repo owner/repo --pr 42   # …or pass flags
codeturtle status                                            # connection + model status
codeturtle reset                                             # wipe local config (-y to skip prompt)

A background daemon (start / logs / stop) is on the roadmap. Today, background watching runs inside the TUI session.

How it reviews

• Smart context: not just the diff — pulls changed files, their imports, callers, and tests from the repo at the head commit
• GitHub via MCP: all GitHub I/O goes through GitHub's official MCP server; findings post as one native PR review (inline comments + summary)
• Custom norms, layered: defaults ← your global norms & packs ← the repo's .codeturtle.yml (project wins); package rules as .yml packs or .mjs transforms (reviewer/key overrides and repo-triggered code are ignored for security) — see the Custom Norms Guide
• Idempotent: re-reviews after a push only post new findings (±3 line tolerance for anchor jitter)

Configuration

Everything lives in ~/.codeturtle/ — credentials.json, config.json, watcher.log. Env vars (GITHUB_TOKEN, GITLAB_TOKEN, REVIEWER_API_KEY, REVIEWER_BASE_URL, REVIEWER_MODEL) override the store.

Files in ~/.codeturtle/ are written with chmod 600. Secrets are never logged, never echoed in errors, and never written outside that directory.

Architecture

The data flow is the same whether the trigger is a pasted PR link, the CLI, or the polling watcher — everything funnels through one entrypoint.

  cli / tui  ──►  pipeline.runReview(job)  ──►  forge client  (GitHub MCP / GitLab REST)
                          │                            │
                          │                            ├─ getMr / getDiffs / getFile
                          ▼                            │
                      bundler  ◄───────────────────────┘   (changed files + imports + callers + tests)
                          │
                          ▼
                      reviewer  ──►  LLM (OpenAI-compatible)  ──►  strict-validated findings
                          │
                          ▼
                       poster   ──►  inline comments + one summary review + labels

Layered norms resolve as: defaults ← global config & packs ← target repo's .codeturtle.yml (project wins on conflict). Repo files can never redirect the reviewer or set keys — agent and key_ref are stripped before merge.

Project Facts

• Language: TypeScript (strict), ESM only, Node ≥ 22.12
• TUI: React + Ink
• GitHub I/O: official GitHub remote MCP server (default) — REST fallback available
• GitLab I/O: REST v4
• LLM: the openai SDK pointed at any compatible base URL
• Build: tsup → dist/cli.js (single bin)
• Tests: Vitest — specs co-located in src/**/__tests__/, invariants locked in invariants.test.ts, coverage enforced in CI

Documentation

Full developer docs live in docs/ — architecture, a per-module engine reference, the TUI components, configuration, and the hard invariants. Start at docs/README.md.

| # | Doc | What you'll learn | | --- | ------------------------------------------------ | --------------------------------------------------------------------- | | 1 | Getting Started | Install, build, run, and do your first review | | 2 | Architecture | The big picture: layers, modules, and the review data flow | | 3 | Engine Reference | Every module in src/engine/ — what it does and its public surface | | 4 | TUI Reference | The React + Ink components in src/tui/ | | 5 | Configuration | ~/.codeturtle store, env vars, and per-repo .codeturtle.yml norms | | 6 | Hard Invariants | The seven rules you must not break — security, idempotency, locking | | 7 | Custom Norms Guide | Build your own review rules and norm packs | | 8 | Glossary | Domain terms: forge, norms, finding, context bundle, marker |

Contributing

Contributions are welcome! Please check out CONTRIBUTING.md and our Code of Conduct for guidelines on how to get started.

Quick local test — build and link to test your changes as a global command:

npm run build && npm link
codeturtle status   # now uses your local build
npm unlink -g code-turtle   # undo when done

See CONTRIBUTING.md and docs/getting-started.md for full details.

Good first contributions:

• Adding a new LLM provider preset in src/engine/providers.ts
• Contributing an example norm pack or transform to the Custom Norms Guide
• Improving TUI key hints or status badges
• Writing missing tests in src/**/__tests__/
• Documentation fixes

Project Status

| Version | Status | Description | | ---------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | v2.2.1 | Stable | Reviewer no longer crashes when an OpenAI-compatible endpoint returns a 200 body without a choices array (e.g. OpenRouter free tier under rate limiting) — the PR stays clean instead of failing. | | v2.2.0 | Stable | Added code context viewport focus and scrolling: use Tab to switch focus to the code pane, and up/down arrows (or j/k keys) to scroll up and down the codebase with a green indicator pointing to the focused line. | | v2.1.1 | Stable | Reviewer now catches deletion-induced bugs (a removed declaration still referenced); clean reviews no longer fail when label perms are missing; explicit re-reviews can force past a stale lock. | | v2.1.0 | Stable | Layered custom norms — personal global norms plus reusable packs (.yml) and code transforms (.mjs), with extends for per-repo opt-in. GitHub OAuth/App sign-in, push reviews, Vitest suite + invariant tests, CI + OIDC release. | | v2.0.0 | Stable | TypeScript rewrite — CLI/TUI reviewing GitHub PRs and GitLab MRs with any OpenAI-compatible model. Python implementation removed. Multi-pass review, provider key validation, watcher and lock failsafes. | | Unreleased | Planned | Background daemon (start / logs / stop) · per-language norm packs auto-selected by file type · TUI manager for installed packs. |

See CHANGELOG.md for the full history.

License

This project is licensed under the MIT License — see the LICENSE file for details.