Connect Claude Projects, Cowork, and Claude Code

Claude currently has several project-shaped surfaces:

Claude Chat / Claude.ai Projects for persistent conversational work, uploaded knowledge, and project instructions.
Claude Cowork for non-coding work that can operate on selected local folders, connectors, and desktop apps.
Claude Code for software development in a terminal, IDE, desktop Code tab, or cloud session.

They are related, but they do not all read one shared "Claude project" database. The safest setup is to create a project hub in your repository or working folder, then let each Claude surface consume that hub in the way it supports.

The Key Distinction

Do not treat ~/.claude/projects/ as your canonical project store.

Claude Code uses ~/.claude/ for personal configuration and application data. Its project entries can contain local transcripts, prompt history, file snapshots, and auto memory such as:

~/.claude/projects/<project>/
├── <session>.jsonl
└── memory/
    ├── MEMORY.md
    ├── debugging.md
    └── ...

That data is useful for Claude Code, but it is machine-local app state. It is not the same thing as a Claude.ai Project, and it is not the best place to maintain shared project knowledge.

Use this rule:

Kind of information	Best home
Team-wide repo instructions	`AGENTS.md`, `CLAUDE.md`, `.claude/CLAUDE.md`, `.claude/rules/`
Personal preferences across all repos	`~/.claude/CLAUDE.md`, `~/.claude/rules/`
Personal preferences for one repo	`CLAUDE.local.md`, `.claude/settings.local.json`
Claude Code auto-learned notes	`~/.claude/projects/<project>/memory/`
Claude.ai Project instructions	Project instructions in Claude.ai
Claude.ai Project knowledge files	Uploaded or attached files in the Project
Cowork working files	A selected local folder you explicitly grant

Recommended Architecture

Create one folder or repository that acts as the source of truth for the project.

my-project/
├── AGENTS.md
├── CLAUDE.md
├── CLAUDE.local.md              # gitignored
├── .claude/
│   ├── CLAUDE.md
│   ├── rules/
│   │   ├── architecture.md
│   │   ├── coding-style.md
│   │   └── testing.md
│   ├── skills/
│   └── settings.local.json      # gitignored
├── .ai-context/
│   ├── project-brief.md
│   ├── glossary.md
│   ├── decisions.md
│   └── handoff.md
└── docs/

The .ai-context/ folder is optional, but it is the cleanest bridge between Chat, Cowork, and Code:

Upload those files to a Claude.ai Project as Project knowledge.
Point Cowork at the same folder when doing non-code work.
Import those files from CLAUDE.md or .claude/rules/ for Claude Code.
Commit the durable parts to git so every surface starts from the same facts.

Step 1: Create A Shared Project Brief

Create a concise context pack:

.ai-context/
├── project-brief.md
├── glossary.md
├── decisions.md
└── handoff.md

Use these files for information that should survive across surfaces:

Product goal and current priorities
Repository layout and ownership boundaries
Architecture decisions
Domain vocabulary
External systems, connectors, and credentials policy
Current handoff notes

Keep this pack short. Put living implementation details in the repo. Put task history in issues, PRs, or handoff.md, not in one giant prompt.

Step 2: Wire Claude Code To The Same Context

At the repo root, add a CLAUDE.md that imports shared instructions:

@AGENTS.md
@.ai-context/project-brief.md
@.ai-context/glossary.md

## Claude Code

- Use the commands and validation steps documented in this repository.
- Treat `.ai-context/decisions.md` as the durable decision log.
- Ask before changing public API contracts, database migrations, or deployment configuration.

Claude Code reads CLAUDE.md, not AGENTS.md. Importing AGENTS.md avoids duplicating instructions for multiple coding agents.

For larger repos, move conditional rules into .claude/rules/:

.claude/rules/
├── frontend.md
├── backend.md
├── testing.md
└── security.md

Use path-scoped rules when a rule should only apply to part of the tree:

---
paths:
  - "src/api/**/*.ts"
  - "app/Http/**/*.php"
---

# API Rules

- Validate inputs at the boundary.
- Keep response formats backward compatible unless the task explicitly changes the API contract.

Run Claude Code from the project root:

cd ~/work/my-project
claude

Inside Claude Code, use /memory to inspect which instruction files are loaded and to open the auto memory folder.

Step 3: Connect Claude.ai Projects

In Claude.ai, create or open a Project for the same domain.

Use the Project instructions for the stable behavior you want in every chat:

You are helping with the my-project codebase and product documentation.
Use the uploaded project brief, glossary, decisions, and handoff files as the source of truth.
When a request affects code, recommend using Claude Code in the repository instead of inventing changes from memory.
When facts are missing, ask for the current repo file or issue link.

Then add Project knowledge:

.ai-context/project-brief.md
.ai-context/glossary.md
.ai-context/decisions.md
.ai-context/handoff.md
architecture docs or public specs that are safe to upload

This gives Claude Chat a parallel view of the same context Claude Code reads locally.

Important limitation: Claude.ai Project knowledge is not automatically synced from your filesystem. When a context file changes, update the uploaded Project knowledge or paste the changed section into the Project.

Step 4: Connect Cowork

Use Cowork when the task is not primarily a coding task:

Organizing folders
Preparing reports
Summarizing notes
Producing spreadsheets, decks, and documents
Running recurring knowledge-work tasks

In the desktop app, choose the Cowork tab and grant access only to the relevant working folder. For project work, that should usually be either:

~/work/my-project/.ai-context/

or a dedicated non-code workspace:

~/work/my-project/workspace/

Use a prompt that keeps Cowork aligned with the same source of truth:

Use the files in this working folder as the current project context.
Read project-brief.md, glossary.md, decisions.md, and handoff.md first.
Before editing files, show me the plan and wait for approval.
If a change belongs in source code, stop and tell me to continue in Claude Code.

Keep Cowork away from broad home-directory access. It can take real actions on local files and connected tools, so use narrow folders and explicit approval.

Step 5: Move Between Code, Web, And Desktop

Claude Code has several ways to bridge surfaces:

Direction	Best option
Local terminal to browser/mobile, while still running locally	Remote Control
Local repo to Claude Code cloud session	`claude --remote "task"`
Cloud session back to terminal	`claude --teleport`
Desktop Code tab to CLI	Open in CLI / same repo
Chat or Cowork to Code	Put the handoff in `.ai-context/handoff.md`, then start Claude Code

For local remote control:

cd ~/work/my-project
claude --remote-control "my-project"

This keeps the session on your machine while the browser or mobile app acts as a remote window into it.

For cloud execution:

cd ~/work/my-project
claude --remote "Implement the plan in .ai-context/handoff.md"

For returning from a web/cloud session:

cd ~/work/my-project
claude --teleport

What To Link And What Not To Link

Use symlinks for authored configuration when that helps:

ln -s ../shared-claude-rules .claude/rules/shared
ln -s AGENTS.md CLAUDE.md

Prefer imports when you need Claude-specific additions:

@AGENTS.md

## Claude Code

- Use plan mode before editing deployment scripts.

Avoid symlinking the whole ~/.claude/projects/ tree into a repo. That directory contains local app data and transcripts. It can include sensitive content, command output, prompt history, and temporary state. Keep it local, inspect it with /memory when useful, and purge it with Claude Code's project cleanup command when needed.

Practical Daily Workflow

Start in Claude.ai Project for strategy, writing, research, and broad discussion.
Save durable decisions into .ai-context/decisions.md.
Save executable handoffs into .ai-context/handoff.md.
Open Claude Code in the repo and run the coding work from the handoff.
Use Remote Control when you want to continue the same local Code session from browser or mobile.
Use Cowork for non-code deliverables, pointed at a narrow folder.
Sync updated .ai-context/ files back into Claude.ai Project knowledge when they change.

Minimal Setup Checklist

Create .ai-context/project-brief.md, glossary.md, decisions.md, and handoff.md.
Add a repo-level CLAUDE.md that imports AGENTS.md and the shared context files.
Add .claude/rules/ for detailed project rules.
Add CLAUDE.local.md and .claude/settings.local.json to .gitignore.
Create a Claude.ai Project and upload the .ai-context/ files as knowledge.
In Cowork, grant access only to the project context or workspace folder.
Use /memory in Claude Code to verify what it loaded.
Use claude --remote-control, claude --remote, and claude --teleport for cross-surface handoff.

The Key Distinction​

Recommended Architecture​

Step 1: Create A Shared Project Brief​

Step 2: Wire Claude Code To The Same Context​

Step 3: Connect Claude.ai Projects​

Step 4: Connect Cowork​

Step 5: Move Between Code, Web, And Desktop​

What To Link And What Not To Link​

Practical Daily Workflow​

Minimal Setup Checklist​

References​