claude-os/docs/guides/SHARING_GUIDE.md

# Claude OS Sharing Guide

## Overview

This guide explains how to share Claude OS with coworkers and set up new projects.

## Architecture

```
claude-os/
├── templates/              # All reusable templates
│   ├── commands/          # Slash commands (symlinked to ~/.claude/)
│   ├── skills/            # Skills (symlinked to ~/.claude/)
│   ├── agents/            # Agent-OS agents (8 specialized agents)
│   └── project-files/     # Files created during project init
│       ├── CLAUDE.md.template
│       ├── agent-os/      # Agent-OS project templates
│       └── .claude-os/    # Config templates
├── cli/                   # CLI tools
│   └── claude-os-consolidate.sh
├── install.sh             # One-command install for coworkers
└── app/                   # Flask API server
```

## For You (Initial Setup)

### Step 1: Consolidate Your Files

Move all scattered commands and skills into templates/:

```bash
cd /Users/iamanmp/Projects/claude-os
./cli/claude-os-consolidate.sh
```

This will:
- Move commands from `~/.claude/commands/` → `templates/commands/`
- Move skills from `~/.claude/skills/` → `templates/skills/`
- Create symlinks so everything still works for you
- Update any hardcoded paths

### Step 2: Commit to Git

```bash
cd /Users/iamanmp/Projects/claude-os
git add templates/ cli/ install.sh SHARING_GUIDE.md
git commit -m "Add templates and installation system for sharing"
git push
```

### Step 3: Test Installation (Optional)

Test on a different machine or user account:

```bash
git clone your-repo/claude-os.git
cd claude-os
./install.sh
```

## For Coworkers (First Time Setup)

### Step 1: Clone Claude OS

```bash
git clone your-repo/claude-os.git
cd claude-os
```

### Step 2: Run Install Script

```bash
./install.sh
```

This will:
- ✅ Create `~/.claude/` directories
- ✅ Symlink all commands and skills
- ✅ Optional: Install Agent-OS (8 agents by Builder Methods)
- ✅ Ask about AI provider (Ollama or OpenAI)
- ✅ Set up Python virtual environment
- ✅ Install dependencies
- ✅ Configure MCP server
- ✅ Create start script

**Note**: Agent-OS is an optional integration created by Builder Methods (CasJam Media LLC) and MIT licensed. The installer will ask if you want to install it.

### Step 3: Start Claude OS

```bash
./start.sh
```

This starts the MCP server at `http://localhost:8051`

### Step 4: Initialize Their First Project

```bash
cd /path/to/their/project
```

In Claude Code, run:
```
/claude-os-init
```

Follow the prompts to:
- Name the project
- Specify tech stack
- Ingest documentation
- Analyze codebase

Done! Their project is now connected to Claude OS.

## For New Projects (After Setup)

Once Claude OS is installed, initializing new projects is simple:

```bash
cd /path/to/new/project
```

In Claude Code:
```
/claude-os-init
```

Answer the questions and you're done!

## What Gets Created During Project Init

```
your-project/
├── CLAUDE.md              # Project context (auto-loaded every session)
├── .claude/               # Project-specific Claude Code files
│   ├── commands/          # (symlinks to Claude OS templates)
│   ├── skills/            # (symlinks to Claude OS templates)
│   ├── agents/            # Project-specific agents
│   ├── ARCHITECTURE.md    # Generated by initialize-project
│   ├── CODING_STANDARDS.md
│   └── DEVELOPMENT_PRACTICES.md
└── .claude-os/            # Claude OS state/config
    ├── config.json        # Project configuration
    ├── hooks.json         # Project hooks
    └── .gitignore         # State files ignored
```

## Knowledge Bases Created

Each project gets 4 knowledge bases:

1. **`{project}-project_memories`** - Claude's memory for decisions, patterns, solutions
2. **`{project}-project_profile`** - Architecture, standards, practices
3. **`{project}-project_index`** - Automated codebase index
4. **`{project}-knowledge_docs`** - Your documentation (auto-ingested)

## Commands Available After Setup

All these work in any initialized project:

- `/claude-os-init` - Initialize new project
- `/claude-os-search` - Search project memories
- `/claude-os-save` - Save insights
- `/claude-os-remember` - Quick save to memories
- `/claude-os-list` - List knowledge bases
- `/claude-os-session` - Manage dev sessions
- `/claude-os-triggers` - Manage trigger phrases

## Skills Available

- `initialize-project` - Analyze codebase and generate standards
- `memory` - Auto-save when you say "remember this:"
- `memory` - Simple memory management

## Agent-OS Commands (If Installed)

If you chose to install Agent-OS during setup, you also get these commands:

- `/new-spec` - Initialize a new feature specification
- `/create-spec` - Full specification workflow
- `/plan-product` - Create product documentation
- `/implement-spec` - Implement a specification

**Agent-OS** is created by Builder Methods (CasJam Media LLC) and provides 8 specialized agents for spec-driven development. Learn more at https://github.com/builder-methods/agent-os

## Benefits for Your Team

### One-Time Setup
- Clone repo → run install → done
- No configuration needed
- Works on Mac/Linux (Windows with WSL)

### Project Isolation
- Each project has its own knowledge bases
- No cross-contamination
- Team members can work on multiple projects

### AI Memory Across Sessions
- Claude remembers decisions across conversations
- Searchable history of all work
- Pattern recognition improves over time

### Documentation Integration
- Automatically indexes your docs
- Searchable alongside code context
- Always up to date

## Updating Claude OS

When you add new commands/skills to templates:

```bash
# On your machine:
cd /Users/iamanmp/Projects/claude-os
git pull origin main

# Commands/skills auto-update via symlinks!
```

Coworkers do the same:
```bash
cd ~/Projects/claude-os
git pull origin main

# Their symlinks automatically point to updated templates
```

## Troubleshooting

### "Command not found: /claude-os-init"

Symlinks weren't created. Re-run:
```bash
cd /path/to/claude-os
./install.sh
```

### "Connection refused to localhost:8051"

Claude OS server isn't running:
```bash
cd /path/to/claude-os
./start.sh
```

### "Project already exists"

Project name is taken. Choose a different name or delete the old project via the UI at `http://localhost:8051`

### Commands work but changes don't persist

Make sure you're committing changes to the Claude OS repo, not your project repo:
```bash
cd /path/to/claude-os  # NOT your project dir
git status
git add templates/
git commit -m "Updated templates"
git push
```

## Adding Custom Commands/Skills

### Add a New Command

1. Create file in `templates/commands/my-command.md`
2. Write command logic (see existing commands for examples)
3. Commit to git
4. Coworkers pull and get it automatically via symlinks

### Add a New Skill

1. Create directory in `templates/skills/my-skill/`
2. Add `SKILL.md` and any scripts
3. Commit to git
4. Coworkers pull and get it automatically

## Security Notes

- `.claude-os/` state files are git-ignored by default
- Never commit API keys or secrets to CLAUDE.md
- Each team member has their own Claude OS database
- Knowledge bases are local, not shared (unless you want to sync them)

## FAQ

**Q: Do I need to reinstall for each project?**
A: No! Install Claude OS once, then just run `/claude-os-init` in each project.

**Q: Can multiple people work on the same project?**
A: Yes! Each person has their own Claude OS database. Shared project knowledge goes in CLAUDE.md (git-tracked).

**Q: What if someone doesn't have Claude Code?**
A: They need Claude Code (the CLI tool) to use this. Free at https://claude.com/claude-code

**Q: How much disk space does it use?**
A: ~500MB for Claude OS + dependencies. Each project's knowledge base is ~10-100MB depending on docs.

**Q: Does this work on Windows?**
A: Yes, with WSL (Windows Subsystem for Linux). Native Windows support coming soon.

## Support

- 📚 Documentation: See README.md in this repo
- 🐛 Issues: Open an issue on GitHub
- 💬 Questions: Ask in team chat or @ the maintainer

## Next Steps

1. **For you**: Run `./cli/claude-os-consolidate.sh` to organize your files
2. **For coworkers**: Share the repo URL and have them run `./install.sh`
3. **For new projects**: Just run `/claude-os-init` and answer questions

---

**You built this! Now share it and make your whole team invincible! 🚀**