SheWhoReignsSupreme/claude-os
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Add optional Agent-OS integration with proper attribution

Browse source 
Integrate Agent-OS by Builder Methods (CasJam Media LLC) as an optional
component during Claude OS installation, following a partner approach that
respects their project while creating a complete AI development system.

Key Changes:
- Updated install.sh to optionally clone Agent-OS from their GitHub repo
- Added proper attribution to Builder Methods throughout documentation
- Created "Acknowledgments" section in README with full credit
- Marked Agent-OS as optional in all user-facing docs
- Added graceful fallback if Agent-OS installation fails

Integration Approach:
- Partner model: git clone from https://github.com/builder-methods/agent-os
- Optional installation: users choose during ./install.sh
- MIT license compliance: all required copyright notices included
- Upstream updates: git clone ensures users get their latest improvements
- Clean separation: Agent-OS remains a separate, credited project

Files Modified:
- install.sh: Added Agent-OS installation prompt (lines 156-211)
- README.md: Added attribution in Agent-OS section and Acknowledgments
- SHARING_GUIDE.md: Updated to reflect optional Agent-OS integration

Benefits:
- Respects Builder Methods' work with proper attribution
- Creates complete system: Claude OS (memory) + Agent-OS (workflows)
- Users get upstream updates automatically
- Optional for flexibility
- MIT license compliant

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Bob Roberts 2025-10-30 19:20:37 -05:00
parent 369a8a0080
commit 6e1d000c1e
3 changed files with 336 additions and 7 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

195
README.md
View file

@ -42,6 +42,8 @@ You work with Claude Code on a feature, close the terminal, come back tomorrow..
✅ **Automatic Context Loading** - Starts every session with relevant memories
✅ **Session Management** - Track work, save progress, resume later
✅ **Documentation Ingestion** - Auto-indexes your docs during setup
✅ **Agent-OS Integration** - Optional spec-driven development with 8 specialized agents
✅ **Flexible AI** - Choose local Ollama (free) or OpenAI API (paid)
✅ **Team Sharing** - `./install.sh` for coworkers, works instantly
✅ **100% Local** - Never leaves your machine, fully private
✅ **Template System** - Commands and skills shared via symlinks
@ -64,10 +66,13 @@ cd claude-os
```
The installer will:
- ✅ Set up Python environment
- ✅ Install all dependencies
- ✅ Configure MCP server
- ✅ Symlink commands and skills to `~/.claude/`
- ✅ Optional: Install Agent-OS (8 agents by Builder Methods)
- ✅ Ask about AI provider (Ollama or OpenAI)
- ✅ Create start script
### Step 2: Start Claude OS
@ -85,6 +90,7 @@ cd /path/to/your/project
```
In Claude Code, run:
```
/claude-os-init
```
@ -92,6 +98,7 @@ In Claude Code, run:
Answer the questions (project name, tech stack, docs path, etc.) and **you're done!**
**What you get:**
- ✅ 4 knowledge bases created (memories, profile, index, docs)
- ✅ Documentation auto-indexed
- ✅ Codebase analyzed
@ -105,10 +112,12 @@ Answer the questions (project name, tech stack, docs path, etc.) and **you're do
### Prerequisites
**Required:**
- Python 3.11+ (`python3 --version`)
- Git (`git --version`)
**Optional:**
- Node.js 16+ (for React UI)
### Installation
@ -126,6 +135,7 @@ cd claude-os
```
**The setup script automatically installs:**
- ✅ Ollama (if not present) + LLM models
- ✅ Redis (if not present) for caching/queues
- ✅ Python virtual environment
@ -133,7 +143,7 @@ cd claude-os
- ✅ SQLite database
- ✅ Frontend dependencies (if Node.js present)
**Visit** http://localhost:5173 to use the web UI.
**Visit** <http://localhost:5173> to use the web UI.
### Consolidate Your Files (First Time Only)
@ -146,6 +156,7 @@ If you've been using Claude OS and have scattered commands/skills, run the conso
This moves all commands from `~/.claude/commands/` to `templates/commands/` and creates symlinks.
**Then commit to git:**
```bash
git add templates/ cli/ install.sh SHARING_GUIDE.md
git commit -m "Add packaging system for sharing"
@ -167,6 +178,7 @@ cd /your/project
```
In Claude Code:
```
/claude-os-init
```
@ -190,6 +202,7 @@ The command will:
- `{project}-knowledge_docs` - Your documentation
3. **Set Up Project Structure:**
```
your-project/
├── CLAUDE.md # Auto-loaded every session!
@ -265,6 +278,124 @@ All these work in any initialized project:
---
## 🤖 Agent-OS: Spec-Driven Development (Optional)
> **Created by [Builder Methods (CasJam Media LLC)](https://github.com/builder-methods/agent-os)**
> MIT Licensed • Optional Integration with Claude OS
**Agent-OS adds structured workflows for planning and implementing features using 8 specialized agents.**
Claude OS optionally integrates with Agent-OS during installation. Agent-OS is a separate open-source project created by Builder Methods, and we're grateful for their work in creating such powerful spec-driven development tools.
### When to Use Agent-OS
Enable Agent-OS during `/claude-os-init` if you want:
- **Structured feature planning** with iterative requirements gathering
- **Detailed specifications** before coding
- **Task breakdowns** with clear implementation steps
- **Verification workflows** to ensure completeness
### The 8 Agents
**Specification Workflow:**
1. **`spec-initializer`** - Initialize new spec directories
2. **`spec-shaper`** - Gather requirements through 1-3 questions at a time
3. **`spec-writer`** - Create detailed technical specifications
4. **`tasks-list-creator`** - Break specs into actionable tasks
**Implementation Workflow:**
5. **`implementer`** - Implement features following task list
6. **`implementation-verifier`** - Verify implementation completeness
7. **`spec-verifier`** - Verify specs and tasks consistency
8. **`product-planner`** - Create product documentation
### Agent-OS Commands
Available when enabled:
- **`/new-spec`** - Initialize a new feature specification
- **`/create-spec`** - Full specification workflow (gather requirements → create spec → generate tasks)
- **`/plan-product`** - Create product mission, roadmap, and tech stack docs
- **`/implement-spec`** - Implement a specification following its tasks
### How It Works
```
1. User: "/new-spec user-authentication"
→ Agent creates spec directory structure
2. User: "/create-spec"
→ spec-shaper asks 1-3 questions at a time
→ Gathers requirements iteratively
→ Identifies reusable code
→ Collects visual assets
3. Agent: spec-writer creates detailed specification
→ tasks-list-creator generates actionable tasks
4. User: "/implement-spec user-authentication"
→ implementer follows tasks step-by-step
→ implementation-verifier checks completeness
5. Result: Fully specified, implemented, and verified feature!
```
### Agent-OS Project Structure
When enabled, your project gets:
```
your-project/
├── agent-os/
│ ├── config.yml # Agent-OS configuration
│ ├── product/ # Product documentation
│ │ ├── mission.md # Product mission
│ │ ├── roadmap.md # Feature roadmap
│ │ └── tech-stack.md # Technology stack
│ ├── specs/ # Feature specifications
│ │ └── YYYY-MM-DD-feature-name/
│ │ ├── planning/
│ │ │ ├── requirements.md
│ │ │ └── visuals/
│ │ ├── spec.md
│ │ └── tasks.md
│ └── standards/ # Coding standards (as skills)
└── .claude/agents/agent-os/ # 8 agents (symlinked)
```
### AI Provider Options
Agent-OS requires AI for advanced features:
**Option 1: Ollama (Local, Free)**
- Requires 8GB+ RAM
- Fully private, no data leaves your machine
- Install: `https://ollama.ai`
- Then: `ollama pull llama2`
**Option 2: OpenAI API (Cloud, Paid)**
- Works on any machine
- ~$0.02 per request
- Requires API key (set during `./install.sh`)
The installer will ask which you prefer!
### Integration with Claude OS
Agent-OS agents deeply integrate with Claude OS:
- **Search memories** before creating specs (avoid reinventing)
- **Save decisions** to project_memories during planning
- **Reference patterns** from previous work
- **Build knowledge** that improves over time
**This is the complete AI development system!**
---
## 🏗️ Architecture
```
@ -331,6 +462,7 @@ claude-os/
```
**Benefits:**
- ✅ Update once, all projects benefit
- ✅ Symlinks mean instant updates
- ✅ Easy to share with team
@ -342,7 +474,7 @@ claude-os/
### Via Web UI
1. **Visit** http://localhost:5173
1. **Visit** <http://localhost:5173>
2. **Create Knowledge Base:**
- Click "Create Knowledge Base"
- Choose type (Generic, Code, Documentation, Agent_OS)
@ -398,6 +530,7 @@ When you run `/claude-os-init`, you get 4 knowledge bases:
### Sharing Claude OS
**Step 1: Package for sharing**
```bash
cd /path/to/claude-os
./cli/claude-os-consolidate.sh # Move files to templates/
@ -409,10 +542,12 @@ git push
**Step 2: Share repo URL with team**
Send teammates:
- Repo URL
- Link to `SHARING_GUIDE.md` in the repo
**Step 3: They install (3 minutes)**
```bash
git clone <your-repo-url>
cd claude-os
@ -425,6 +560,7 @@ Done! They can now use `/claude-os-init` on any project.
### Per-Project Setup
Each team member:
1. Runs `/claude-os-init` in their project
2. Gets their own knowledge bases
3. CLAUDE.md is committed to git (shared)
@ -479,12 +615,14 @@ Each project has `.claude-os/config.json`:
## 📊 Performance
**Native Ollama Setup:**
- Response time: ~40 seconds per query
- GPU acceleration: Full Metal GPU on Apple Silicon
- Memory usage: 8-10GB (models + context)
- CPU usage: 12 cores (M4 Pro)
**Why it's fast:**
- Direct GPU acceleration (no virtualization)
- Efficient vector search in SQLite
- Optimized RAG engine with caching
@ -497,10 +635,13 @@ Each project has `.claude-os/config.json`:
### Installation & Setup
#### `./install.sh` - Team Member Setup ⭐
```bash
./install.sh
```
**For coworkers joining the team:**
- ✅ Creates `~/.claude/` directories
- ✅ Symlinks all commands and skills
- ✅ Sets up Python environment
@ -508,20 +649,26 @@ Each project has `.claude-os/config.json`:
- ✅ Configures MCP server
#### `./setup.sh` - First-Time Setup
```bash
./setup.sh
```
**For the original creator:**
- ✅ Installs Ollama + Redis (if needed)
- ✅ Downloads LLM models (~5-10 GB)
- ✅ Sets up Python environment
- ✅ Creates database
#### `./cli/claude-os-consolidate.sh` - Organize Files
```bash
./cli/claude-os-consolidate.sh
```
**One-time consolidation:**
- Moves commands to `templates/`
- Moves skills to `templates/`
- Creates symlinks
@ -530,10 +677,13 @@ Each project has `.claude-os/config.json`:
### Service Management
#### `./start.sh` or `./start_all_services.sh` - Start Everything
```bash
./start.sh
```
**Starts:**
- 🔌 MCP Server (port 8051)
- 🎨 React Frontend (port 5173)
- 🤖 RQ Workers
@ -541,11 +691,13 @@ Each project has `.claude-os/config.json`:
- 🧠 Ollama
#### `./stop_all_services.sh` - Stop All
```bash
./stop_all_services.sh
```
#### `./restart_services.sh` - Restart
```bash
./restart_services.sh
```
@ -557,6 +709,7 @@ Each project has `.claude-os/config.json`:
### "Command not found: /claude-os-init"
Symlinks weren't created. Re-run:
```bash
cd /path/to/claude-os
./install.sh
@ -565,6 +718,7 @@ cd /path/to/claude-os
### "Connection refused to localhost:8051"
Claude OS server isn't running:
```bash
cd /path/to/claude-os
./start.sh
@ -572,7 +726,7 @@ cd /path/to/claude-os
### "Project already exists"
Project name is taken. Choose a different name or delete via UI at http://localhost:5173
Project name is taken. Choose a different name or delete via UI at <http://localhost:5173>
### Port Already in Use
@ -636,15 +790,18 @@ claude-os/
## 📖 Additional Documentation
### Getting Started
- **[SHARING_GUIDE.md](SHARING_GUIDE.md)** - 🤝 How to share with your team
- **[templates/README.md](templates/README.md)** - 📂 Template system documentation
### Core Features
- **[docs/SELF_LEARNING_SYSTEM.md](docs/SELF_LEARNING_SYSTEM.md)** - 🧠 How Claude learns automatically
- **[docs/REAL_TIME_LEARNING_GUIDE.md](docs/REAL_TIME_LEARNING_GUIDE.md)** - Real-time learning usage
- **[docs/MEMORY_MCP_GUIDE.md](docs/MEMORY_MCP_GUIDE.md)** - Persistent memory guide
### Technical Documentation
- **[README_NATIVE_SETUP.md](README_NATIVE_SETUP.md)** - Detailed native setup
- **[NATIVE_VS_DOCKER_DECISION.md](NATIVE_VS_DOCKER_DECISION.md)** - Why native Ollama
- **[PERFORMANCE_TEST_RESULTS.md](PERFORMANCE_TEST_RESULTS.md)** - Benchmark results
@ -655,6 +812,7 @@ claude-os/
## 🤝 Contributing
This is a team development tool. Feel free to:
- Modify for your specific needs
- Add new commands and skills
- Optimize RAG strategies
@ -662,27 +820,52 @@ This is a team development tool. Feel free to:
---
## 🙏 Acknowledgments
**Agent-OS Integration**
Claude OS optionally integrates with [Agent-OS](https://github.com/builder-methods/agent-os) by Builder Methods (CasJam Media LLC).
- **Project**: Agent-OS - Spec-driven development workflow system
- **Author**: Builder Methods (CasJam Media LLC)
- **License**: MIT
- **Repository**: https://github.com/builder-methods/agent-os
Agent-OS provides 8 specialized agents for structured feature planning and implementation. We're grateful to Builder Methods for creating such powerful tools and for licensing them under MIT, making this integration possible.
If you find Agent-OS valuable, consider:
- ⭐ Starring their repository
- 📣 Sharing it with other developers
- 🤝 Contributing to their project
---
## 📄 License
MIT License - Use it freely!
**Note**: This project (Claude OS) is MIT licensed. Agent-OS, when installed, is a separate project also MIT licensed by Builder Methods (CasJam Media LLC). See the Agent-OS repository for their specific license terms.
---
## 🎯 Next Steps
### For Original Creator:
### For Original Creator
1. Run `./setup.sh` (first time)
2. Run `./cli/claude-os-consolidate.sh` (organize files)
3. Commit templates to git
4. Share repo with team
### For Team Members:
### For Team Members
1. Clone the repo
2. Run `./install.sh`
3. Run `./start.sh`
4. Use `/claude-os-init` in your projects
### For Everyone:
### For Everyone
- Use `/claude-os-search` to find past work
- Use `/claude-os-remember` to save insights
- Use `/claude-os-session` to track work

18
SHARING_GUIDE.md
View file

@ -11,9 +11,10 @@ claude-os/
├── templates/ # All reusable templates
│ ├── commands/ # Slash commands (symlinked to ~/.claude/)
│ ├── skills/ # Skills (symlinked to ~/.claude/)
│ ├── agents/ # Agent templates
│ ├── 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
@ -75,11 +76,15 @@ cd claude-os
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
@ -167,6 +172,17 @@ All these work in any initialized project:
- `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

130
install.sh
View file

@ -87,6 +87,129 @@ pip install --quiet --upgrade pip
pip install --quiet -r "${CLAUDE_OS_DIR}/requirements.txt"
echo " ✅ Dependencies installed"
# AI Model Configuration
echo ""
echo "🤖 AI Model Configuration (for Agent-OS)"
echo "========================================="
echo ""
echo "Agent-OS can use AI for advanced features like spec generation."
echo "You have two options:"
echo ""
echo " 1. Local Ollama (FREE, requires 8GB+ RAM)"
echo " 2. OpenAI API (Paid, ~\$0.02/request, works on any machine)"
echo " 3. Skip for now (can configure later)"
echo ""
read -p "Which would you like to use? (1/2/3): " ai_choice
AI_PROVIDER="none"
if [ "$ai_choice" = "1" ]; then
echo ""
echo "📦 Checking for Ollama..."
if command -v ollama &> /dev/null; then
echo " ✅ Ollama found"
AI_PROVIDER="ollama"
# Check if llama2 model is available
if ollama list | grep -q "llama2"; then
echo " ✅ llama2 model available"
else
echo " 📥 Pulling llama2 model (this may take a few minutes)..."
ollama pull llama2
echo " ✅ llama2 model ready"
fi
else
echo " ❌ Ollama not found"
echo ""
echo " To install Ollama:"
echo " 1. Visit: https://ollama.ai"
echo " 2. Download and install"
echo " 3. Run: ollama pull llama2"
echo ""
read -p " Press enter to continue (you can configure Ollama later)..."
AI_PROVIDER="none"
fi
elif [ "$ai_choice" = "2" ]; then
echo ""
echo "🔑 OpenAI API Configuration"
echo ""
read -p "Enter your OpenAI API key: " openai_key
if [ -n "$openai_key" ]; then
# Create or append to .env file
ENV_FILE="${CLAUDE_OS_DIR}/.env"
if grep -q "OPENAI_API_KEY" "$ENV_FILE" 2>/dev/null; then
# Update existing key
sed -i.bak "s/OPENAI_API_KEY=.*/OPENAI_API_KEY=$openai_key/" "$ENV_FILE"
else
# Add new key
echo "OPENAI_API_KEY=$openai_key" >> "$ENV_FILE"
fi
echo " ✅ API key saved to .env"
AI_PROVIDER="openai"
else
echo " ⚠️ No API key provided, skipping"
AI_PROVIDER="none"
fi
else
echo " ⏭️ Skipping AI configuration (can set up later)"
AI_PROVIDER="none"
fi
# Agent-OS Integration (Optional)
echo ""
echo "🎯 Agent-OS Integration (Optional)"
echo "===================================="
echo ""
echo "Agent-OS by Builder Methods (CasJam Media LLC) provides 8 specialized"
echo "agents for spec-driven development workflows:"
echo ""
echo " • spec-initializer • spec-shaper"
echo " • spec-writer • tasks-list-creator"
echo " • implementer • implementation-verifier"
echo " • spec-verifier • product-planner"
echo ""
echo "Agent-OS is MIT licensed and created by Builder Methods."
echo "Repository: https://github.com/builder-methods/agent-os"
echo ""
read -p "Install Agent-OS? (y/n): " install_agent_os
AGENT_OS_INSTALLED="no"
if [ "$install_agent_os" = "y" ] || [ "$install_agent_os" = "Y" ]; then
echo ""
echo "📦 Installing Agent-OS..."
AGENT_OS_DIR="${USER_CLAUDE_DIR}/agents/agent-os"
# Create agents directory if needed
mkdir -p "${USER_CLAUDE_DIR}/agents"
# Clone or update Agent-OS
if [ -d "$AGENT_OS_DIR" ]; then
echo " 📁 Agent-OS directory exists, updating..."
cd "$AGENT_OS_DIR"
git pull origin main 2>/dev/null || git pull origin master 2>/dev/null || echo " ⚠️ Could not update (not a git repo or no connection)"
cd "$CLAUDE_OS_DIR"
else
echo " 📥 Cloning Agent-OS from GitHub..."
git clone https://github.com/builder-methods/agent-os.git "$AGENT_OS_DIR" 2>/dev/null
if [ $? -eq 0 ]; then
echo " ✅ Agent-OS installed successfully"
AGENT_OS_INSTALLED="yes"
else
echo " ❌ Failed to clone Agent-OS (check internet connection)"
echo " You can install it manually later:"
echo " git clone https://github.com/builder-methods/agent-os.git ~/.claude/agents/agent-os"
AGENT_OS_INSTALLED="failed"
fi
fi
if [ -d "$AGENT_OS_DIR" ]; then
AGENT_OS_INSTALLED="yes"
fi
else
echo " ⏭️ Skipping Agent-OS installation"
echo ""
echo " You can install it later with:"
echo " git clone https://github.com/builder-methods/agent-os.git ~/.claude/agents/agent-os"
fi
# Create config file
echo ""
echo "⚙️ Creating configuration..."
@ -105,6 +228,7 @@ if [ ! -f "$CONFIG_FILE" ]; then
"model": "all-MiniLM-L6-v2",
"device": "cpu"
},
"ai_provider": "${AI_PROVIDER}",
"installed_at": "$(date -u +"%Y-%m-%dT%H:%M:%SZ")",
"version": "1.0.0"
}
@ -180,9 +304,15 @@ echo ""
echo "📋 What was set up:"
echo " ✅ Commands linked to ~/.claude/commands/"
echo " ✅ Skills linked to ~/.claude/skills/"
if [ "$AGENT_OS_INSTALLED" = "yes" ]; then
echo " ✅ Agent-OS installed (8 agents by Builder Methods)"
else
echo " ⏭️ Agent-OS not installed (optional)"
fi
echo " ✅ Python virtual environment created"
echo " ✅ Dependencies installed"
echo " ✅ MCP server configured"
echo " ✅ AI provider: ${AI_PROVIDER}"
echo ""
echo "🎯 Next steps:"
echo " 1. Start Claude OS:"