{"id":49833910,"url":"https://github.com/mrdushidush/claudette","last_synced_at":"2026-06-16T21:00:28.642Z","repository":{"id":353214372,"uuid":"1214300796","full_name":"mrdushidush/claudette","owner":"mrdushidush","description":"Your AI never leaves your laptop. Claudette is a personal AI assistant and coding agent that runs entirely on local hardware - REPL, fullscreen TUI, one-shot CLI, and a Telegram bot, all driving one local model through Ollama or LM Studio. No cloud brain. No API key. No subscription. No telemetry. One Rust binary. ","archived":false,"fork":false,"pushed_at":"2026-06-07T15:03:23.000Z","size":2639,"stargazers_count":5,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-07T15:03:34.912Z","etag":null,"topics":["agent","ai-agent","cli","coding-agent","developer-tools","llm","lm-studio","local-ai","local-first","local-llm","ollama","personal-assistant","privacy","qwen","rust","telegram-bot","tool-calling","tui","voice-assistant","whisper"],"latest_commit_sha":null,"homepage":"https://github.com/mrdushidush/claudette","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mrdushidush.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE-APACHE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-18T11:39:39.000Z","updated_at":"2026-06-07T15:03:26.000Z","dependencies_parsed_at":null,"dependency_job_id":"d32ac88e-7eb1-4f6f-ad7c-993da714efab","html_url":"https://github.com/mrdushidush/claudette","commit_stats":null,"previous_names":["mrdushidush/claudette"],"tags_count":31,"template":false,"template_full_name":null,"purl":"pkg:github/mrdushidush/claudette","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mrdushidush%2Fclaudette","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mrdushidush%2Fclaudette/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mrdushidush%2Fclaudette/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mrdushidush%2Fclaudette/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mrdushidush","download_url":"https://codeload.github.com/mrdushidush/claudette/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mrdushidush%2Fclaudette/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34423218,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-16T02:00:06.860Z","response_time":126,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent","ai-agent","cli","coding-agent","developer-tools","llm","lm-studio","local-ai","local-first","local-llm","ollama","personal-assistant","privacy","qwen","rust","telegram-bot","tool-calling","tui","voice-assistant","whisper"],"created_at":"2026-05-13T23:03:31.965Z","updated_at":"2026-06-16T21:00:28.595Z","avatar_url":"https://github.com/mrdushidush.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Claudette\n\n**An air-gapped AI coding agent that runs entirely on your own hardware.** One Rust binary, one local model through [Ollama](https://ollama.com) or [LM Studio](https://lmstudio.ai/), no cloud. Run it with `--offline` and it physically can't reach the network - your code and your prompts can't leave the machine. (It's a capable personal assistant too - notes, calendar, Telegram voice - but the headline is a coding agent you can run on a no-cloud box.)\n\n[![Crates.io](https://img.shields.io/crates/v/claudette.svg)](https://crates.io/crates/claudette)\n[![CI](https://github.com/mrdushidush/claudette/actions/workflows/ci.yml/badge.svg)](https://github.com/mrdushidush/claudette/actions/workflows/ci.yml)\n[![License: MIT OR Apache-2.0](https://img.shields.io/badge/license-MIT%20OR%20Apache--2.0-blue.svg)](#license)\n[![Air-gap: enforced](https://img.shields.io/badge/air--gap-enforced-success.svg)](#-air-gapped-and-enforced)\n\n![Claudette editing her own repo, clearing the cargo gate, and opening a real pull request - all on a local model, offline](docs/images/claudette-ships-pr.png)\n\n*Claudette in her own repo on a local 35B model - editing the code, clearing the full `cargo fmt` / `clippy` / `cargo test` gate, then opening a genuine pull request. No cloud; nothing leaves the machine.*\n\n---\n\n## 🔒 Air-gapped, and enforced\n\n`claudette --offline` (or `CLAUDETTE_OFFLINE=1`) hard-blocks every outbound call except your local model server and loopback. Web search, GitHub, Telegram, Google, even `git push` all refuse with a clear `blocked by offline mode` error. Two guard layers cover in-process HTTP *and* subprocesses (`git`, `gh`, TTS), and an integration test drives every networked tool to prove each one refuses - the air-gap is tested, not just documented. `claudette --offline --doctor` prints the exact allow-list.\n\nThere's no cloud-brain code in the binary to begin with, so there's no \"private mode\" to switch on - there is no other mode. Nothing is written outside `~/.claudette/` without a prompt. Full inventory of every place a byte could leave: [PRIVACY.md](PRIVACY.md).\n\n---\n\n## Install\n\n```sh\ncurl -fsSL https://raw.githubusercontent.com/mrdushidush/claudette/main/install.sh | sh   # Linux / macOS\niwr -useb https://raw.githubusercontent.com/mrdushidush/claudette/main/install.ps1 | iex  # Windows\ncargo install claudette                                                                    # Rust\n```\n\n```sh\nollama pull qwen3.5:4b        # 3.4 GB model, one-time download\nclaudette \"what time is it?\"\n```\n\nPrefer not to pipe curl into a shell? Grab a [prebuilt release](https://github.com/mrdushidush/claudette/releases/latest) - each ships a SHA256. No GPU? The 4B model runs on plain CPU. Full setup and first flows → [docs/quickstart.md](docs/quickstart.md).\n\n---\n\n## What it does\n\n| Mode | Command | For |\n|------|---------|-----|\n| **REPL** | `claudette` | Conversational shell; autosaves every turn |\n| **One-shot** | `claudette \"...\"` | Print a reply and exit; pipe-friendly |\n| **TUI** | `claudette --tui` | Fullscreen UI, 5 tabs, live tool panel |\n| **Telegram** | `claudette --telegram` | Voice-capable chat from your phone |\n\n- **80+ tools across 22 opt-in groups.** The model turns a group on (`enable_tools(\"git\")`) only when it needs it, so the base schema stays ~200 tokens however many tools exist. Point Claudette at a repo and the coding core - files, search, tests - is pre-enabled.\n- **Forge - an autonomous code pipeline.** `claudette --forge \"\u003ctask\u003e\"` runs Planner → Coder → Verifier → fix-loop → Submitter. The Verifier actually builds and runs the tests each round (`cargo`, `go`, `pytest`, `npm`), so a diff that doesn't compile or breaks a test can't pass - and no PR opens until you approve the plan and the full diff. → [docs/forge.md](docs/forge.md)\n- **Brownfield missions.** `mission_start(\"owner/repo\")` clones a repo, routes file ops into it, and `mission_submit` branches, commits, pushes, and opens the PR - one tool chain.\n- **Also a personal assistant.** Notes, todos, calendar, Gmail, weather, markets, web search, and a Telegram bot with voice in (Whisper) and out (edge-tts, English or Hebrew).\n- **Tiered brain, recall, vision.** Auto-escalates the 4B model to 9B only on real stuck signals; `/recall` searches every past session through a local embedding index; image attachments work when the loaded model is multimodal.\n- **Per-tool permissions.** Read-only and workspace-write tools auto-allow; `bash`, `edit_file`, and `git push` prompt `[y/N]` every time.\n\n### 🔁 She helps build herself\n\nClaudette is developed *with* Claudette. She runs her own Forge pipeline against this repo, clears the real build-and-test gate (`cargo fmt` / `clippy -D warnings` / `cargo test`) before anything is pushed, and opens genuine pull requests under her own git identity - so she shows up as a [listed contributor on this repo](https://github.com/mrdushidush/claudette/graphs/contributors). A human reviews and merges every change; nothing lands on `main` unattended. Features shipped this way include `repo_map` C#/Java support, `read_file tail=N`, `grep_search count_only` / `case_sensitive`, and `git_status filter`.\n\n![Claudette previewing a colored diff and running the cargo gate before pushing](docs/images/claudette-diff-gate.png)\n\n*Each edit is previewed as a colored diff at the `[y/N]` gate; she then runs `cargo fmt` / `clippy` / `cargo test` and pushes only when they pass.*\n\n---\n\n## 🏅 Which model should I run?\n\nEvery candidate runs the same objective 50-task battery - 11 languages × 12 task types - through Claudette's real tool loop, then an automated verifier checks the result (build/test passes, file is correct, ground-truth tokens appear). No model grades itself. `claudette --doctor` reads your VRAM and names the model that fits your GPU, with the load command.\n\n| Model | VRAM | Pass @ 50 | Best for |\n|-------|------|-----------|----------|\n| **`qwen3.6-35b-a3b`** (q3_k_xl) | 16 GB | **92%** | Best accuracy - the default |\n| `qwen3.5-4b` | **8 GB** | 90% | Best value - runs almost anywhere |\n| `gpt-oss-20b` | 13 GB | 86% | Fastest |\n\nFull table, methodology, and the reusable harness → [MODEL-COMPARISON.md](runs/eval-2026-05-29/battery/MODEL-COMPARISON.md). Benching a model we haven't covered is the single most useful way to contribute - no Rust required.\n\nRuns on 8 GB VRAM or plain CPU; 16 GB for the 35B brain. Footprint details → [docs/hardware.md](docs/hardware.md).\n\n---\n\n## Docs\n\n- [docs/show-me.md](docs/show-me.md) - **start here:** plain-English example prompts\n- [docs/quickstart.md](docs/quickstart.md) - full setup, common flows, tokens\n- [docs/configuration.md](docs/configuration.md) - every env var and token fallback\n- [docs/power-user.md](docs/power-user.md) - LM Studio recipe, brain pinning, forge knobs\n- [docs/hardware.md](docs/hardware.md) - VRAM/RAM/disk by preset, CPU-only mode\n- [docs/usage.md](docs/usage.md) - CLI flags, slash commands, Telegram commands\n- [docs/architecture.md](docs/architecture.md) - module layout, tool-group + Codet contracts, storage layout\n- [docs/forge.md](docs/forge.md) - forge pipeline, brownfield missions, `models.toml`\n- [docs/comparison.md](docs/comparison.md) - side-by-side vs. opencode / Aider / OpenHands / Cline / Continue\n- [docs/deploy.md](docs/deploy.md) - Pi / VPS / home-server via docker-compose\n- [editor/vscode/](editor/vscode/README.md) - VS Code extension\n- [PRIVACY.md](PRIVACY.md) - every place data can leave, and the conditions for each\n\n---\n\n## Build from source\n\n```bash\ngit clone https://github.com/mrdushidush/claudette \u0026\u0026 cd claudette\ncargo build --release -p claudette\n```\n\n1,000+ tests, green on CI. Before committing: `cargo fmt --all \u0026\u0026 cargo clippy --all-targets --no-deps -- -D warnings \u0026\u0026 cargo test --lib`.\n\n---\n\n## Contributing\n\nBugs and PRs welcome - see [CONTRIBUTING.md](CONTRIBUTING.md). Conventional Commits (`feat:`, `fix:`, `docs:`, …). Security issues go through the private advisory flow in [SECURITY.md](SECURITY.md), not a public issue. Contributions are dual-licensed MIT OR Apache-2.0.\n\n## License\n\nDual-licensed under **MIT** ([LICENSE-MIT](LICENSE-MIT)) **OR Apache-2.0** ([LICENSE-APACHE](LICENSE-APACHE)), at your option. The Apache option adds a patent grant; neither grants a trademark.\n\n© 2026 [mrdushidush](https://github.com/mrdushidush).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmrdushidush%2Fclaudette","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmrdushidush%2Fclaudette","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmrdushidush%2Fclaudette/lists"}