colleague

AI coder backends are not interchangeable — a local vLLM model, an OpenAI-compatible endpoint, and a hosted assistant each bring their own SDK, controls, and output shape. colleague is the harness around the model: the same work command runs the task through whichever backend you pick, and the caller never has to care which mind ran it.

Two engines ship today. mock is deterministic and networkless — the CI workhorse, so you can see the shape of a task with no model and no network at all. vllm-openai drives any OpenAI-compatible endpoint with tool calling. Swap one for the other and nothing else about your workflow changes: the same command, the same typed TaskResult.

And this is how it actually runs at home: Claude thinks and designs; colleague does the field-work. Not a stronger mind taking over — a different mind at the next desk, catching what the author's mind glides past.

Everything colleague shows is one CockpitState — a pure-reducer state tree — rendered through three tiers, and the right tier is chosen automatically for whoever is looking: a human at a terminal, an agent without a screen, a bot that wants only JSON. Nothing is recomputed per renderer; the three views cannot drift apart because there is only one state.

The middle tier is the unusual one. TAUI — Textual Agentic UI — is the semantic mirror of the live cockpit: a serialised, selector-addressed JSON tree plus a Markdown render, so an agent can read and drive the same UI a human sees without a screen reader and without spending an LLM call on a screenshot.

And the cockpit is not colleague's private invention. It is imported from agentfront.taui — agentfront being colleague's one base dependency, the shared agent-first foundation built to fit humans, agents, and bots at once.

colleague work is the working surface: hand it a goal, and every engine consumes the same typed Task and produces the same typed TaskResult. That uniformity is the whole point — the caller assigns repo work without caring which engine executed it, and the result round-trips through JSON unchanged.

It never works in your tree. Every run gets a throwaway git worktree at your HEAD on its own colleague/<id> branch — your working tree and checked-out branch are never touched, even if the model commits mid-run. And if your tree is dirty, colleague refuses to start until you acknowledge it: delegating never silently sweeps your uncommitted work.

The loop itself is bounded, not open-ended. The model is offered seven base tools plus a curated set of optional ones, and every path out of the loop is one of three: the model signals finish, it answers in prose, or it hits the step budget. Termination is guaranteed, not hoped for.

Before the handoff, three gates run by default — lint autofix, test-integrity, affected tests — and all three are advisory: they surface findings on stderr and in the artifact, and they never wedge the run. Then the work lands the way work should land: branch, commit, push, pull request.

And a run is not a black box while it flies. Every run arms a flight — you can read its live feed, inject guidance, or stop it cooperatively, all over a file-based control plane that lands directives at the next turn boundary. Runs detach to the background, chain episodes until the task is done, and resume where they left off.

Mid-work, a backend may hire. The subagent and subagents loop tools delegate scoped children, each isolated in its own throwaway worktree on a sub/<id> branch, and a merge-subagent integrates the branches afterward — surfacing conflicts, never force-merging them. Plain delegation is capped at depth 2 and fanout 4; with roles, the budget deepens to depth 4 under a global cap of 24 agents per work item, charged before any child does work, so every nesting shape terminates.

Roles are what make the workforce typed. Five built-ins ship, and four of them are read-only: a read-only role is offered neither write_file, edit_file, nor run_command — and the role-aware ToolExecutor refuses a withheld tool even if the model hallucinates the call. In the repo's own words: a read-only role provably cannot mutate the tree.

The table below is not copied from documentation — it is the live surface, exactly as this install reports it.

colleague drives with two roles. The cortex is the fast, wide-window, authoritative tool-calling mind — it drives every turn of the bounded loop, and nothing about the loop, the gates, or the handoff changes. The senses is a tools-off multimodal front door: it reads the operator's raw request before cortex acts on it and shapes cortex's raw summary back into a conversational reply — it intakes and speaks, but it structurally cannot act.

Cannot act is not a policy promise — it is structural. Every senses call goes out with an explicit empty tool list on the wire, so a senses request cannot carry a tool schema at all; and the senses module imports neither the tool executor nor subprocess, so even a hallucinated tool call from a misbehaving senses model produces only an advisory packet — the repo tree provably untouched.

Both minds resolve by role, not by hardcoded model ids: with a lobes gateway armed, colleague's own config carries zero model ids — they are read live off the wire. The reference rig — a probed reference, not a requirement — pairs a Qwen3.6-27B cortex with a gemma-4-12B senses on vLLM behind lobes. And in the captures on this page you can watch that brain live across the mesh: cortex ready on spark, senses ready on Thor — one mind split over two machines.

Every work item is wrapped in a memory exchange against the repo's eidetic store. Recall-before injects one advisory prior-lessons block — capped at 4,000 characters, advice not authority — and remember-after upserts exactly one idempotent lesson per work item, so re-runs never duplicate. Incomplete runs are recorded too, because failures are the most valuable lessons.

Mid-run, the model can call a memory tool itself — and here the roles hold: a read-only role gets recall only, because remember is a write-capable shell-out the role-aware executor refuses.

Memory is default-ON but triple-gated: the config switch, a .eidetic/ store in the repo, and the eidetic CLI on PATH — all three, or a strict no-op. And it is one store, shared: the same store the operator's own remember and recall skills use, so colleague's lessons and Claude's notes are mutually visible. The two minds read each other's memory.

The saving is measured, not asserted — one live pair, the same task run against a cold store and then a warmed one, quoted here with its run ids as provenance rather than as a general benchmark:

colleague is a big surface for a small install, and the rest of it deserves at least a card each. One thread runs through all of them: every capability states its own limit, in the repo's own words.

Every capture on this page is a real session, and four of them prove the point on colleague itself, not just in prose. The step trace below is ported straight from the public repo: colleague once built its own website in eight bounded steps, with no step failing.

The other three are this very page. While it was being specced, colleague explored its own repo as ask-colleague's second, independent mind, and that run was graded through the same ROI loop described above. Then, before this page's pull request opened, colleague reviewed the diff itself — its one real catch shipped, recorded as a first-class deviation on the plan's ledger.

colleague moves fast, and its direction is checkable the same way its facts are: on the open tracker. Four currents stand out in the open issues.