oh-my-colab (@iadr-dev/colab, CLI ohc): team-first AI coding workflows — methodology, orchestration, persistent memory; Claude Code plugin + Cursor/Codex/Gemini/Antigravity.

🧠 oh-my-colab

Methodology + orchestration + persistent memory. Every platform.

Your AI coding agent has the intelligence of a senior engineer. What it lacks is discipline, memory, and a team. oh-my-colab gives it all three.

🧠 ohc │ workflow: BUILD │ agent: executor/sonnet │ task: implement auth refresh
📊 plan: 4/7 steps │ notepad: 2 open items
🔀 branch: feat/oauth │ agents: 3 running │ worktrees: 3 │ MCP: context7 github brave-search

Find this repo (discovery)


Canonical name	oh-my-colab — CLI command `ohc`, npm package `@iadr-dev/colab`
Source	`github.com/iadr-dev/colab`
Not	Google Colab notebooks — unrelated product with a similar short name

Search tips: in Google or GitHub, prefer quoted brand + org: "oh-my-colab" iadr-dev, or site:github.com/iadr-dev/colab so results are not drowned out by Google Colab.

Repository About description and Topics (tags) on GitHub are set in Settings → General; they feed GitHub’s topic and search surfaces. Good pairs with this README: oh-my-colab, ohc, claude-code-plugin, mcp, tdd, orchestration.

Why oh-my-colab?

Problem	Solution
Goldfish brain — forgets everything between sessions	4-layer memory: SOUL + USER + PROJECT + notepad
Re-fetches the same library docs every session	Cross-session research cache (`.ohc/research/`) — lookup before fetch
Jumps to code without planning	Enforced PLAN gate for tasks >30 minutes
”Done” without running tests	Verifier agent reads actual output — 0 failing, 0 skipped
Only works with one platform	5 platforms: Claude Code, Cursor, Antigravity, Codex, Gemini
Parallel agents can’t coordinate or verify each other	`/ohc-team` five-stage pipeline with `RESULT.json` gate + auto fix loop
No learning loop	RETRO extracts skills from every session

Install

Everything else (Claude, Cursor, Antigravity, Codex CLI, Gemini CLI, plus Claude Code via npm)

npm install -g @iadr-dev/colab
ohc setup

ohc setup detects which platforms you want to support and writes the right config for each: .claude/ (Claude Code; Cursor may reuse it for compatibility), .cursor/, project .agents/ (Antigravity rules/skills/workflows; Codex also loads skills from .agents/skills/), project GEMINI.md plus user ~/.gemini/settings.json (Gemini CLI MCP), user ~/.gemini/antigravity/mcp_config.json when Antigravity is enabled, and user ~/.codex/ (Codex prompts + config.toml MCP tables). Optional: seed CONTEXT.md / CONTEXT-MAP.md from templates/ into the repo root as a bounded domain glossary.

Claude Code plugin (marketplace / git)

Bundled manifests live under .claude-plugin/ (metadata only). Ships skills/, agents/, plugin hooks (hooks/plugin-hooks.json with ${CLAUDE_PLUGIN_ROOT} per plugins reference), and Claude slash definitions as commands/ohc-*.md (Workflows section lists them). ohc setup copies hook scripts under .claude/hooks/ and merges the same nested hook definitions into .claude/settings.json (how Claude Code expects hooks); it also copies the verbose hooks/hooks.json to .claude/hooks.json for tooling compatibility (and mirrors commands into .claude/commands/).

Develop from this repo for claude code:

/plugin marketplace add ./.claude-plugin/marketplace.json
/plugin install oh-my-colab --scope project

Or from local directory installed once: Use npm i -g @iadr-dev/colab && ohc setup when you want the full multi-platform scaffold (recommended together with or after the Claude plugin).

How it works

Every session starts by reading global + project memory — always, in this order:

~/.ohc/SOUL.md     → who the agent is (constant)
~/.ohc/USER.md     → who you are (your preferences, stack, style)
.ohc/PROJECT.md    → what this project is (stack, conventions, gotchas)
.ohc/notepad.md    → what's in progress right now (human-editable)

Paths are created by ohc setup (PROJECT.md / notepad.md under .ohc/ in the repo; SOUL.md / USER.md under ~/.ohc/ by default).

You can edit .ohc/notepad.md directly between sessions. Write for your future self or teammate. The agent picks up exactly where you left off.

12-hook event system

oh-my-colab intercepts 12 Claude Code lifecycle events (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, PostToolUseFailure, SubagentStart, SubagentStop, PreCompact, PostCompact, Stop, SessionEnd, PermissionRequest). Each hook runs a Node.js handler under hooks/ that can inject <system_reminder> context, persist state, and enforce workflows. Plugin installs use hooks/plugin-hooks.json (with ${CLAUDE_PLUGIN_ROOT} paths). ohc setup wires the equivalent nested hooks object into .claude/settings.json and copies hooks/hooks.json to .claude/hooks.json as auxiliary reference.

Workflows — keyword-triggered

Core six:

Keyword	Workflow	What happens
`"explore"`	EXPLORE	Reads codebase, populates `.ohc/PROJECT.md`
`"deepsearch"`	EXPLORE	Targeted deep search — grep patterns, trace data flows, map dependencies for a specific concept (deep mode of explore)
`"plan this"`	PLAN	Interview → approaches → task list → confirms before building (`"design this"` routes here too — see `hooks/keyword-map.json`)
`"build"`	BUILD	Loads plan → coding-skill-lookup → subagents → TDD → verifier
`"review"`	REVIEW	Spec compliance + code quality report
`"ship it"`	SHIP	Pre-merge check → changelog → PR → clean
`"retro"`	RETRO	Session diff → patterns → update memory files

Meta-workflows:

Keyword	Workflow	What happens
`"autopilot"`	AUTOPILOT	PLAN + BUILD + REVIEW chained, pauses at plan for OK (`"full auto"` skips that gate)
`"ultrawork"`	ULTRAWORK	PLAN + BUILD + REVIEW chained in parallel mode for maximum throughput
`"ralph"`	RALPH	BUILD with persistence until tests pass (or max iters); `/ohc-ralph` maps in `hooks/keyword-map.json`
`"ralplan"`	PLAN	PLAN with persistence and iterative refinement
`"ultrathink"`	THINK	Extended brainstorming with deep reasoning and rigorous clarification rubrics
`"stopomc"`	STOP	Deactivates all persistent modes (bulk mode off, `"stop all"` also works)

Keyword routing is authoritative; edits go in hooks/keyword-map.json (picked up by hooks/on-user-prompt.js).

Claude Code plugin — slash commands

Plugin Markdown lives under commands/ohc-*.md (shown in Claude Code as /ohc-…):

/ohc-setup · /ohc-explore · /ohc-plan · /ohc-build · /ohc-review · /ohc-ship · /ohc-retro · /ohc-autopilot · /ohc-team · /ohc-research · /ohc-skill · /ohc-caveman · /ohc-ralph · /ohc-document-intake

Each workflow row above aligns with keywords; these slashes are explicit equivalents (plus /ohc-setup onboarding and /ohc-document-intake for external specs).

Eleven agents

Definitions live in agents/*.md (eleven files). Routed on Claude Code with the models below:

Agent	Model	Role
planner	opus	Requirements, design, task decomposition
executor	sonnet	Code writing, plan implementation
reviewer	opus	Code review, spec compliance, security
verifier	sonnet	Test execution — reads actual output
debugger	sonnet	Hypothesis-driven root cause
architect	opus	System design, ADRs
researcher	haiku	Context7 docs, Brave Search
writer	haiku	Changelogs, PR descriptions
collaborator	opus	Team handoffs, notepad updates
librarian	opus	Context efficiency, large file summarization
advisor	opus	Proactive risk assessment, gap analysis

The Model column is the Claude Code subagent model routing and applies only on Claude Code. On other platforms the agent .md files are rule/role references — the host platform decides which model runs. hooks/keyword-map.json also maps “handoff” / “picking up” phrases to the collaborator agent.

Parallel team support — five-stage pipeline

# Claude Code — native team mode (Task() dispatch)
/ohc-team 3:executor "implement the 3 tasks in .ohc/plans/auth-feature.md"

# CLI — tmux workers
ohc team 2:codex "security review of src/auth"
ohc team 4:gemini "redesign dashboard components"
ohc team 3:claude "write tests for utils/ modules"

Every team runs an internal pipeline, gated by evidence:

team-plan → team-prd → team-exec → team-verify → team-fix ⤺ → team-merge → done

Each worker gets its own git worktree under .ohc/team/<id>/worktrees/<name>/ on an ohc/<id>-<name> branch. The shared research cache (.ohc/research/) is symlinked into every worktree so workers never re-fetch docs another worker already cached.
Every worker must write RESULT.json (status, tests, files_changed, artifacts, notes) plus per-worker notes.md. The orchestrator refuses to advance past team-exec until every worker has written RESULT.json — no “pretend it’s done”.
If team-verify finds failures, ohc team advance auto-dispatches fix workers back into the same worktrees. Capped at 3 fix attempts; then it hands off to a human at team-merge.
ohc team merge <id> runs git merge --no-ff per worker branch, stopping on conflict so you can resolve manually.
Dirty worktrees block ohc team shutdown without --force. Nothing gets discarded silently.

State lives under .ohc/state/team/<id>/ and is inspectable via ohc team status <id>.

Team CLI

ohc team N:provider "task"            # Spawn team (starts at team-exec)
ohc team status <id>                  # Stage, RESULT.json counts, failing workers
ohc team advance <id>                 # Drive pipeline one step (auto-dispatches fix workers)
ohc team poll <id>                    # Check tmux worker exit sentinels (codex/gemini)
ohc team merge <id>                   # Merge worker branches back; stops on first conflict
ohc team shutdown <id> [--force]      # Remove worktrees
ohc team list                         # List all active teams

Skills — enforced, not suggested

“Trigger” is how the skill gets loaded: keyword phrases are matched by hooks/on-user-prompt.js against hooks/keyword-map.json; “referenced” skills are loaded by another skill or workflow.

Skill	Trigger	Enforces
ohc-coding-discipline	`CLAUDE.md` / Cursor rules norms + keywords `"discipline"`, `"scope check"`	Minimal scope, surgical changes, explicit assumptions, verifiable success criteria
explore-codebase	`"explore"`, `"explore codebase"`, `"understand"`, `"deepsearch"`, `"deep search"`	Reading order, `.ohc/PROJECT.md` population; deep mode: targeted pattern/flow search
brainstorming	referenced by writing-plans	Socratic questioning; `references/product-brief-template.md` for greenfield framing
writing-plans	`"plan this"`; substring `plan` ; `write a plan`	≤2h tasks, confirmation gate before BUILD
autopilot	`"autopilot"`, `"auto pilot"`, `"full auto"`; `/ohc-autopilot`	PLAN → BUILD → REVIEW chain (`full auto` skips plan gate in keyword map)
document-intake	`"from my docs"`, `"existing spec"`, `"external spec"`, `"document intake"`, `/ohc-document-intake`	Respect third-party PRD/RFC layouts; emit `.ohc/doc-sources.md` + traced `.ohc/plans/`
test-driven-development	`"tdd"`, `"test first"`	RED-GREEN-REFACTOR, 0 failing 0 skipped
subagent-driven-development	referenced by BUILD workflow	Git worktrees, dispatch protocol
systematic-debugging	`"debug"`, `"broken"`, `"not working"`, `"why is"`	Hypothesis before fix
requesting-code-review	`"review"`, `"code review"`, `"check this"`	Two-pass: spec then quality
finishing-a-branch	`"ship"`, `"ship it"`, `"finish branch"`	Pre-merge check, changelog, PR, cleanup + optional `references/production-checklist.md`
retrospective	`"retro"`, `"retrospective"`	Session diff, pattern extraction, memory update
context7-aware-coding	referenced when using libs	Live docs via Context7 — cache-first via `.ohc/research/`, no guessing
writing-skills	reference doc (meta)	Skill authoring guide and structure
ralph	`"ralph"`, `"keep going"`, `"ralph mode"`, `/ohc-ralph`	Persistent BUILD until tests pass
caveman	`"stop caveman"` / `"normal mode"` (exit); `"caveman mode"`, `"compressed mode"` (enter)	Persistent compressed responses with technical accuracy

The repo ships 33 skills under skills/*/SKILL.md and skills/coding/*/SKILL.md. Canonical keyword list: hooks/keyword-map.json.

Each skill: SKILL.md (≤200 lines) + references/ (on demand) + scripts/ (output only).

MCP servers

Server	Purpose	Key
Context7	Live library docs	Optional (free at context7.com/dashboard)
GitHub MCP	Repos, PRs, issues, CI	`GITHUB_PERSONAL_ACCESS_TOKEN`
Brave Search	Web search	`BRAVE_API_KEY`
Playwright	Browser automation, e2e	No
Firecrawl	Web scraping	`FIRECRAWL_API_KEY`
Linear	Remote MCP (`mcp.linear.app`)	No secret in default `ohc setup` (`scripts/setup/index.js`)
Sentry	Hosted MCP (`mcp.sentry.dev`)	No secret in default setup (add auth if your org requires it)
Figma	Hosted MCP (`mcp.figma.com`)	No secret in default setup (add tokens if your org requires it)

Interactive ohc setup only prompts for env vars where scripts/setup/index.js marks needsKey: true for your selection (Context7 remains optional).

Research cache (cross-session, anti-goldfish)

Every Context7 / Brave / GitHub doc fetch is persisted to .ohc/research/ so future sessions don’t re-fetch the same thing. The researcher agent runs cache-first — lookup() before any external call. At session start, on-session-start.js injects an <ohc_research_index> reminder listing cached entries so the agent knows upfront what’s already answered. The executor/verifier can stamp verified_working: true + the commit SHA onto an entry, giving the reviewer a research audit trail.

ohc research list                     # List cached entries (freshness, library, topic)
ohc research show <lib> <topic>       # Print one entry
ohc research search "<query>"         # Substring search across the cache
ohc research verify <lib> <topic> [commit]  # Mark an entry as verified-working
ohc research prune [--older-than N]   # Remove expired / >N-day entries
ohc research clear                    # Nuke the cache

Default TTL is 30 days. on-session-end.js auto-prunes stale entries. In /ohc-team mode, the cache directory is symlinked into every worker worktree so the whole team shares one source of truth.

ohc CLI

ohc setup                          # Interactive onboarding (+ optional CONTEXT templates)
ohc doctor                         # Health: .ohc, hooks JSON, MCP env hints, semver (colab devs)
ohc team N:provider "task"         # Spawn a team — see "Parallel team support" above
ohc research list | show | search  # Cross-session research cache
ohc skill list                     # List installed + draft skills
ohc skill promote <name>           # Promote draft to project skill
ohc skill draft <name>             # Scaffold a new skill
ohc version                        # Show version
ohc help                           # All commands

Philosophy

oh-my-colab enforces:

Plan before build — no code for tasks >30min without an approved plan
Minimal scope — no speculative features, no gold-plating
Verify before done — verifier reads actual test output, not just “tests pass”
Learn after done — every session teaches the system something via RETRO

These are not suggestions. The hooks, skills, and workflow gates enforce them.

Contributing

Before contributing a skill: read skills/writing-skills/SKILL.md. Claude Code slash sources live in commands/ohc-*.md; keep name in YAML frontmatter in sync with the filename stem.

SKILL.md must be ≤200 lines (CI blocks if not)
Move detailed content to references/
Move executable tools to scripts/
Test on Claude Code + at least one other platform
npm test runs a Node subset on Windows; full bash smoke (symlink worktree): npm run test:shell (Git Bash / WSL / Linux/macOS)

@iadr-dev/colab