claude-os/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/:

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

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:

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

For Coworkers (First Time Setup)

Step 1: Clone Claude OS

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

Step 2: Run Install Script

./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

./start.sh

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

Step 4: Initialize Their First Project

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:

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
• remember-this - 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:

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

# Commands/skills auto-update via symlinks!

Coworkers do the same:

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:

cd /path/to/claude-os
./install.sh

"Connection refused to localhost:8051"

Claude OS server isn't running:

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:

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! 🚀