Cowork

Cowork and Claude Code are two modes of the same brain. They share everything in ~/.claude/ — agents, memory, settings, rules. The difference is posture.

Two Modes

Shared State

Both modes read and write to:

Handoff: Cowork → Code

When work starts in Cowork (planning, strategy, research):

1. Cowork produces a deliverable: plan, architecture, stories
2. Cowork creates GitHub issues for actionable items
3. Cowork appends to ~/.claude/bridge.md
4. Code reads bridge.md at session start
5. Code picks up the issues and executes

Example

[Cowork session]
Abdout: "Plan the hogwarts notification system"
→ Research patterns, design architecture, write stories
→ Create issues: databayt/hogwarts#10, #11, #12
→ Append to ~/.claude/bridge.md: "Notification system planned. Issues: #10, #11, #12."

[Claude Code session]
Captain: reads bridge.md → sees plan → starts executing #10

Handoff: Code → Cowork

When Code finishes work that needs strategic review:

1. Code writes to ~/.claude/bridge.md
2. Code creates a GitHub issue if follow-up is needed
3. Cowork picks up in the next Desktop session

Cowork Use Cases

Ali (QA + Sales)

> "Summarize this week's hogwarts progress for pitch materials"
> "Draft proposal for King Fahad Schools — open source, sharing economy angle"
> "Research schools, sponsors, investors in Sudan/MENA"

Samia (R&D)

> "Translate these UI strings to Arabic"
> "Write help documentation for the admission module"
> "Research best practices for school notification systems"

Abdout (Planning)

> "Plan the notification system architecture"
> "Review the weekly revenue report"
> "Design the multi-tenant billing flow"

Session Start Protocol

Every Cowork Session

1. Read ~/.claude/bridge.md for Code's latest output
2. Review GitHub issues for completed/blocked items (label from-code or priority/blocking)
3. Plan next moves

Every Code Session

1. Read ~/.claude/bridge.md — check for Cowork handoffs
2. gh issue list --state open --label "from-abdout,priority/blocking" — check Abdout's instructions + blockers
3. gh issue list --state open — full work queue
4. Proceed with highest priority

The Key Insight

Cowork doesn't need to know how to code. Claude Code doesn't need to strategize. They share a brain through bridge.md + GitHub Issues + native push notifications.

Abdout switches between them like switching between thinking and doing. Both are Captain — one thinks, one acts.

Operating notes

The always-loaded rule (.claude/rules-global/cowork-bridge.md) keeps only what a Code session needs on every turn. The detail lives here. Cowork: read this section before your first command in a session.

What each side can do

Three of these rows used to read "No" for Cowork, and "Drive a browser" read "No" for Code until 2026-09-26. They were wrong, and the wrong version cost real work — Code planned around a Cowork that supposedly couldn't run a command. Corrected 2026-07-27 from a session that did all three.

Not shared between the two: conversation history, active context (tools loaded, files read), hooks and settings.json automation, slash commands.

The two shells

Cowork has two shells, and they see different filesystems:

• Bash runs in an ephemeral Anthropic cloud container. Use it for clones, builds, installs, scratch work. Nothing here touches Abdout's Mac. gh is not installed in it.
• device_bash runs on Abdout's machine, inside the desktop app's Linux VM, with his connected folders mounted. ~/kun appears there as /sessions/<session-id>/mnt/kun/. It cannot delete files — rm returns "Operation not permitted". To remove something, mv it into a _to_delete/ subfolder under the same mounted folder and tell Abdout to empty it.

A file written by one is invisible to the other. Pick one location per file.

Separately, the filesystem MCP addresses the same Mac files by their real macOS paths (/Users/abdout/kun/...), not the mounted /sessions/... ones. Three path vocabularies, one machine — read the tool name before you write.

Known breakage

• github MCP returns Authentication Failed: Requires authentication on write calls (add_issue_comment, create_or_update_file) while read calls succeed. Workaround that works today: drive github.com in the browser via the claude-in-chrome MCP — find the comment box, form_input the body, click Submit. Slower, but it posts.
• git in a mounted folder prints unable to unlink '.git/index.lock': Operation not permitted on every invocation. It is the sandbox's unlink restriction, not a stale lock, and clearing the lock does not stop it. The command underneath still succeeds. Ignore it; do not go hunting.

Cowork session start

1. Read ~/.claude/bridge.md via filesystem MCP — check for Code results.
2. Check GitHub issues for completed/blocked items (label from-abdout or priority/blocking).
3. Plan next moves, update bridge.md with the plan.

Desktop MCP config

Cowork's session runs in Anthropic's cloud; it reaches the Mac through the desktop app's device bridge, which also proxies the MCP servers configured in ~/Library/Application Support/Claude/claude_desktop_config.json:

• filesystem — reads/writes ~/.claude/, ~/kun, ~/codebase (real macOS paths)
• github — repos, issues, PRs in the databayt org (reads fine; writes 401 — see Known breakage)

The bridge only works while the desktop app is open. When it isn't, previously staged files remain readable but nothing new can be fetched or written back.

Phone → Mac — pick the lane

The Mac is the bottleneck, not the plan: it has 16 GB of RAM and each open session holds about 10 MCP processes. Close sessions when their work is done; the kun-rc server keeps the phone's way in. bash ~/.claude/scripts/devices.sh --status shows the whole lane.