collie

KO | EN

gitlite — search

#kotlin #ruby #containers #gpt #generative-ai #cross-platform #api #claude-code #computer-vision #editor

(★ 9)

A local-first coding agent that proves its own work — one cross-platform Python codebase, one-click Windows installer.

File Explorer

ZIP Download

- - webwork.md
- - ci.yml
  - docs.yml
  - release.yml
- collie-logo.svg
- collie.svg
- - graded.json
- bench_sync.py
- codesearch_eval.py
- exec_select.py
- locomo_e2e.py
- locomo_eval.py
- longmemeval_eval.py
- multirun_eval.py
- paired_eval.py
- polyglot_eval.py
- pro_eval.py
- redo_failed.py
- ultra_select.py
- htap.json
- ids16.txt
- ids50.txt
- ids_contested3.txt
- ids_django_contested.txt
- ids_fresh12.txt
- ids_holdout12.txt
- ids_lite12.txt
- ids_one.txt
- retrieval_eval.json
- tap_test.json
- cli.md
- desktop.md
- index.md
- install.md
- mission.md
- PLATFORMS.md
- presence.md
- privacy.md
- providers.md
- quickstart.md
- signing.md
- - background.js
  - icon128.png
  - icon16.png
  - icon48.png
  - manifest.json
  - popup.html
  - popup.js
  - shadow.js
- - opencode.jsonc
  - pi-oauth-proxy.js
- - build.ps1
  - collie.ico
  - Microsoft.Web.WebView2.Core.dll
  - Microsoft.Web.WebView2.WinForms.dll
  - Program.cs
  - README.md
  - stop-wallpaper.ps1
  - WebView2Loader.dll
- - ambient.html
  - collie-icon-512.png
  - index.html
  - logo.svg
  - map.html
  - mobile.html
  - remote.html
  - three.min.js
  - wallpaper.html
- __init__.py
- acp_agent.py
- actions.py
- adapters.py
- apitap.py
- approve.py
- audit.py
- avatar.py
- browserapple.py
- browserbridge.py
- capabilities.py
- catalog.py
- checkpoint.py
- checkpoints.py
- cli.py
- codeindex.py
- codemap.py
- codex_oauth.py
- compare.py
- context.py
- costs.py
- dashboard.py
- delegate.py
- desktop.py
- desktop_mac.py
- distill.py
- dogmail.py
- e2e.py
- embeddings.py
- everyday.py
- gate.py
- inbox.py
- jobs.py
- jobsweb.py
- judge.py
- leash.py
- lint.py
- loop.py
- mandate.py
- mcpclient.py
- mem_import.py
- memory.py
- menubar_mac.py
- mission.py
- missioncmd.py
- missionweb.py
- native.py
- native_mac.py
- nowplaying_mac.py
- oauth_proxy.py
- observe.py
- overrides.py
- pack.py
- paircode.py
- personas.py
- plantool.py
- plat.py
- presence.py
- primitives.py
- progtool.py
- providers.py
- qr.py
- record.py
- recorder.py
- redact.py
- remote.py
- remote_identity.py
- research.py
- reval.py
- risk.py
- router.py
- scheduler.py
- scratch.py
- screenshot.py
- sessions.py
- settings.py
- skills.py
- slackbot.py
- slackexec.py
- slackguard.py
- swe.py
- swe_predict_one.py
- tools.py
- trust.py
- tui.py
- update.py
- verifier.py
- wallpaper.py
- webact.py
- webapp.py
- webedit.py
- webfetch.py
- websearch.py
- worktree.py
- wsclient.py
- - Abkhazian.isl
  - Afrikaans.isl
  - Albanian.isl
  - Asturian.isl
  - Azerbaijan.isl
  - Basque.isl
  - Belarusian.isl
  - Bengali.islu
  - Bosnian.isl
  - ChineseSimplified.isl
  - ChineseTraditional.isl
  - Croatian.isl
  - EnglishBritish.isl
  - Esperanto.isl
  - Estonian.isl
  - Ewe.isl
  - Farsi.isl
  - Galician.isl
  - Georgian.isl
  - Greek.isl
  - Hindi.islu
  - Icelandic.isl
  - Indonesian.isl
  - Kazakh.islu
  - Kurdish.isl
  - Latvian.isl
  - Ligurian.isl
  - Luxemburgish.isl
  - Macedonian.isl
  - Malaysian.isl
  - Marathi.islu
  - Mongolian.isl
  - Montenegrin.isl
  - Nepali.islu
  - NorwegianNynorsk.isl
  - Occitan.isl
  - Romanian.isl
  - ScottishGaelic.isl
  - SerbianCyrillic.isl
  - SerbianLatin.isl
  - Sinhala.islu
  - Tatar.isl
  - Urdu.isl
  - Uyghur.islu
  - Uzbek.isl
  - Valencian.isl
  - Vietnamese.isl
- - build-shell.ps1
  - collie-logo.png
  - fonts.css
  - installer.html
  - Launcher.cs
  - pack.ps1
  - Shell.cs
- brew_release.sh
- build.ps1
- build_mac.sh
- build_mac_payload.sh
- build_payload.ps1
- collie-wallpaper.iss
- collie.iss
- DEVELOPER_ID.md
- fetch_languages.py
- gen_langs.py
- gen_zhtw.py
- make_art.py
- README.md
- _avatar.js
- _identity_section.css
- _identity_section.html
- _preview.html
- _redirects
- avatar-tables.json
- collie-logo.png
- collie-logo.svg
- favicon.ico
- index.draft.html
- index.html
- README.md
- robots.txt
- sitemap.xml
- wrangler.toml
- E2E_DESIGN.md
- IOS_APP.md
- mail.wrangler.toml
- mail_worker.js
- README.md
- slack_presence.js
- worker.js
- wrangler.toml
- _util.py
- browser_ext_test.js
- browser_live_test.py
- browser_suite.py
- conftest.py
- e2e_chain.py
- gui_test.py
- mail_crossimpl_test.js
- mail_names_test.js
- nowplaying_ui_check.py
- nowplaying_web_check.py
- parallel_ui_check.py
- relay_pairing_test.js
- relay_presence_test.js
- relay_push_test.js
- render_test.js
- run_all.sh
- slack_presence_worker_test.js
- smoke_codex_oauth.py
- steer_ui_check.py
- surfaces_test.py
- test_actions.py
- test_app_port.py
- test_audit.py
- test_avatar.py
- test_browserbridge.py
- test_capabilities.py
- test_catalog.py
- test_cli_jobs.py
- test_cli_mission.py
- test_codex_oauth.py
- test_context.py
- test_core.py
- test_data_dir.py
- test_desktop.py
- test_desktopweb.py
- test_dogmail.py
- test_dogmail_wire.py
- test_e2e.py
- test_e2e_persist.py
- test_everyday.py
- test_gate.py
- test_gate_freshness.py
- test_inbox.py
- test_jobs.py
- test_jobsweb.py
- test_leash.py
- test_loop.py
- test_loop_gate.py
- test_mandate.py
- test_map_landing.py
- test_mcp_catalog.py
- test_mcp_confidential.py
- test_mirror_backlog.py
- test_mission.py
- test_missionweb.py
- test_model_pin.py
- test_multimodel.py
- test_no_console_flash.py
- test_notify.py
- test_observe.py
- test_output_encoding.py
- test_overrides.py
- test_pack_isolation.py
- test_pack_roster.py
- test_packaging_facts.py
- test_paircode.py
- test_pairprompt.py
- test_personas.py
- test_plat.py
- test_platform_purity.py
- test_playhere.py
- test_presence.py
- test_primitives.py
- test_provider_plugins.py
- test_providers.py
- test_qr.py
- test_relay_keepalive.py
- test_repo_discovery.py
- test_repos_deadline.py
- test_research.py
- test_risk.py
- test_router.py
- test_runs_registry.py
- test_scheduler.py
- test_settings_fallback.py
- test_slack_answer.py
- test_slack_guard.py
- test_slack_presence.py
- test_slack_setup.py
- test_slack_worker.py
- test_slackbot.py
- test_tools.py
- test_trust.py
- test_update.py
- test_verifier.py
- test_web_lan.py
- test_web_mission_api.py
- test_whoami.py
- test_worktree.py
- - collie.svg
  - galaxy.svg
  - icon.png
- .vscodeignore
- extension.js
- package.json
- README.md
.gitignore
CHANGELOG.md
HANDOFF.md
LICENSE
MANIFEST.in
mkdocs.yml
pyproject.toml
pytest.ini
README.md
run_compare.py
run_compare4.py
run_parallel.py
swe_run.py

# Use via CDN

jsDelivr

jsDelivr serves any public GitHub repository as a CDN with zero setup. Pick a version and a file to get a ready-to-paste link and snippet.

Version

File

Link

Example

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

<h1 align="center">Collie</h1>

A coding agent that lives on your computer — and can actually run it. 
 Local and private. It reaches your real environment — your logged-in browser, your desktop,
 your screen, your files — and proves its work by running it.

<a href="https://collie.run">collie.run</a> ·
 <code>collie -p "fix the bug"</code> ·
 <code>collie web</code>

---

Most coding agents live in a cloud tab or an editor pane and can only touch the files you hand
them. **Collie runs on your machine** — so it works the way you already do: it drives your *real*
logged-in browser, arranges your desktop, records your screen, takes tasks from your phone, and
edits your code. Nothing leaves your computer unless you send it there; there's no account and no
telemetry.

And it doesn't just *claim* to be done. When Collie fixes something it writes a reproduction that
must fail on the broken code, makes the smallest edit that flips it, and re-runs the assertion — a
run isn't "done," it's **verified ✓**.

## Why it's different

**It's local, and it reaches your real world.** A cloud agent can read a repo. Collie can open the
site in the browser you're already logged into, click through the actual flow, watch what happens on
your screen, and change the code — all on one machine, all under your control. That's a different
class of task: not "edit these files," but "get this working, end to end."

**The range is the proof.** Collie isn't a coding agent with a pile of unrelated features bolted on.
The breadth below — the desktop console, the browser control, the screen recorder, the phone remote —
is there because **Collie's coding agent built all of it.** The features *are* the benchmark: a
harness strong enough to ship its own desktop app and iOS companion is strong enough for your bug.

## The range

| | Capability | What it means |
|---|---|---|
| 🧠 | **Coding agent** | Semantic code navigation, syntax-gated edits, and a self-verifying repair loop — the core, covered below. |
| 🌐 | **Your real browser** | A Chrome extension lets Collie act *in your logged-in browser* — the real session, real cookies — so it can operate sites, not just scrape them. Every action is a fenced, CSRF-checked localhost call. |
| 🖥️ | **Living desktop** | `collie web` powers an interactive ambient wallpaper: clock, weather, an app dock, projects, a music player (real audio + synced karaoke lyrics), and a command bar — all agent-manageable via one JSON config. When Collie is working, the wallpaper becomes a live star-map of your code. |
| 🎬 | **Screen recorder** | `collie record` captures screen + camera + mic (Windows and macOS) — a built-in way to demo or document a run. |
| 📱 | **Phone remote** | Pair once by scanning a code; then tail runs and start new ones from your phone — on the same Wi-Fi (`--lan`) or anywhere through a relay (`--remote`), with the companion iOS app. |
| 🔌 | **Everywhere else** | Terminal, browser GUI, VS Code, and any ACP editor (Zed/JetBrains/neovim) — one harness, every surface. |

## Where it runs

Collie is **terminal-first** and reaches editors through an open protocol, not a bespoke extension:

| Surface | Command | Reaches |
|---|---|---|
| **Terminal** | `collie` (TUI) · `collie -p "task"` | anywhere — SSH, CI, tmux |
| **Browser GUI** | `collie web` | chat, the live verification gate, diffs, the star-map, the ambient desktop, settings |
| **iPhone** | `collie web --lan` (same Wi-Fi) or `--remote` (anywhere, via the relay) + the companion app | scan the pair code once, then run from the phone |
| **VS Code** | the bundled `vscode-collie` extension | Collie docked in a sidebar panel (manages its own server) |
| **Editors (ACP)** | `collie acp` | Zed · JetBrains · neovim · VS Code — one adapter, every [ACP](https://agentclientprotocol.com) editor |
| **Streaming / CI** | `collie run "task" --stream-json` | NDJSON events (tool · edit · repro-gate · receipt) |

## Install

**Windows — one click.** Download **`Collie-Setup.exe`** from the
[latest release](https://github.com/colliehq/collie/releases/latest) and double-click it. A small
app-style installer lays down a self-contained runtime (Python + Collie + semantic memory, nothing to
preinstall) and opens Collie in a native desktop window. On first launch you **pick a brain** — an
existing Claude, Codex, or Grok login is detected and connects in one click; or paste an API key.

**macOS / Linux — pip.** The core is stdlib-only, so the base install is tiny:

```bash
pip install -e ".[local,dev]"      # from a clone (PyPI publish is planned)
collie setup                       # optional deps, pre-download the memory model, pick a provider
collie                             # the terminal chat (TUI) opens
```

No account, no telemetry, and the core has **zero third-party dependencies** — `mock` and `ollama`
run without any key, and memory works out of the box on BM25 keyword recall.

Optional extras: `pip install ".[local,tui,search]"` — `local` (semantic memory: granite-107m via
onnxruntime, ~55MB, multilingual), `tui` (rich terminal chat), `search` (keyless web search), `acp`
(editor protocol), `browser` (Playwright — only for `collie browser-bridge --browser`, a managed
Chromium with the extension preloaded, for CI or when you'd rather not use your own Chrome). Per-OS
setup — especially the real-browser bridge (`collie browser-bridge` + `harness/browser_ext/`) — is in
**[docs/PLATFORMS.md](docs/PLATFORMS.md)**.

## Quickstart

```bash
collie                     # terminal chat (TUI); first run picks a provider
collie web                 # browser GUI — chat, live gate, diffs, star-map, ambient desktop
collie selftest            # $0 deterministic end-to-end (mock model, real tools + memory)

DEEPSEEK_API_KEY=... collie -p "fix the off-by-one in utils/timeparse.py"

# machine-readable / streaming
collie run "fix the bug" --json          # final result object (tokens, cost, verified)
collie run "fix the bug" --stream-json   # live NDJSON: tool · edit · repro-gate · receipt

# fully local, no key
collie run "summarize app.py" --provider ollama --model qwen2.5-coder:7b

# autonomous loop: iterate toward the goal, STOP the first turn an executed check goes green
collie loop --goal "get the suite passing" --until "pytest -q" --max 8

# best-of-N with EXECUTION-based selection: run N isolated attempts, keep only what passes
collie pack "fix the failing test" -n 3 --check "pytest -q" --apply

collie acp                 # serve as an ACP agent (an editor spawns this over stdio)
```

Providers: `mock`, `ollama`, `anthropic`, `anthropic-oauth`, and OpenAI-compatible presets
`deepseek` · `qwen`/`dashscope` · `openrouter` · `moonshot` · `groq` · `zhipu` · `openai`.

---

# For developers

Everything above rests on a small, honest harness. This is what's under it.

## The signature: the verification gate

```
  locate   code_search "parse_duration compound units"   · 4 hits
           › utils/timeparse.py:42  _parse  ············· 0.91

repro    wrote repro.py · assert parse_duration("1h30m") == 5400
           ✗ FAILING  › got 1800, want 5400              ← gate armed

edit     utils/timeparse.py  ································· +1 −1
           43 │- total = SECONDS[unit] * int(val)
           43 │+ total += SECONDS[unit] * int(val)

verify   python repro.py
           ✓ PASSING  › parse_duration("1h30m") == 5400   ← gate green

✓ verified in 12.8s · Δ +1 −1 · 3,410 tok · $0.006
```

Other agents check "did the test not error." Collie's gate is stronger: the reproduction carries an
`assert actual == expected` derived from the issue, so a plausible-but-wrong edit fails *loudly* and
drives another repair round. This **`assert-verify`** loop is the core of the harness — a wrong edit
never silently ships as "done." The same idea scales up: `collie loop` stops when a real shell check
exits 0, and `collie pack` picks the best of N attempts by what actually passes.

## What it asks before doing

Collie reaches further than a cloud agent — your logged-in browser, your desktop, your files — so
it draws a line and asks before crossing it. Every tool declares how far it reaches
([`harness/risk.py`](harness/risk.py)), and `collie risk` prints the whole table:

| | | |
|---|---|---|
| **read** | no side effects | never asks |
| **write_local** | changes files here | inside your directory: goes ahead |
| **exec** | runs commands here | inside your directory: goes ahead |
| **external** | **leaves this machine** — your logged-in browser, your desktop, an MCP server | **asks, every time** |

**Running `collie` in your repo is the consent** for the middle two. That is the whole point of the
default `project` mode: an agent that interrupts every `pytest` is not usable, and asking about work
you already asked for is theatre. What you did *not* consent to by launching it is `browser_click`
sending mail under your cookies — so that asks.

```bash
collie -p "fix the bug"                  # project (default)
collie -p "..." --mode plan              # read-only: explore and propose, change nothing
collie -p "..." --mode interactive       # ask before every write and command too
collie -p "..." --mode auto              # ask nothing (sandboxes, CI)
collie risk                              # what collie can reach, grouped by how far
```

Three things worth knowing:

- **"Always allow" is pinned to a target, never to a tool.** Approving clicks on
 `http://localhost:5173` does not approve clicks on your bank — the rule is
 `browser_click → http://localhost:5173`, the origin is re-read live on every call, and it lasts
 one run. There is deliberately no way to express "always allow browser_click".
- **Unattended does not raise the ceiling — it changes who can answer.** When nobody is at the
 machine, the question goes to the Inbox and the run *suspends*; your phone gets a nudge, and you
 answer from there, from the browser, or with `collie inbox allow <id>`. One record, so whoever
 answers first is the one that counts. With no surface at all (piped, CI), off-machine calls are
 refused with a reason the model can work around — never run because no one objected.
- **Only you can widen anything.** A repo's `.collie/allow.toml` is inert until you `collie trust`
 that exact directory; a persona can only *narrow* what you allowed; and the risk overrides have
 no tool and no config hook, because something collie loaded must never be able to reclassify
 itself as harmless.

In an editor, this is the editor's own prompt: collie speaks ACP's `session/request_permission`, so
Zed / JetBrains / neovim render their native approval UI.

```bash
collie inbox # what is waiting on you, across runs
collie inbox allow <id> # …answer it from anywhere
collie trust # let THIS repo's .collie/allow.toml count
collie audit --unexplained # anything that ran silently without citing a rule
collie risk --set 'mcp__fs__read_*' --risk read # stop being asked about a server you have read
collie -p "..." --persona webwork # a role: identity + tools + a stricter mode
```

`collie audit --unexplained` is the one to remember. Every call that runs *without* asking records
the rule that let it through, so the question "why was I not asked about that?" has an answer. It
should always print nothing.

## Architecture (abstractions & seams)

```
                      ┌──────────────── loop.Harness ────────────────┐
   task ─────────────▶│  compose → complete → run tools → verify ✓   │
                      └──┬──────────────┬──────────────┬─────────────┘
     ┌───────────────────┘              │              └───────────────────┐
     ▼                                  ▼                                  ▼
 ContextComposer                  ModelProvider                     ToolRegistry
 STABLE/CONTEXT/VOLATILE          OpenAI-compat · Anthropic ·       read/write/edit/bash/
 + token budgeter                 Ollama · subscription-OAuth       grep/glob + code_search
     ▼                                  │                                  │
 memory.SqliteMemory                    ▼                            recorder.Recorder
 hybrid recall (BM25+dense+RRF)   emit → stream-json / ACP          runs.db (+ dashboard)
```

| Seam (abstract base) | shipped impl |
|---|---|
| `ModelProvider` | **OpenAICompat** (DeepSeek/Qwen/GLM/OpenRouter…) · Anthropic · Ollama · subscription-OAuth |
| `ToolRegistry` | read/write/**edit** (syntax-gated) · bash · grep · glob · **`code_search`** · **`web_search`** + **`web_fetch`** (keyless) · **`plan`** · **`undo`** · browser · **MCP** (deferred tier + `load_tools`) |
| `EmbeddingProvider` | **OnnxEmbedding** granite-107m (Apache, 55MB, multilingual) · bge-m3 / e5 · jina-v3 opt-in · **BM25-only** when no model |
| `SqliteMemory` | CORE + facts + FTS5 + cosine, hybrid RRF + optional rerank + consolidation |
| `ContextComposer` | STABLE/CONTEXT/VOLATILE + auto-prefetch · a ~1K-token fixed prefix (kept deliberately lean) |

**`code_search`** extracts the identifiers from a natural-language query and greps the repo (ripgrep,
else grep), ranking files by how many of your terms each contains — so the agent reasons about *where*
to edit instead of grepping blind, with no model and no index to go stale. **`edit_file`** is
exact-match, whitespace-tolerant, and **rejects any edit that would break Python syntax**.
Untrusted web/page content is **fenced as data** (prompt-injection defense), and the browser bridge
refuses any request missing its CSRF header. A token/cost **budget**
(`COLLIE_MAX_COST` / `COLLIE_MAX_TOTAL_TOKENS`) stops a run at a ceiling.

## Platforms

One cross-platform Python codebase — **not** a per-OS fork. The handful of operations that genuinely
differ (kill a process tree on a timeout, secure a token file, convert a path, choose a shell) are
isolated in `harness/plat.py`, so the same wheel runs everywhere.

| OS | Status | Notes |
|---|---|---|
| **Linux** | ✅ native | the primary target |
| **macOS** | ✅ native | POSIX; the browser bridge is *simplest* here (Chrome + Collie on one OS) |
| **Windows** | ✅ one-click | the packaged installer; the agent prefers the file/search tools over `bash` |
| **WSL2** | ✅ | a Windows-Chrome ↔ WSL bridge uses the LAN IP + `wslpath` (handled for you) |

## Benchmark lab (built in)

Collie measures itself against other harnesses on the **same** task and model — you run it yourself;
no numbers are asserted here:

```bash
DEEPSEEK_API_KEY=... python swe_run.py --n 5                 # SWE-bench Verified (needs Docker)
python -m bench.multirun_eval                                # pass@1 / pass@k / Wilson CI / McNemar
python -m bench.polyglot_eval --langs python,cpp,javascript  # Aider-Polyglot, multi-language
python -m harness.cli compare --vs all                       # vs Claude Code / Aider / …
```

## Honesty & policy

- The benchmark harness is version-tagged and reproducible. "Progress is a number" cuts both ways —
  Collie surfaces the levers that turn out **net-neutral**, not just the wins.
- Token counts are real usage (the model's own `usage`, or `harness/apitap.py` metering for CLIs that
  report none) — apples-to-apples, same source both sides.
- Collie draws a personal Max/Pro subscription only through the first-party OAuth path
  (`anthropic-oauth`), the same mechanism the official CLI uses; it never scrapes or resells
  subscription tokens. Cheap API keys and local models are the default.

## License

collie

File Explorer

# Use via CDN

Was this content helpful?

Recent Feedback

Download README