From a744080e659918d32ce0eb1bb406b207b5e272d3 Mon Sep 17 00:00:00 2001 From: Bob Roberts Date: Thu, 11 Dec 2025 12:56:49 -0600 Subject: [PATCH] feat: Add Skills Library and Session Insights (v2.3) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Skills Library - Browse and install 36+ community skills from Anthropic & Superpowers - Local skill templates (Rails, React, testing) - Create custom project-specific skills - Beautiful UI with search and filtering - /claude-os-skills command for CLI management ## Session Insights - Parse Claude Code native .jsonl session files - Extract patterns, decisions, blockers automatically - Track tool usage and file changes - Session summary generation for LLM processing ## Documentation - Updated README with v2.3 features - Updated API_REFERENCE with new endpoints - Added SKILLS_GUIDE.md and SESSIONS_GUIDE.md - Updated GitHub Pages (docs/index.html) - Reorganized docs (internal_docs for private) ## Bug Fixes - Fixed httpx client closure in community skill install - Fixed frontend request format for skill install 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- .coverage | Bin 53248 -> 0 bytes .gitignore | 16 +- README.md | 136 ++- app/core/insight_extractor.py | 312 ++++++ app/core/session_parser.py | 368 +++++++ app/core/skill_manager.py | 992 ++++++++++++++++++ docs/API_REFERENCE.md | 367 ++++++- docs/assets/claude-os-architecture.svg | 289 +++++ docs/guides/AUTH_SETUP.md | 190 ++++ docs/guides/BACKUP_RESTORE_GUIDE.md | 431 ++++++++ docs/guides/HOOK_SETUP_QUICK_START.md | 230 ++++ docs/guides/IDEAL_SESSION_WORKFLOW.md | 373 +++++++ docs/guides/MANDATORY_SESSIONS.md | 548 ++++++++++ docs/guides/PORTS_GUIDE.md | 233 ++++ docs/guides/SESSIONS_GUIDE.md | 415 ++++++++ docs/guides/SESSION_IMPLEMENTATION_SUMMARY.md | 410 ++++++++ docs/guides/SESSION_START_PROTOCOL.md | 390 +++++++ docs/guides/SHARING_GUIDE.md | 315 ++++++ docs/guides/SKILLS_GUIDE.md | 342 ++++++ docs/guides/START_SCRIPTS_GUIDE.md | 295 ++++++ docs/guides/WHAT_IS_CLAUDE_OS.md | 896 ++++++++++++++++ docs/index.html | 687 ++++++++++++ frontend/src/components/SkillsManagement.tsx | 862 +++++++++++++++ frontend/src/pages/MainApp.tsx | 18 +- mcp_server/claude_code_mcp.py | 199 ++++ mcp_server/server.py | 537 ++++++++++ templates/commands/claude-os-session.md | 144 ++- templates/commands/claude-os-skills.md | 262 +++++ .../general/initialize-project/metadata.json | 7 + .../general/initialize-project/skill.md | 163 +++ .../rails/rails-backend/metadata.json | 7 + .../rails/rails-backend/skill.md | 148 +++ .../react/react-patterns/metadata.json | 7 + .../react/react-patterns/skill.md | 262 +++++ .../skill-library/testing/rspec/metadata.json | 7 + .../skill-library/testing/rspec/skill.md | 221 ++++ tests/test_session_parser.py | 260 +++++ 37 files changed, 11294 insertions(+), 45 deletions(-) delete mode 100644 .coverage create mode 100644 app/core/insight_extractor.py create mode 100644 app/core/session_parser.py create mode 100644 app/core/skill_manager.py create mode 100644 docs/assets/claude-os-architecture.svg create mode 100644 docs/guides/AUTH_SETUP.md create mode 100644 docs/guides/BACKUP_RESTORE_GUIDE.md create mode 100644 docs/guides/HOOK_SETUP_QUICK_START.md create mode 100644 docs/guides/IDEAL_SESSION_WORKFLOW.md create mode 100644 docs/guides/MANDATORY_SESSIONS.md create mode 100644 docs/guides/PORTS_GUIDE.md create mode 100644 docs/guides/SESSIONS_GUIDE.md create mode 100644 docs/guides/SESSION_IMPLEMENTATION_SUMMARY.md create mode 100644 docs/guides/SESSION_START_PROTOCOL.md create mode 100644 docs/guides/SHARING_GUIDE.md create mode 100644 docs/guides/SKILLS_GUIDE.md create mode 100644 docs/guides/START_SCRIPTS_GUIDE.md create mode 100644 docs/guides/WHAT_IS_CLAUDE_OS.md create mode 100644 docs/index.html create mode 100644 frontend/src/components/SkillsManagement.tsx create mode 100644 templates/commands/claude-os-skills.md create mode 100644 templates/skill-library/general/initialize-project/metadata.json create mode 100644 templates/skill-library/general/initialize-project/skill.md create mode 100644 templates/skill-library/rails/rails-backend/metadata.json create mode 100644 templates/skill-library/rails/rails-backend/skill.md create mode 100644 templates/skill-library/react/react-patterns/metadata.json create mode 100644 templates/skill-library/react/react-patterns/skill.md create mode 100644 templates/skill-library/testing/rspec/metadata.json create mode 100644 templates/skill-library/testing/rspec/skill.md create mode 100644 tests/test_session_parser.py diff --git a/.coverage b/.coverage deleted file mode 100644 index da0248c54bb5e74d6d7f02a3b9b8b62508f33a25..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 53248 zcmeI4dvFv*8o+yY_WkN4O9&|nGv0|IkYvqCDG5jtkDwfS;SoHQ(`B-mBrCf+>&z?= zF-2CX;z~}T)D!VAKFTVr<3!6lxl+$Ub6P>Y0#T6DDh=l=z7Q-$LK4G$J^M-m@iKo| z(Qj&ZdUmG2ufP8F*WLT=?DX=bSA{f5XqJ_Ts0kO79Kvy=Mi2-g4tRUuo!)G4U`~I4 zlpA(D)}e!x-!aKUuOV*horK=#si$S`9i9ta2i+0J9j;EB=m^3E+>ihgKmthM=S?87 z)NLy$EaYx$*TlxKq$y%hQj&Ymub0);Hq;3XwU=L2CnV1aGn@i!Wo1IGpvY^5n4}2J zp|B)`qD`TosD+{}g4QafbH`PwiA{8H4yHPmv0RsDM}bfiNNG|FsE8?{h^Vv)tEIM5 zJwvKAO$kHlExfJCxjO&&{fELlxXRd(EMbB?ym)^|j6rjfH2O-jY1p_}7UrtwRK ztYoQPji_8Iuu6ajOm|reDt#OQuawrQH;3W-RzQqvvi>;$jUT9hoqJ=h-BwUk#BI7+ zcNB&v&=}Ix%zNad-k$zkEg zb|i3}3Wv3zu4pXR$+$qEB6H|W6k2TsQ>SvbIdnHlwN@&zjc}oKOP*sGO<#&gq8eAy z1IZ5!l4*(TD4FgfsVh*OGMlxacIsHwN#zSvqz>!}o7q;7pU)+dJ%Wu(>}?rQ33evi z1x8H-<2OGhYOTWAwzJb)Kpn~mLlx$~T=vCC}ec8L&yTohv9Pn)Otn}o$54rDg zFL&p=4!iDmUF*tq9(3N}TmS;NApsJhKmeY(T~J^q3D5Y1VPy-+zd9sA{Za={;zr~oF|4(M;6gjpI@f?CG#3jYVU-;@I;{It+IZ4t zKn<|h+G3J!yVaQO8HcH{fbA9og{Br^$vXT3GiWd}f~ zugB-w?rw0s?Vjw)bH3?)#km;-a6*J>7(L*T4PS|Mv5OD|9cIZKQjLJTxm}Dj1)gs{O=xrmpUu{cU{V> zMr=sO|IRsl+>l&4{&!qqPUISq93%d>SMhB|)C`ONZ3b=6#Q)Y>bHZYz(6i!yi_sA* z6S)tM|IL@16E-7uWVB@Bf8HRzVUfIPHZMC2$N#wg-^8A_(Rw6+1dsp{Kmter2_OL^ zfCP{L5F8q?+))e?+Wis&sVS-z$2bGWWx;!AOR$R1dsp{ zKmter2_OL^@KYer>a%c;#1c!_UdM^Q-FIl$;G;e79UQvs`W3c=0-d9glU%t!o*P%1lEuKZ*F!i4~@W3nK z=kFsA=TFOl-1F$hmIIYXhHic0nLX`)|Ht?5KKcE-&#VVYa}|ZlYw~UzXj%F8$-zZ0 zJY6$*=Jk(Dw{ZJv?&bDXu>zrNJIP@s*W5kNvhv`2Z+CXSW$RdGD)EABgS%@RY3@C+ zKVW)lddGupozuzlO+8PWA2th%UbEFG+rRnn*^6hL?}4lfyc>JW7ryn7qv*Ro^!~g0 z%U(L?rFWj|eCd&^^FHr({K5@c7TUU`6Ydj}``q7EbZn{aOBD5Sc5(qZ>L3?xC37xt zL7v}uJ}Bb`&(xdx%&Q*h`*LW`gXFv5uWo#(nyc|RxQ@4$`<;+$m8v|-@nM0I6$Dm+0`Q@R_`AA>=v@)p3}uEUNE(8e%-(O>dx)m z`-hev;|>qJQ=Bu&4q0b9KA4#}^8WEtzkKSsEkrvNzQD%p@^$T%xQ-g3gSZ$pLf|N; z)LzrkLF^rbIHp-4*F3xVq0{fLKmNk0^Zew7PlguXaOBnJh93X=%GpI0xLjlHnm$Wy zzH56&{jJ9@o4x1Qp*_bo4D{?db7#erS!T#^EpH+lPCq&LMfc!ROUEU1Pd~wLEjmf& z(Ec^n?$3Jr2lv-68MxwE%M2beFEg8tNQslArqlmo_cwbjFaK!^zyIT%q-x7?@-27t zv;MxX`^;7ob@NJ;}+_liXZAp*ebz zNA<+*)f2BrPi$^I@woKF< **Latest Release: December 2025** -### ✨ Beautiful New Installer +### 🎯 Skills Library & Community Skills + +Browse and install **36+ skills** from the community with one click! + +```bash +/claude-os-skills # List all skills +/claude-os-skills install pdf # Install from community +``` + +**New Features:** +- 📚 **Local Templates** - Pre-built skills for Rails, React, testing workflows +- 🌐 **Community Skills** - Install from Anthropic Official (16) & Superpowers (20) +- 🔧 **Custom Skills** - Create and share project-specific skills +- 🎨 **Beautiful UI** - Browse, search, and install via web interface + +### 📊 Session Insights + +Parse Claude Code sessions and extract insights automatically! + +**New Features:** +- 🔍 **Session Parser** - Reads Claude Code's native `.jsonl` session files +- 💡 **Insight Extraction** - Extracts patterns, decisions, blockers +- 📈 **Analytics Ready** - Track tool usage and file changes across sessions + +### ✨ Beautiful New Installer (v2.2) The installer got a major upgrade with **Charm CLI (gum)** support! @@ -66,6 +90,7 @@ The installer got a major upgrade with **Charm CLI (gum)** support! | Version | Highlights | |---------|------------| +| **v2.3** | Skills library, community skills, session insights | | **v2.2** | Gum CLI support, safety features, lite model default | | **v2.1** | Unified installer, OpenAI provider support | | **v2.0** | Hybrid tree-sitter indexing, real-time Kanban board | @@ -109,8 +134,10 @@ You work with Claude Code on a feature, close the terminal, come back tomorrow.. ### Key Features -✅ **Lightning-Fast Indexing** - NEW! Tree-sitter hybrid indexing: 10,000 files in 30 seconds (vs 3-5 hours) -✅ **Real-Time Kanban Board** - NEW! Auto-syncing task visualization for agent-os specs (updates within 3 seconds) +✅ **Skills Library** - NEW! Browse & install skills from Anthropic and community repos +✅ **Session Insights** - NEW! Parse Claude Code sessions and extract patterns automatically +✅ **Lightning-Fast Indexing** - Tree-sitter hybrid indexing: 10,000 files in 30 seconds +✅ **Real-Time Kanban Board** - Auto-syncing task visualization for agent-os specs ✅ **One-Command Project Init** - `/claude-os-init` and you're done ✅ **Automatic Context Loading** - Starts every session with relevant memories ✅ **Session Management** - Track work, save progress, resume later @@ -424,13 +451,19 @@ All these work in any initialized project: - **`/claude-os-list`** - List all knowledge bases - **`/claude-os-session [action]`** - Manage development sessions - **`/claude-os-triggers`** - Manage trigger phrases +- **`/claude-os-skills [action]`** - Manage skills (list, install, create) ### Available Skills +**Global Skills (always available):** - **`initialize-project`** - Analyze codebase and generate standards - **`remember-this`** - Auto-save when you say "remember this:" - **`memory`** - Simple memory management +**Community Skills (install via `/claude-os-skills`):** +- **36+ skills** from Anthropic Official and Superpowers repos +- PDF/XLSX manipulation, frontend design, TDD, debugging, code review, and more + --- ## 🤖 Agent-OS: Spec-Driven Development (Optional) @@ -544,6 +577,82 @@ Agent-OS agents deeply integrate with Claude OS: --- +## 🎯 Skills Library + +**Browse, install, and manage Claude Code skills with ease!** + +### What Are Skills? + +Skills are reusable instruction sets that teach Claude specific capabilities. They can include: +- Coding patterns and best practices +- Tool usage workflows +- Domain-specific knowledge +- Development methodologies + +### Skill Types + +**Global Skills** (`~/.claude/skills/`) +- Available in ALL projects +- Core skills: `memory`, `remember-this`, `initialize-project` + +**Project Skills** (`{project}/.claude/skills/`) +- Available only in that project +- Installed from templates or custom created + +**Community Skills** (fetched from GitHub) +- **Anthropic Official** - 16 skills from `anthropics/skills` +- **Superpowers** - 20 skills from `obra/superpowers` + +### Using the Skills Command + +```bash +# List all installed skills +/claude-os-skills + +# Browse local templates +/claude-os-skills templates + +# Install a template to your project +/claude-os-skills install rails-backend + +# Create a custom skill +/claude-os-skills create + +# View skill details +/claude-os-skills view + +# Delete a project skill +/claude-os-skills delete +``` + +### Community Skills (via Web UI) + +1. Open the web UI at http://localhost:5173 +2. Select your project +3. Click the **Skills** tab +4. Click **Install Template** +5. Switch to **Community Skills** tab +6. Browse skills from Anthropic Official and Superpowers +7. Click **Install** on any skill + +### Featured Community Skills + +**From Anthropic Official:** +- `pdf` - Create, edit, and analyze PDF documents +- `xlsx` - Spreadsheet manipulation with formulas +- `frontend-design` - Production-grade UI components +- `mcp-builder` - Create MCP servers +- `doc-coauthoring` - Collaborative documentation + +**From Superpowers:** +- `test-driven-development` - TDD workflow +- `systematic-debugging` - Four-phase debugging framework +- `code-review` - Rigorous code review process +- `git-worktrees` - Isolated development branches +- `brainstorming` - Structured ideation process + +--- + ## 🎯 Spec Tracking & Kanban Board **NEW: Real-time auto-syncing Kanban board for Agent-OS specs!** @@ -722,11 +831,17 @@ claude-os/ │ ├── commands/ # Slash commands (symlinked to ~/.claude/) │ │ ├── claude-os-init.md │ │ ├── claude-os-search.md +│ │ ├── claude-os-skills.md # NEW: Skills management │ │ └── ... -│ ├── skills/ # Skills (symlinked to ~/.claude/) +│ ├── skills/ # Global skills (symlinked to ~/.claude/) │ │ ├── initialize-project/ │ │ ├── remember-this/ │ │ └── memory/ +│ ├── skill-library/ # NEW: Local skill templates +│ │ ├── general/ # General purpose skills +│ │ ├── rails/ # Ruby on Rails skills +│ │ ├── react/ # React/TypeScript skills +│ │ └── testing/ # Testing frameworks │ └── project-files/ # Files created during /claude-os-init │ ├── CLAUDE.md.template │ └── .claude-os/ @@ -1036,7 +1151,8 @@ ollama list | grep llama3.1 claude-os/ ├── templates/ # Shared templates system │ ├── commands/ # Slash commands -│ ├── skills/ # Skills +│ ├── skills/ # Global skills +│ ├── skill-library/ # Local skill templates (NEW) │ └── project-files/ # Files created during init ├── cli/ # CLI tools │ └── claude-os-consolidate.sh @@ -1044,13 +1160,19 @@ claude-os/ │ ├── core/ # Core modules │ │ ├── sqlite_manager.py │ │ ├── rag_engine.py +│ │ ├── skill_manager.py # NEW: Skills management +│ │ ├── session_parser.py # NEW: Session parsing +│ │ ├── insight_extractor.py # NEW: Insight extraction │ │ └── ... │ └── db/ # Database schemas ├── frontend/ # React UI (Vite) │ ├── src/ +│ │ ├── components/ +│ │ │ ├── SkillsManagement.tsx # NEW: Skills UI +│ │ │ └── ... +│ │ └── pages/ │ └── public/ │ └── assets/ -│ └── claude-os-hero.png ├── mcp_server/ # MCP Server (HTTP) │ └── server.py # FastAPI + MCP endpoints ├── data/ # SQLite database diff --git a/app/core/insight_extractor.py b/app/core/insight_extractor.py new file mode 100644 index 0000000..73f913f --- /dev/null +++ b/app/core/insight_extractor.py @@ -0,0 +1,312 @@ +""" +Insight Extractor for Claude Code session transcripts. +Uses LLM to extract valuable insights (decisions, patterns, solutions, blockers). +""" + +import json +import logging +from dataclasses import dataclass +from typing import List, Dict, Any, Optional +import httpx + +from app.core.config import Config + +logger = logging.getLogger(__name__) + + +@dataclass +class Insight: + """An extracted insight from a session.""" + type: str # "decision", "pattern", "solution", or "blocker" + title: str + content: str + confidence: float # 0.0 to 1.0 + metadata: Optional[Dict[str, Any]] = None + + +# Extraction prompt template +EXTRACTION_PROMPT = """Analyze this Claude Code session transcript and extract valuable insights. + +Look for: +1. **Decisions**: Technical choices made with reasoning (e.g., "Decided to use SQLite instead of PostgreSQL because...") +2. **Patterns**: Reusable approaches or code patterns discovered (e.g., "Session files use JSONL format with entry types...") +3. **Solutions**: Bug fixes, error resolutions, implementation approaches (e.g., "Fixed authentication error by updating token refresh logic...") +4. **Blockers**: Problems encountered, whether resolved or not (e.g., "Package installation failed due to Python version mismatch...") + +For each insight: +- Provide a clear title (5-10 words) +- Write detailed content (2-4 sentences with specific technical details) +- Rate confidence (0.0-1.0) based on how explicit/important it is +- Categorize by type + +**Only extract HIGH VALUE insights worth remembering for future sessions.** +Skip routine operations (ls, git status, simple file reads, etc.). +Focus on decisions, learnings, and technical discoveries. + +Session transcript: +{transcript} + +Return valid JSON only (no markdown, no extra text): +{{ + "insights": [ + {{"type": "decision|pattern|solution|blocker", "title": "Clear descriptive title", "content": "Detailed explanation with technical specifics...", "confidence": 0.85}} + ] +}} +""" + + +class InsightExtractor: + """Extract insights from session transcripts using LLM.""" + + def __init__(self, ollama_base_url: Optional[str] = None, model: Optional[str] = None): + """ + Initialize insight extractor. + + Args: + ollama_base_url: Ollama API base URL (defaults to Config.OLLAMA_HOST) + model: LLM model to use (defaults to Config.OLLAMA_MODEL) + """ + self.ollama_base_url = ollama_base_url or Config.OLLAMA_HOST + self.model = model or Config.get_active_llm_model() + + logger.info(f"Initialized InsightExtractor with model: {self.model}") + + async def extract( + self, + session_summary: str, + insight_types: Optional[List[str]] = None + ) -> List[Insight]: + """ + Extract insights from session summary using LLM. + + Args: + session_summary: Condensed session transcript + insight_types: Filter to specific types (defaults to all types) + + Returns: + List of Insight objects + """ + if insight_types is None: + insight_types = ["decision", "pattern", "solution", "blocker"] + + logger.info(f"Extracting insights from session summary ({len(session_summary)} chars)") + + # Build prompt + prompt = EXTRACTION_PROMPT.format(transcript=session_summary) + + # Call Ollama + try: + insights = await self._call_ollama(prompt) + + # Filter by requested types + filtered_insights = [ + i for i in insights + if i.type in insight_types + ] + + logger.info(f"Extracted {len(filtered_insights)} insights (filtered from {len(insights)})") + return filtered_insights + + except Exception as e: + logger.error(f"Failed to extract insights: {e}") + return [] + + async def _call_ollama(self, prompt: str) -> List[Insight]: + """ + Call Ollama API to extract insights. + + Args: + prompt: Extraction prompt with session transcript + + Returns: + List of Insight objects + """ + url = f"{self.ollama_base_url}/api/generate" + + payload = { + "model": self.model, + "prompt": prompt, + "stream": False, + "format": "json", # Request JSON response + "options": { + "temperature": 0.3, # Lower temperature for more focused extraction + "num_predict": 2048, # Allow longer responses for multiple insights + "top_k": 40, + "top_p": 0.9 + } + } + + try: + async with httpx.AsyncClient(timeout=120.0) as client: + response = await client.post(url, json=payload) + response.raise_for_status() + + result = response.json() + response_text = result.get("response", "") + + # Parse JSON response + insights_data = self._parse_llm_response(response_text) + + # Convert to Insight objects + insights = [] + for item in insights_data.get("insights", []): + try: + insight = Insight( + type=item.get("type", "pattern"), + title=item.get("title", "Untitled"), + content=item.get("content", ""), + confidence=float(item.get("confidence", 0.5)) + ) + insights.append(insight) + except (ValueError, KeyError) as e: + logger.warning(f"Failed to parse insight item: {e}") + continue + + return insights + + except httpx.HTTPError as e: + logger.error(f"Ollama API error: {e}") + raise + except Exception as e: + logger.error(f"Unexpected error calling Ollama: {e}") + raise + + def _parse_llm_response(self, response_text: str) -> Dict[str, Any]: + """ + Parse LLM response JSON. + + Handles cases where LLM might include markdown code blocks or extra text. + + Args: + response_text: Raw LLM response + + Returns: + Parsed JSON dict + """ + # Clean up response if it has markdown code blocks + cleaned_text = response_text.strip() + + # Remove markdown code blocks if present + if cleaned_text.startswith("```json"): + cleaned_text = cleaned_text[7:] # Remove ```json + elif cleaned_text.startswith("```"): + cleaned_text = cleaned_text[3:] # Remove ``` + + if cleaned_text.endswith("```"): + cleaned_text = cleaned_text[:-3] + + cleaned_text = cleaned_text.strip() + + try: + return json.loads(cleaned_text) + except json.JSONDecodeError as e: + logger.error(f"Failed to parse LLM JSON response: {e}") + logger.debug(f"Response text: {cleaned_text[:500]}") + # Return empty insights on parse failure + return {"insights": []} + + def filter_by_confidence( + self, + insights: List[Insight], + min_confidence: float = 0.7 + ) -> List[Insight]: + """ + Filter insights by minimum confidence threshold. + + Args: + insights: List of insights + min_confidence: Minimum confidence score (0.0-1.0) + + Returns: + Filtered list of insights + """ + return [i for i in insights if i.confidence >= min_confidence] + + def group_by_type(self, insights: List[Insight]) -> Dict[str, List[Insight]]: + """ + Group insights by type. + + Args: + insights: List of insights + + Returns: + Dict mapping type to list of insights + """ + grouped: Dict[str, List[Insight]] = { + "decision": [], + "pattern": [], + "solution": [], + "blocker": [] + } + + for insight in insights: + if insight.type in grouped: + grouped[insight.type].append(insight) + + return grouped + + def format_for_save(self, insight: Insight, session_id: str) -> str: + """ + Format insight as markdown for saving to knowledge base. + + Args: + insight: Insight to format + session_id: Session ID for metadata + + Returns: + Markdown string + """ + type_emoji = { + "decision": "💎", + "pattern": "🔄", + "solution": "✅", + "blocker": "🚧" + } + + emoji = type_emoji.get(insight.type, "📝") + type_label = insight.type.capitalize() + + markdown = f"""# {emoji} {insight.title} + +**Type:** {type_label} +**Confidence:** {insight.confidence:.2f} +**Source:** Session `{session_id}` + +## Details + +{insight.content} + +--- +*Extracted from Claude Code session on {insight.metadata.get('extracted_date', 'unknown') if insight.metadata else 'unknown'}* +""" + return markdown + + +def extract_insights_sync( + session_summary: str, + insight_types: Optional[List[str]] = None, + min_confidence: float = 0.7 +) -> List[Insight]: + """ + Synchronous wrapper for extract_insights (for non-async contexts). + + Args: + session_summary: Condensed session transcript + insight_types: Filter to specific types + min_confidence: Minimum confidence threshold + + Returns: + List of high-confidence Insight objects + """ + import asyncio + + extractor = InsightExtractor() + + # Run async extraction + loop = asyncio.get_event_loop() + insights = loop.run_until_complete( + extractor.extract(session_summary, insight_types) + ) + + # Filter by confidence + return extractor.filter_by_confidence(insights, min_confidence) diff --git a/app/core/session_parser.py b/app/core/session_parser.py new file mode 100644 index 0000000..9698562 --- /dev/null +++ b/app/core/session_parser.py @@ -0,0 +1,368 @@ +""" +Session Parser for Claude Code built-in session files. +Parses .jsonl session files from ~/.claude/projects/ and extracts structured data. +""" + +import json +import logging +from dataclasses import dataclass, field +from datetime import datetime +from pathlib import Path +from typing import List, Dict, Any, Optional + +logger = logging.getLogger(__name__) + + +@dataclass +class Message: + """A user or assistant message.""" + role: str # "user" or "assistant" + content: str + timestamp: str + uuid: str + parent_uuid: Optional[str] = None + + +@dataclass +class ToolCall: + """A tool call made during the session.""" + tool_name: str + timestamp: str + uuid: str + parent_uuid: Optional[str] = None + input_data: Optional[Dict[str, Any]] = None + + +@dataclass +class FileChange: + """A file modification tracked during the session.""" + file_path: str + timestamp: str + message_id: str + + +@dataclass +class SessionData: + """Parsed session data.""" + session_id: str + session_path: str + messages: List[Message] = field(default_factory=list) + tool_calls: List[ToolCall] = field(default_factory=list) + file_changes: List[FileChange] = field(default_factory=list) + start_time: Optional[str] = None + end_time: Optional[str] = None + git_branch: Optional[str] = None + cwd: Optional[str] = None + total_entries: int = 0 + + +class SessionParser: + """Parse Claude Code built-in session files (.jsonl format).""" + + def __init__(self, session_path: str): + """ + Initialize parser with path to session file. + + Args: + session_path: Path to .jsonl session file + """ + self.path = Path(session_path).expanduser() + if not self.path.exists(): + raise FileNotFoundError(f"Session file not found: {self.path}") + + self.session_id = self.path.stem + self.entries: List[Dict[str, Any]] = [] + + def parse(self) -> SessionData: + """ + Parse JSONL file and return structured session data. + + Returns: + SessionData object with parsed information + """ + logger.info(f"Parsing session file: {self.path}") + + # Read JSONL file + with open(self.path, 'r', encoding='utf-8') as f: + for line in f: + line = line.strip() + if not line: + continue + try: + entry = json.loads(line) + self.entries.append(entry) + except json.JSONDecodeError as e: + logger.warning(f"Failed to parse line: {e}") + continue + + # Build session data + session_data = SessionData( + session_id=self.session_id, + session_path=str(self.path), + total_entries=len(self.entries) + ) + + # Extract metadata from first entry if available + for entry in self.entries: + if entry.get("type") in ["user", "assistant"]: + if not session_data.cwd: + session_data.cwd = entry.get("cwd") + if not session_data.git_branch: + session_data.git_branch = entry.get("gitBranch") + break + + # Parse entries + for entry in self.entries: + entry_type = entry.get("type") + + if entry_type == "user": + self._parse_user_message(entry, session_data) + elif entry_type == "assistant": + self._parse_assistant_message(entry, session_data) + elif entry_type == "file-history-snapshot": + self._parse_file_snapshot(entry, session_data) + + # Set start/end times from messages + if session_data.messages: + session_data.start_time = session_data.messages[0].timestamp + session_data.end_time = session_data.messages[-1].timestamp + + logger.info( + f"Parsed session {self.session_id}: " + f"{len(session_data.messages)} messages, " + f"{len(session_data.tool_calls)} tool calls, " + f"{len(session_data.file_changes)} file changes" + ) + + return session_data + + def _parse_user_message(self, entry: Dict[str, Any], session_data: SessionData) -> None: + """Parse a user message entry.""" + message_obj = entry.get("message", {}) + content = message_obj.get("content", "") + + session_data.messages.append(Message( + role="user", + content=content, + timestamp=entry.get("timestamp", ""), + uuid=entry.get("uuid", ""), + parent_uuid=entry.get("parentUuid") + )) + + def _parse_assistant_message(self, entry: Dict[str, Any], session_data: SessionData) -> None: + """Parse an assistant message entry.""" + message_obj = entry.get("message", {}) + content_parts = message_obj.get("content", []) + + # Extract text content + text_content = [] + for part in content_parts: + if isinstance(part, dict): + if part.get("type") == "text": + text_content.append(part.get("text", "")) + elif part.get("type") == "tool_use": + # Track tool calls + tool_call = ToolCall( + tool_name=part.get("name", ""), + timestamp=entry.get("timestamp", ""), + uuid=entry.get("uuid", ""), + parent_uuid=entry.get("parentUuid"), + input_data=part.get("input") + ) + session_data.tool_calls.append(tool_call) + + # Only add message if there's text content + if text_content: + session_data.messages.append(Message( + role="assistant", + content="\n".join(text_content), + timestamp=entry.get("timestamp", ""), + uuid=entry.get("uuid", ""), + parent_uuid=entry.get("parentUuid") + )) + + def _parse_file_snapshot(self, entry: Dict[str, Any], session_data: SessionData) -> None: + """Parse a file history snapshot entry.""" + snapshot = entry.get("snapshot", {}) + tracked_files = snapshot.get("trackedFileBackups", {}) + + for file_path in tracked_files.keys(): + session_data.file_changes.append(FileChange( + file_path=file_path, + timestamp=snapshot.get("timestamp", ""), + message_id=entry.get("messageId", "") + )) + + def get_conversation(self) -> List[Message]: + """ + Extract user/assistant messages only (no tool calls). + + Returns: + List of Message objects in chronological order + """ + if not self.entries: + session_data = self.parse() + else: + session_data = self.parse() + + return session_data.messages + + def get_tool_results(self) -> List[ToolCall]: + """ + Extract tool calls and results. + + Returns: + List of ToolCall objects + """ + if not self.entries: + session_data = self.parse() + else: + session_data = self.parse() + + return session_data.tool_calls + + def get_file_changes(self) -> List[FileChange]: + """ + Extract file modifications from snapshots. + + Returns: + List of FileChange objects + """ + if not self.entries: + session_data = self.parse() + else: + session_data = self.parse() + + return session_data.file_changes + + def get_summary_for_extraction(self, max_tokens: int = 8000) -> str: + """ + Build condensed conversation summary for LLM extraction. + + Focuses on user/assistant messages and major tool calls. + Truncates to fit within token limit (roughly 4 chars per token). + + Args: + max_tokens: Maximum tokens for summary (default: 8000) + + Returns: + Condensed conversation string + """ + session_data = self.parse() + + summary_parts = [] + summary_parts.append(f"# Session: {self.session_id}") + summary_parts.append(f"Project: {session_data.cwd or 'Unknown'}") + summary_parts.append(f"Branch: {session_data.git_branch or 'Unknown'}") + summary_parts.append(f"Duration: {session_data.start_time} to {session_data.end_time}") + summary_parts.append(f"\n## Conversation ({len(session_data.messages)} messages)\n") + + # Add messages + for msg in session_data.messages: + role_prefix = "USER" if msg.role == "user" else "ASSISTANT" + # Truncate very long messages + content = msg.content[:1000] if len(msg.content) > 1000 else msg.content + summary_parts.append(f"{role_prefix}: {content}\n") + + # Add tool calls summary + if session_data.tool_calls: + summary_parts.append(f"\n## Tool Calls ({len(session_data.tool_calls)})\n") + for tool in session_data.tool_calls[:20]: # Limit to first 20 + summary_parts.append(f"- {tool.tool_name}") + if tool.input_data: + # Show first few input keys + keys = list(tool.input_data.keys())[:3] + summary_parts.append(f" ({', '.join(keys)})") + summary_parts.append("\n") + + # Add file changes summary + if session_data.file_changes: + summary_parts.append(f"\n## Files Modified ({len(session_data.file_changes)})\n") + unique_files = list(set(fc.file_path for fc in session_data.file_changes)) + for file_path in unique_files[:10]: # Limit to first 10 + summary_parts.append(f"- {file_path}\n") + + full_summary = "".join(summary_parts) + + # Truncate if needed (roughly 4 chars per token) + max_chars = max_tokens * 4 + if len(full_summary) > max_chars: + full_summary = full_summary[:max_chars] + "\n\n[... truncated ...]" + + return full_summary + + +def get_project_sessions_dir(project_path: str) -> Path: + """ + Get the Claude Code sessions directory for a project path. + + Claude Code stores sessions in ~/.claude/projects/{encoded-path}/ + where path like "/Users/user/Projects/myapp" becomes "-Users-user-Projects-myapp" + + Args: + project_path: Absolute path to project directory + + Returns: + Path to sessions directory + """ + # Encode path: replace slashes with hyphens + # Claude keeps the leading hyphen (e.g., "-Users-iamanmp-Projects-claude-os") + encoded_path = project_path.replace("/", "-") + + sessions_dir = Path.home() / ".claude" / "projects" / encoded_path + return sessions_dir + + +def list_session_files(project_path: str, limit: int = 50) -> List[Dict[str, Any]]: + """ + List session files for a project. + + Args: + project_path: Absolute path to project directory + limit: Maximum number of sessions to return (most recent first) + + Returns: + List of session file info dicts + """ + sessions_dir = get_project_sessions_dir(project_path) + + if not sessions_dir.exists(): + logger.warning(f"Sessions directory not found: {sessions_dir}") + return [] + + # Find all .jsonl files + session_files = list(sessions_dir.glob("*.jsonl")) + + # Sort by modification time (most recent first) + session_files.sort(key=lambda p: p.stat().st_mtime, reverse=True) + + # Limit results + session_files = session_files[:limit] + + # Build info list + sessions_info = [] + for session_file in session_files: + stat = session_file.stat() + + # Try to get basic info without full parse + session_id = session_file.stem + created_time = datetime.fromtimestamp(stat.st_ctime).isoformat() + modified_time = datetime.fromtimestamp(stat.st_mtime).isoformat() + + # Count lines to estimate message count + try: + with open(session_file, 'r') as f: + line_count = sum(1 for _ in f) + except Exception: + line_count = 0 + + sessions_info.append({ + "id": session_id, + "path": str(session_file), + "created": created_time, + "modified": modified_time, + "size_bytes": stat.st_size, + "estimated_entries": line_count + }) + + return sessions_info diff --git a/app/core/skill_manager.py b/app/core/skill_manager.py new file mode 100644 index 0000000..d577bbb --- /dev/null +++ b/app/core/skill_manager.py @@ -0,0 +1,992 @@ +""" +Skill Manager for Claude Code skills. +Manages global skills (~/.claude/skills/) and project-level skills ({project}/.claude/skills/). +""" + +import json +import logging +import shutil +from dataclasses import dataclass, field +from datetime import datetime +from pathlib import Path +from typing import List, Dict, Any, Optional + +logger = logging.getLogger(__name__) + + +@dataclass +class Skill: + """A Claude Code skill.""" + name: str + path: str + description: str + scope: str # "global" or "project" + source: str # "claude-os-core", "template", "custom" + content: str = "" + enabled: bool = True + category: Optional[str] = None + tags: List[str] = field(default_factory=list) + created: Optional[str] = None + modified: Optional[str] = None + + def to_dict(self) -> Dict[str, Any]: + """Convert to dictionary.""" + return { + "name": self.name, + "path": self.path, + "description": self.description, + "scope": self.scope, + "source": self.source, + "content": self.content, + "enabled": self.enabled, + "category": self.category, + "tags": self.tags, + "created": self.created, + "modified": self.modified + } + + +@dataclass +class SkillTemplate: + """A skill template that can be installed.""" + name: str + category: str + description: str + path: str + tags: List[str] = field(default_factory=list) + version: str = "1.0.0" + + def to_dict(self) -> Dict[str, Any]: + """Convert to dictionary.""" + return { + "name": self.name, + "category": self.category, + "description": self.description, + "path": self.path, + "tags": self.tags, + "version": self.version + } + + +class SkillManager: + """Manage Claude Code skills (global and project-level).""" + + GLOBAL_SKILLS_DIR = Path.home() / ".claude" / "skills" + TEMPLATES_DIR = Path(__file__).parent.parent.parent / "templates" / "skill-library" + + # Core skills that should remain global + CORE_SKILLS = {"memory", "remember-this"} + + def __init__(self, project_path: Optional[str] = None): + """ + Initialize skill manager. + + Args: + project_path: Optional project path for project-level operations + """ + self.project_path = Path(project_path) if project_path else None + + # Ensure global skills directory exists + self.GLOBAL_SKILLS_DIR.mkdir(parents=True, exist_ok=True) + + @property + def project_skills_dir(self) -> Optional[Path]: + """Get project skills directory.""" + if self.project_path: + return self.project_path / ".claude" / "skills" + return None + + def list_global_skills(self) -> List[Skill]: + """ + List skills in ~/.claude/skills/ + + Returns: + List of global Skill objects + """ + skills = [] + + if not self.GLOBAL_SKILLS_DIR.exists(): + return skills + + for item in self.GLOBAL_SKILLS_DIR.iterdir(): + if item.is_dir() or (item.is_symlink() and item.resolve().is_dir()): + try: + skill = self._parse_skill(item, scope="global") + if skill: + skills.append(skill) + except Exception as e: + logger.warning(f"Failed to parse skill {item.name}: {e}") + + return sorted(skills, key=lambda s: s.name) + + def list_project_skills(self) -> List[Skill]: + """ + List skills in {project}/.claude/skills/ + + Returns: + List of project Skill objects + """ + skills = [] + + if not self.project_skills_dir or not self.project_skills_dir.exists(): + return skills + + for item in self.project_skills_dir.iterdir(): + if item.is_dir(): + try: + skill = self._parse_skill(item, scope="project") + if skill: + skills.append(skill) + except Exception as e: + logger.warning(f"Failed to parse project skill {item.name}: {e}") + + return sorted(skills, key=lambda s: s.name) + + def list_all_skills(self, include_content: bool = False) -> Dict[str, List[Skill]]: + """ + List all skills (global and project). + + Args: + include_content: Whether to include skill content + + Returns: + Dict with "global" and "project" skill lists + """ + global_skills = self.list_global_skills() + project_skills = self.list_project_skills() + + if not include_content: + for skill in global_skills + project_skills: + skill.content = "" + + return { + "global": global_skills, + "project": project_skills + } + + def list_templates(self, category: Optional[str] = None) -> List[SkillTemplate]: + """ + List available skill templates. + + Args: + category: Optional category filter + + Returns: + List of SkillTemplate objects + """ + templates = [] + + if not self.TEMPLATES_DIR.exists(): + logger.warning(f"Templates directory not found: {self.TEMPLATES_DIR}") + return templates + + for category_dir in self.TEMPLATES_DIR.iterdir(): + if not category_dir.is_dir(): + continue + + if category and category_dir.name != category: + continue + + for template_dir in category_dir.iterdir(): + if not template_dir.is_dir(): + continue + + try: + template = self._parse_template(template_dir, category_dir.name) + if template: + templates.append(template) + except Exception as e: + logger.warning(f"Failed to parse template {template_dir.name}: {e}") + + return sorted(templates, key=lambda t: (t.category, t.name)) + + def get_template_categories(self) -> List[str]: + """ + Get list of template categories. + + Returns: + List of category names + """ + categories = [] + + if not self.TEMPLATES_DIR.exists(): + return categories + + for item in self.TEMPLATES_DIR.iterdir(): + if item.is_dir(): + categories.append(item.name) + + return sorted(categories) + + def get_skill(self, name: str, scope: str) -> Optional[Skill]: + """ + Get skill details including content. + + Args: + name: Skill name + scope: "global" or "project" + + Returns: + Skill object or None if not found + """ + if scope == "global": + skill_path = self.GLOBAL_SKILLS_DIR / name + elif scope == "project" and self.project_skills_dir: + skill_path = self.project_skills_dir / name + else: + return None + + if not skill_path.exists(): + # Check if it's a symlink + if skill_path.is_symlink(): + skill_path = skill_path.resolve() + else: + return None + + return self._parse_skill(skill_path, scope, include_content=True) + + def install_template( + self, + template_name: str, + custom_name: Optional[str] = None + ) -> Skill: + """ + Install a skill template to the project. + + Args: + template_name: Name of template to install + custom_name: Optional custom name for the installed skill + + Returns: + Installed Skill object + + Raises: + ValueError: If template not found or no project path set + FileExistsError: If skill already exists + """ + if not self.project_path: + raise ValueError("No project path set") + + # Find template + template = None + for t in self.list_templates(): + if t.name == template_name: + template = t + break + + if not template: + raise ValueError(f"Template not found: {template_name}") + + # Determine target name and path + skill_name = custom_name or template_name + target_dir = self.project_skills_dir / skill_name + + if target_dir.exists(): + raise FileExistsError(f"Skill already exists: {skill_name}") + + # Create project skills directory if needed + self.project_skills_dir.mkdir(parents=True, exist_ok=True) + + # Copy template to project + template_path = Path(template.path) + shutil.copytree(template_path, target_dir) + + # Update metadata if renamed + if custom_name: + metadata_file = target_dir / "metadata.json" + if metadata_file.exists(): + with open(metadata_file, 'r') as f: + metadata = json.load(f) + metadata["name"] = custom_name + metadata["source"] = "template" + metadata["installed_from"] = template_name + metadata["installed_at"] = datetime.now().isoformat() + with open(metadata_file, 'w') as f: + json.dump(metadata, f, indent=2) + + logger.info(f"Installed template {template_name} as {skill_name}") + + return self._parse_skill(target_dir, scope="project", include_content=True) + + def create_skill( + self, + name: str, + description: str, + content: str, + category: Optional[str] = None, + tags: Optional[List[str]] = None + ) -> Skill: + """ + Create a custom skill for the project. + + Args: + name: Skill name + description: Skill description + content: Skill content (markdown) + category: Optional category + tags: Optional tags + + Returns: + Created Skill object + + Raises: + ValueError: If no project path set + FileExistsError: If skill already exists + """ + if not self.project_path: + raise ValueError("No project path set") + + target_dir = self.project_skills_dir / name + + if target_dir.exists(): + raise FileExistsError(f"Skill already exists: {name}") + + # Create directories + self.project_skills_dir.mkdir(parents=True, exist_ok=True) + target_dir.mkdir() + + # Write skill content + skill_file = target_dir / "skill.md" + with open(skill_file, 'w') as f: + f.write(content) + + # Write metadata + metadata = { + "name": name, + "description": description, + "category": category, + "tags": tags or [], + "source": "custom", + "created_at": datetime.now().isoformat(), + "version": "1.0.0" + } + metadata_file = target_dir / "metadata.json" + with open(metadata_file, 'w') as f: + json.dump(metadata, f, indent=2) + + logger.info(f"Created custom skill: {name}") + + return self._parse_skill(target_dir, scope="project", include_content=True) + + def update_skill( + self, + name: str, + content: Optional[str] = None, + description: Optional[str] = None, + tags: Optional[List[str]] = None + ) -> Skill: + """ + Update an existing project skill. + + Args: + name: Skill name + content: New content (optional) + description: New description (optional) + tags: New tags (optional) + + Returns: + Updated Skill object + + Raises: + ValueError: If no project path set + FileNotFoundError: If skill not found + """ + if not self.project_path: + raise ValueError("No project path set") + + skill_dir = self.project_skills_dir / name + + if not skill_dir.exists(): + raise FileNotFoundError(f"Skill not found: {name}") + + # Update content + if content is not None: + skill_file = skill_dir / "skill.md" + with open(skill_file, 'w') as f: + f.write(content) + + # Update metadata + metadata_file = skill_dir / "metadata.json" + if metadata_file.exists(): + with open(metadata_file, 'r') as f: + metadata = json.load(f) + else: + metadata = {"name": name} + + if description is not None: + metadata["description"] = description + if tags is not None: + metadata["tags"] = tags + metadata["modified_at"] = datetime.now().isoformat() + + with open(metadata_file, 'w') as f: + json.dump(metadata, f, indent=2) + + logger.info(f"Updated skill: {name}") + + return self._parse_skill(skill_dir, scope="project", include_content=True) + + def delete_skill(self, name: str) -> bool: + """ + Delete a project skill. + + Args: + name: Skill name + + Returns: + True if deleted + + Raises: + ValueError: If no project path set or trying to delete global skill + FileNotFoundError: If skill not found + """ + if not self.project_path: + raise ValueError("No project path set") + + skill_dir = self.project_skills_dir / name + + if not skill_dir.exists(): + raise FileNotFoundError(f"Skill not found: {name}") + + shutil.rmtree(skill_dir) + logger.info(f"Deleted skill: {name}") + + return True + + def _parse_skill( + self, + skill_path: Path, + scope: str, + include_content: bool = False + ) -> Optional[Skill]: + """ + Parse a skill directory into a Skill object. + + Args: + skill_path: Path to skill directory + scope: "global" or "project" + include_content: Whether to include skill content + + Returns: + Skill object or None if invalid + """ + # Resolve symlinks + if skill_path.is_symlink(): + resolved_path = skill_path.resolve() + else: + resolved_path = skill_path + + if not resolved_path.exists() or not resolved_path.is_dir(): + return None + + name = skill_path.name + + # Determine source + if name in self.CORE_SKILLS and scope == "global": + source = "claude-os-core" + elif scope == "global": + source = "template" + else: + source = "custom" + + # Load metadata if exists + metadata_file = resolved_path / "metadata.json" + metadata = {} + if metadata_file.exists(): + try: + with open(metadata_file, 'r') as f: + metadata = json.load(f) + source = metadata.get("source", source) + except Exception as e: + logger.warning(f"Failed to load metadata for {name}: {e}") + + # Load content + content = "" + if include_content: + skill_file = resolved_path / "skill.md" + if skill_file.exists(): + with open(skill_file, 'r') as f: + content = f.read() + else: + # Try other common names + for filename in ["README.md", "index.md", f"{name}.md"]: + alt_file = resolved_path / filename + if alt_file.exists(): + with open(alt_file, 'r') as f: + content = f.read() + break + + # Extract description from content if not in metadata + description = metadata.get("description", "") + if not description and content: + # Try to extract from first paragraph + lines = content.strip().split('\n') + for line in lines: + line = line.strip() + if line and not line.startswith('#'): + description = line[:200] + break + + # Get file stats + stat = resolved_path.stat() + created = datetime.fromtimestamp(stat.st_ctime).isoformat() + modified = datetime.fromtimestamp(stat.st_mtime).isoformat() + + return Skill( + name=name, + path=str(skill_path), + description=description, + scope=scope, + source=source, + content=content, + enabled=True, + category=metadata.get("category"), + tags=metadata.get("tags", []), + created=metadata.get("created_at", created), + modified=metadata.get("modified_at", modified) + ) + + def _parse_template(self, template_path: Path, category: str) -> Optional[SkillTemplate]: + """ + Parse a template directory into a SkillTemplate object. + + Args: + template_path: Path to template directory + category: Template category + + Returns: + SkillTemplate object or None if invalid + """ + if not template_path.is_dir(): + return None + + name = template_path.name + + # Load metadata + metadata_file = template_path / "metadata.json" + metadata = {} + if metadata_file.exists(): + try: + with open(metadata_file, 'r') as f: + metadata = json.load(f) + except Exception as e: + logger.warning(f"Failed to load template metadata for {name}: {e}") + + # Get description + description = metadata.get("description", "") + if not description: + # Try to extract from skill.md + skill_file = template_path / "skill.md" + if skill_file.exists(): + with open(skill_file, 'r') as f: + content = f.read() + lines = content.strip().split('\n') + for line in lines: + line = line.strip() + if line and not line.startswith('#'): + description = line[:200] + break + + return SkillTemplate( + name=name, + category=category, + description=description, + path=str(template_path), + tags=metadata.get("tags", []), + version=metadata.get("version", "1.0.0") + ) + + +# Convenience functions + +def list_skills(project_path: Optional[str] = None) -> Dict[str, List[Dict]]: + """ + List all skills. + + Args: + project_path: Optional project path + + Returns: + Dict with global and project skill lists as dicts + """ + manager = SkillManager(project_path) + skills = manager.list_all_skills() + + return { + "global": [s.to_dict() for s in skills["global"]], + "project": [s.to_dict() for s in skills["project"]] + } + + +def list_skill_templates(category: Optional[str] = None) -> List[Dict]: + """ + List available skill templates. + + Args: + category: Optional category filter + + Returns: + List of template dicts + """ + manager = SkillManager() + templates = manager.list_templates(category) + return [t.to_dict() for t in templates] + + +# ============================================================================ +# COMMUNITY SKILLS - Fetch from external GitHub repositories +# ============================================================================ + +import httpx +import base64 +import re +import tempfile + +@dataclass +class CommunitySkill: + """A skill from an external community repository.""" + name: str + description: str + source: str # "anthropic", "superpowers", etc. + repo: str # Full repo path e.g., "anthropics/skills" + path: str # Path within repo e.g., "skills/frontend-design" + tags: List[str] = field(default_factory=list) + url: str = "" # GitHub URL + + def to_dict(self) -> Dict[str, Any]: + """Convert to dictionary.""" + return { + "name": self.name, + "description": self.description, + "source": self.source, + "repo": self.repo, + "path": self.path, + "tags": self.tags, + "url": self.url + } + + +# Community skill sources configuration +COMMUNITY_SOURCES = { + "anthropic": { + "repo": "anthropics/skills", + "skills_path": "skills", + "name": "Anthropic Official", + "description": "Official skills from Anthropic" + }, + "superpowers": { + "repo": "obra/superpowers", + "skills_path": "skills", + "name": "Superpowers", + "description": "Battle-tested skills for TDD, debugging, and collaboration" + } +} + + +class CommunitySkillsManager: + """Fetch and install skills from community GitHub repositories.""" + + GITHUB_API = "https://api.github.com" + GITHUB_RAW = "https://raw.githubusercontent.com" + CACHE_TTL = 3600 # Cache for 1 hour + + def __init__(self): + self._cache: Dict[str, Any] = {} + self._cache_times: Dict[str, float] = {} + + def _is_cache_valid(self, key: str) -> bool: + """Check if cache entry is still valid.""" + if key not in self._cache_times: + return False + import time + return (time.time() - self._cache_times[key]) < self.CACHE_TTL + + def _set_cache(self, key: str, value: Any) -> None: + """Set cache entry.""" + import time + self._cache[key] = value + self._cache_times[key] = time.time() + + async def list_community_skills(self, source: Optional[str] = None) -> List[CommunitySkill]: + """ + List skills from community repositories. + + Args: + source: Optional source filter ("anthropic", "superpowers", etc.) + + Returns: + List of CommunitySkill objects + """ + skills = [] + sources = {source: COMMUNITY_SOURCES[source]} if source else COMMUNITY_SOURCES + + for source_key, config in sources.items(): + try: + source_skills = await self._fetch_skills_from_repo(source_key, config) + skills.extend(source_skills) + except Exception as e: + logger.warning(f"Failed to fetch skills from {source_key}: {e}") + + return skills + + async def _fetch_skills_from_repo( + self, + source_key: str, + config: Dict[str, str] + ) -> List[CommunitySkill]: + """Fetch skill list from a GitHub repository.""" + cache_key = f"skills_{source_key}" + if self._is_cache_valid(cache_key): + return self._cache[cache_key] + + repo = config["repo"] + skills_path = config["skills_path"] + + # Fetch directory listing from GitHub API + url = f"{self.GITHUB_API}/repos/{repo}/contents/{skills_path}" + + async with httpx.AsyncClient() as client: + response = await client.get(url, timeout=15.0) + if response.status_code != 200: + logger.error(f"GitHub API error for {repo}: {response.status_code}") + return [] + + items = response.json() + + skills = [] + for item in items: + if item.get("type") != "dir": + continue + + skill_name = item["name"] + skill_path = f"{skills_path}/{skill_name}" + + # Try to fetch SKILL.md to get description + description = await self._fetch_skill_description(repo, skill_path) + + skill = CommunitySkill( + name=skill_name, + description=description, + source=source_key, + repo=repo, + path=skill_path, + tags=self._infer_tags(skill_name, description), + url=f"https://github.com/{repo}/tree/main/{skill_path}" + ) + skills.append(skill) + + self._set_cache(cache_key, skills) + return skills + + async def _fetch_skill_description(self, repo: str, skill_path: str) -> str: + """Fetch skill description from SKILL.md.""" + # Try both SKILL.md and skill.md + for filename in ["SKILL.md", "skill.md"]: + url = f"{self.GITHUB_RAW}/{repo}/main/{skill_path}/{filename}" + + try: + async with httpx.AsyncClient() as client: + response = await client.get(url, timeout=10.0) + if response.status_code == 200: + content = response.text + # Extract description from YAML frontmatter or first paragraph + return self._extract_description(content) + except Exception: + continue + + return "" + + def _extract_description(self, content: str) -> str: + """Extract description from skill markdown content.""" + # Try YAML frontmatter first + frontmatter_match = re.match(r'^---\s*\n(.*?)\n---', content, re.DOTALL) + if frontmatter_match: + frontmatter = frontmatter_match.group(1) + desc_match = re.search(r'description:\s*["\']?([^"\'\n]+)["\']?', frontmatter) + if desc_match: + return desc_match.group(1).strip()[:200] + + # Fall back to first non-header paragraph + lines = content.split('\n') + for line in lines: + line = line.strip() + if line and not line.startswith('#') and not line.startswith('---'): + return line[:200] + + return "" + + def _infer_tags(self, name: str, description: str) -> List[str]: + """Infer tags from skill name and description.""" + tags = [] + text = f"{name} {description}".lower() + + tag_keywords = { + "testing": ["test", "tdd", "spec", "jest", "pytest", "rspec"], + "debugging": ["debug", "error", "fix", "trace"], + "frontend": ["frontend", "react", "vue", "ui", "css", "design"], + "backend": ["backend", "api", "server", "database"], + "documentation": ["doc", "readme", "markdown", "write"], + "automation": ["automat", "script", "workflow"], + "design": ["design", "canvas", "art", "visual", "brand"], + "git": ["git", "commit", "branch", "merge"], + } + + for tag, keywords in tag_keywords.items(): + if any(kw in text for kw in keywords): + tags.append(tag) + + return tags + + async def get_skill_content(self, repo: str, skill_path: str) -> Dict[str, str]: + """ + Fetch full skill content from GitHub. + + Returns: + Dict with filename -> content mappings + """ + # Get list of files in skill directory + url = f"{self.GITHUB_API}/repos/{repo}/contents/{skill_path}" + + async with httpx.AsyncClient() as client: + response = await client.get(url, timeout=15.0) + if response.status_code != 200: + raise ValueError(f"Failed to fetch skill: {response.status_code}") + + items = response.json() + + contents = {} + for item in items: + if item.get("type") != "file": + continue + + filename = item["name"] + # Fetch file content + file_url = f"{self.GITHUB_RAW}/{repo}/main/{skill_path}/{filename}" + + file_response = await client.get(file_url, timeout=10.0) + if file_response.status_code == 200: + contents[filename] = file_response.text + + return contents + + async def install_community_skill( + self, + skill: CommunitySkill, + project_path: str, + custom_name: Optional[str] = None + ) -> Skill: + """ + Install a community skill to a project. + + Args: + skill: CommunitySkill to install + project_path: Target project path + custom_name: Optional custom name for the skill + + Returns: + Installed Skill object + """ + # Fetch skill content + contents = await self.get_skill_content(skill.repo, skill.path) + + if not contents: + raise ValueError(f"No content found for skill: {skill.name}") + + # Determine target directory + skill_name = custom_name or skill.name + target_dir = Path(project_path) / ".claude" / "skills" / skill_name + + if target_dir.exists(): + raise FileExistsError(f"Skill already exists: {skill_name}") + + # Create directory + target_dir.mkdir(parents=True, exist_ok=True) + + # Write files + for filename, content in contents.items(): + # Normalize SKILL.md to skill.md + if filename.upper() == "SKILL.MD": + filename = "skill.md" + + file_path = target_dir / filename + with open(file_path, 'w') as f: + f.write(content) + + # Create/update metadata + metadata_file = target_dir / "metadata.json" + metadata = { + "name": skill_name, + "description": skill.description, + "source": f"community:{skill.source}", + "original_repo": skill.repo, + "original_path": skill.path, + "installed_at": datetime.now().isoformat(), + "tags": skill.tags + } + + with open(metadata_file, 'w') as f: + json.dump(metadata, f, indent=2) + + logger.info(f"Installed community skill {skill.name} from {skill.source}") + + # Return as Skill object + manager = SkillManager(project_path) + return manager._parse_skill(target_dir, scope="project", include_content=True) + + +# Singleton instance +_community_manager: Optional[CommunitySkillsManager] = None + + +def get_community_manager() -> CommunitySkillsManager: + """Get or create the community skills manager singleton.""" + global _community_manager + if _community_manager is None: + _community_manager = CommunitySkillsManager() + return _community_manager + + +async def list_community_skills(source: Optional[str] = None) -> List[Dict]: + """ + List available community skills. + + Args: + source: Optional source filter + + Returns: + List of community skill dicts + """ + manager = get_community_manager() + skills = await manager.list_community_skills(source) + return [s.to_dict() for s in skills] + + +async def install_community_skill( + source: str, + skill_name: str, + project_path: str, + custom_name: Optional[str] = None +) -> Dict: + """ + Install a community skill to a project. + + Args: + source: Source key ("anthropic", "superpowers") + skill_name: Name of the skill + project_path: Target project path + custom_name: Optional custom name + + Returns: + Installed skill dict + """ + manager = get_community_manager() + + # Find the skill + skills = await manager.list_community_skills(source) + skill = next((s for s in skills if s.name == skill_name), None) + + if not skill: + raise ValueError(f"Skill not found: {skill_name} in {source}") + + installed = await manager.install_community_skill(skill, project_path, custom_name) + return installed.to_dict() diff --git a/docs/API_REFERENCE.md b/docs/API_REFERENCE.md index 2347e41..3668221 100644 --- a/docs/API_REFERENCE.md +++ b/docs/API_REFERENCE.md @@ -11,13 +11,15 @@ Complete reference for all Claude OS MCP Server API endpoints. 1. [Knowledge Base Operations](#knowledge-base-operations) 2. [Hybrid Indexing](#hybrid-indexing-new) 3. [Project Management](#project-management) -4. [Agent-OS Spec Tracking](#agent-os-spec-tracking-new) -5. [Real-Time Spec Watcher](#real-time-spec-watcher-new) -6. [Hooks System](#hooks-system) -7. [File Watcher](#file-watcher) -8. [Authentication](#authentication) -9. [Utilities](#utilities) -10. [Health Check](#health-check) +4. [Skills Management](#skills-management-new) +5. [Session Parsing](#session-parsing-new) +6. [Agent-OS Spec Tracking](#agent-os-spec-tracking-new) +7. [Real-Time Spec Watcher](#real-time-spec-watcher-new) +8. [Hooks System](#hooks-system) +9. [File Watcher](#file-watcher) +10. [Authentication](#authentication) +11. [Utilities](#utilities) +12. [Health Check](#health-check) --- @@ -495,6 +497,353 @@ DELETE /api/projects/{id} --- +## Skills Management (NEW) + +Manage Claude Code skills - list, install, create, and configure. + +### List All Skills +```http +GET /api/skills?project_path=/path/to/project&include_content=false +``` + +Returns global and project-level skills. + +**Response:** +```json +{ + "global": [ + { + "name": "memory", + "path": "/Users/username/.claude/skills/memory", + "description": "Save and recall information", + "scope": "global", + "source": "custom", + "enabled": true, + "category": null, + "tags": [] + } + ], + "project": [ + { + "name": "rails-backend", + "path": "/path/to/project/.claude/skills/rails-backend", + "description": "Rails patterns and service objects", + "scope": "project", + "source": "template", + "enabled": true, + "category": "rails", + "tags": ["ruby", "rails", "backend"] + } + ] +} +``` + +--- + +### List Skill Templates +```http +GET /api/skills/templates +``` + +Returns available local templates organized by category. + +**Response:** +```json +{ + "templates": [ + { + "name": "rails-backend", + "category": "rails", + "description": "Rails patterns and service objects", + "path": "/path/to/claude-os/templates/skill-library/rails/rails-backend", + "tags": ["ruby", "rails", "backend"], + "version": "1.0.0" + } + ], + "categories": ["general", "rails", "react", "testing"] +} +``` + +--- + +### Install Skill Template +```http +POST /api/skills/install?project_path=/path/to/project +Content-Type: application/json + +{ + "template_name": "rails-backend" +} +``` + +**Response:** +```json +{ + "success": true, + "skill": { + "name": "rails-backend", + "path": "/path/to/project/.claude/skills/rails-backend", + "scope": "project", + "source": "template" + }, + "message": "Installed skill 'rails-backend' to project" +} +``` + +--- + +### Create Custom Skill +```http +POST /api/skills?project_path=/path/to/project +Content-Type: application/json + +{ + "name": "my-skill", + "description": "My custom skill", + "content": "# My Skill\n\nSkill instructions here...", + "category": "custom", + "tags": ["custom"] +} +``` + +**Response:** +```json +{ + "success": true, + "skill": { + "name": "my-skill", + "path": "/path/to/project/.claude/skills/my-skill", + "scope": "project", + "source": "custom" + } +} +``` + +--- + +### Get Skill Details +```http +GET /api/skills/{scope}/{name}?project_path=/path/to/project +``` + +**Parameters:** +- `scope`: `global` or `project` +- `name`: Skill name + +**Response:** +```json +{ + "name": "rails-backend", + "path": "/path/to/project/.claude/skills/rails-backend", + "description": "Rails patterns and service objects", + "scope": "project", + "source": "template", + "content": "# Rails Backend\n\n...", + "enabled": true, + "category": "rails", + "tags": ["ruby", "rails", "backend"], + "created": "2025-12-11T10:00:00Z", + "modified": "2025-12-11T10:00:00Z" +} +``` + +--- + +### Delete Skill +```http +DELETE /api/skills/{name}?project_path=/path/to/project +``` + +**Response:** +```json +{ + "success": true, + "message": "Deleted skill 'my-skill' from project" +} +``` + +--- + +### List Community Sources +```http +GET /api/skills/community/sources +``` + +**Response:** +```json +{ + "sources": { + "anthropic": { + "repo": "anthropics/skills", + "skills_path": "skills", + "name": "Anthropic Official", + "description": "Official skills from Anthropic" + }, + "superpowers": { + "repo": "obra/superpowers", + "skills_path": "skills", + "name": "Superpowers", + "description": "Battle-tested skills for TDD, debugging, and collaboration" + } + } +} +``` + +--- + +### List Community Skills +```http +GET /api/skills/community?source=anthropic +``` + +**Parameters:** +- `source` (optional): Filter by source (`anthropic`, `superpowers`) + +**Response:** +```json +{ + "skills": [ + { + "name": "pdf", + "source": "anthropic", + "repo": "anthropics/skills", + "path": "skills/pdf", + "description": "Comprehensive PDF manipulation toolkit...", + "readme_url": "https://github.com/anthropics/skills/tree/main/skills/pdf", + "raw_url": "https://raw.githubusercontent.com/anthropics/skills/main/skills/pdf" + } + ], + "sources": {...}, + "total": 36 +} +``` + +--- + +### Install Community Skill +```http +POST /api/skills/community/install?project_path=/path/to/project +Content-Type: application/json + +{ + "name": "pdf", + "source": "anthropic", + "repo": "anthropics/skills", + "path": "skills/pdf", + "description": "PDF manipulation toolkit", + "readme_url": "https://github.com/anthropics/skills/tree/main/skills/pdf", + "raw_url": "https://raw.githubusercontent.com/anthropics/skills/main/skills/pdf" +} +``` + +**Response:** +```json +{ + "success": true, + "skill": { + "name": "pdf", + "path": "/path/to/project/.claude/skills/pdf", + "scope": "project", + "source": "community:anthropic" + }, + "message": "Installed community skill 'pdf' from anthropic" +} +``` + +--- + +## Session Parsing (NEW) + +Parse Claude Code session files and extract insights. + +### List Project Sessions +```http +GET /api/sessions?project_path=/path/to/project&limit=10 +``` + +**Response:** +```json +{ + "sessions": [ + { + "session_id": "abc123", + "session_path": "/Users/username/.claude/projects/-path-to-project/abc123.jsonl", + "start_time": "2025-12-11T10:00:00Z", + "end_time": "2025-12-11T11:30:00Z", + "message_count": 24, + "tool_calls": 15, + "file_changes": 8 + } + ], + "total": 42 +} +``` + +--- + +### Get Session Details +```http +GET /api/sessions/{session_id}?project_path=/path/to/project +``` + +**Response:** +```json +{ + "session_id": "abc123", + "session_path": "/Users/username/.claude/projects/-path-to-project/abc123.jsonl", + "messages": [ + { + "role": "user", + "content": "Help me fix the authentication bug", + "timestamp": "2025-12-11T10:00:00Z", + "uuid": "msg-001" + }, + { + "role": "assistant", + "content": "I'll help you fix that...", + "timestamp": "2025-12-11T10:00:05Z", + "uuid": "msg-002" + } + ], + "tool_calls": [ + { + "tool_name": "Read", + "timestamp": "2025-12-11T10:00:10Z", + "input_data": {"file_path": "/path/to/auth.py"} + } + ], + "file_changes": [ + { + "file_path": "/path/to/auth.py", + "timestamp": "2025-12-11T10:05:00Z" + } + ], + "start_time": "2025-12-11T10:00:00Z", + "end_time": "2025-12-11T11:30:00Z", + "git_branch": "fix-auth-bug", + "cwd": "/path/to/project" +} +``` + +--- + +### Get Session Summary +```http +GET /api/sessions/{session_id}/summary?project_path=/path/to/project&max_tokens=500 +``` + +Returns a formatted summary suitable for LLM processing. + +**Response:** +```json +{ + "session_id": "abc123", + "summary": "# Session: abc123\nProject: /path/to/project\nBranch: fix-auth-bug\n\n## Conversation (24 messages)\n..." +} +``` + +--- + ## Agent-OS Spec Tracking (NEW) Real-time tracking and visualization of agent-os specifications and tasks through the Kanban board. @@ -1102,5 +1451,5 @@ For issues, questions, or contributions: --- -**Last Updated:** 2025-10-31 -**API Version:** 1.0 +**Last Updated:** 2025-12-11 +**API Version:** 2.3 diff --git a/docs/assets/claude-os-architecture.svg b/docs/assets/claude-os-architecture.svg new file mode 100644 index 0000000..44808e6 --- /dev/null +++ b/docs/assets/claude-os-architecture.svg @@ -0,0 +1,289 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + CLAUDE OS ARCHITECTURE + + + + + + + + + + + + + + + Semantic Knowledge Base + + + SQLite + sqlite-vec + + + 800+ indexed chunks + + + Vector embeddings + + + + + + + + + + + 🧠 Real-Time Learning + + + Redis Pub/Sub + + + <1ms latency + + + 10+ patterns + + + (Cyan glow) + + + + + + + + + + + 💾 Memory MCP + + + Persistent Memory + + + Instant Recall + + + Natural Language + + + (Purple glow) + + + + + + + + + + + 🔍 Analyze-Project + + + Git Hooks + + + Auto-Index + + + Smart Docs + + + (Pink glow) + + + + + + + + + + + 🎯 Session Management + + + Auto Resume + + + Context Preservation + + + Zero Cold Start + + + (Purple-pink glow) + + + + + + + + + + + 📚 Semantic Search + + + Vector Similarity + + + Code Understanding + + + Pattern Recognition + + + (Cyan-purple glow) + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + MCP Server + + + (port 8051) + + + + + + + + + + Claude Code + + + Interface + + + + + + + + + + Developer + + + (You!) + + + + + + + + + + + + + Data Flow Pipeline: + + + Git Commit → 3s indexing → SQLite → MCP → Claude → You + + + + + + + + + + + diff --git a/docs/guides/AUTH_SETUP.md b/docs/guides/AUTH_SETUP.md new file mode 100644 index 0000000..abda42f --- /dev/null +++ b/docs/guides/AUTH_SETUP.md @@ -0,0 +1,190 @@ +# Claude OS Authentication Setup + +Simple email/password authentication to keep strangers out of your Claude OS frontend. + +## Features + +✅ **Optional Authentication** - Disabled by default, enable when needed +✅ **Environment-based** - No database required for user management +✅ **JWT Tokens** - 7-day token expiration +✅ **Secure** - Bcrypt password hashing +✅ **Simple** - Single user account via environment variables + +## Quick Start + +### 1. Enable Authentication + +Set environment variables in your `.env` file or server environment: + +```bash +# Required: Email for login +CLAUDE_OS_EMAIL=admin@example.com + +# Option 1: Plain password (development only - will be hashed automatically) +CLAUDE_OS_PASSWORD=your_secure_password_here + +# Option 2: Pre-hashed password (recommended for production) +CLAUDE_OS_PASSWORD_HASH=$2b$12$LQv3c1yqBWVHxkd0LHAkCOYz6TtxMQJqhN8/LewY5hhA82jdg8jpu + +# Optional: Custom secret key for JWT (auto-generated if not set) +CLAUDE_OS_SECRET_KEY=your-super-secret-key-min-32-chars +``` + +### 2. Generate Password Hash (Production) + +For production, use a pre-hashed password instead of plain text: + +```bash +# Install dependencies first +cd ~/Projects/claude-os +source venv/bin/activate +pip install -r requirements.txt + +# Generate hash +python3 -c "from passlib.context import CryptContext; print(CryptContext(schemes=['bcrypt']).hash('your_password_here'))" +``` + +Copy the output and use it as `CLAUDE_OS_PASSWORD_HASH` in your `.env` file. + +### 3. Restart Claude OS + +```bash +# Local (Mac) +./stop.sh +./start.sh + +# Production Server +sudo systemctl restart claude-os +``` + +### 4. Login + +Visit your Claude OS frontend: +- Local: http://localhost:5173/login +- Production: https://your-domain.com/login + +Use the email and password you configured. + +## Production Deployment + +### Server Environment Variables + +Add to `/opt/claude-os/.env`: + +```bash +CLAUDE_OS_EMAIL=admin@pistn.com +CLAUDE_OS_PASSWORD_HASH=$2b$12$xyz... # Generated hash +CLAUDE_OS_SECRET_KEY=your-32-char-secret +``` + +Restart the service: + +```bash +sudo systemctl restart claude-os +``` + +## Disable Authentication + +To disable authentication (open access): + +```bash +# Remove or comment out these variables in .env: +# CLAUDE_OS_EMAIL=... +# CLAUDE_OS_PASSWORD=... +# CLAUDE_OS_PASSWORD_HASH=... +``` + +Restart Claude OS. The frontend will allow access without login. + +## How It Works + +### Backend (FastAPI) + +- **`/api/auth/login`** - Login endpoint, returns JWT token +- **`/api/auth/me`** - Get current user info +- **`/api/auth/status`** - Check if authentication is enabled + +### Frontend (React) + +- **Login Page** - Beautiful gradient login form +- **Auth Context** - Manages authentication state +- **Protected Routes** - Automatically redirects to login if not authenticated +- **Token Storage** - JWT stored in localStorage (7-day expiration) + +### Security Features + +✅ **Bcrypt hashing** - Industry-standard password encryption +✅ **JWT tokens** - Stateless authentication +✅ **Automatic expiration** - Tokens expire after 7 days +✅ **HTTPS recommended** - Use SSL in production +✅ **No database needed** - Single user, environment-based + +## Troubleshooting + +### "Authentication is not configured" + +You haven't set the `CLAUDE_OS_EMAIL` environment variable. Set it and restart. + +### "Incorrect email or password" + +Check your `.env` file: +- Email matches exactly (case-sensitive) +- If using `CLAUDE_OS_PASSWORD`, make sure it's correct +- If using `CLAUDE_OS_PASSWORD_HASH`, regenerate the hash + +### Login page doesn't appear + +Make sure your Claude OS frontend is running: + +```bash +# Local development +cd frontend +npm run dev + +# Production (should be served by Nginx) +curl http://localhost:5173 +``` + +### Token expired + +Tokens last 7 days. Just login again to get a new token. + +## Multiple Users + +This system is designed for single-user access. For multiple users: + +1. **Simple approach**: Share one account with your team +2. **Advanced approach**: Extend the auth system to use a database (requires custom implementation) + +For most teams deploying Claude OS internally, a single shared account is sufficient since it's: +- Behind your firewall +- For trusted team members only +- Just to keep strangers out (not enterprise-grade auth) + +## Security Best Practices + +### Development (Local) + +```bash +CLAUDE_OS_EMAIL=dev@localhost +CLAUDE_OS_PASSWORD=dev123 +``` + +Fine for local development. Password is hashed automatically. + +### Production (Server) + +```bash +CLAUDE_OS_EMAIL=admin@yourcompany.com +CLAUDE_OS_PASSWORD_HASH=$2b$12$xyz... # Pre-hashed +CLAUDE_OS_SECRET_KEY=randomly-generated-32-char-secret +``` + +✅ **Use hashed passwords** +✅ **Use strong secret keys** +✅ **Use HTTPS/SSL** +✅ **Rotate passwords periodically** + +--- + +**Questions?** Check the main Claude OS README or open an issue on GitHub. diff --git a/docs/guides/BACKUP_RESTORE_GUIDE.md b/docs/guides/BACKUP_RESTORE_GUIDE.md new file mode 100644 index 0000000..62d0ca2 --- /dev/null +++ b/docs/guides/BACKUP_RESTORE_GUIDE.md @@ -0,0 +1,431 @@ +# Claude OS Backup & Restore Guide + +This guide explains how to safely backup and restore your Claude OS installation, perfect for testing fresh installations without losing data. + +## Quick Start + +### 1. Backup Your Current Setup + +```bash +./scripts/backup_claude_os.sh +``` + +This creates a timestamped backup in `backups/backup_YYYYMMDD_HHMMSS/` containing: +- SQLite database (all projects, knowledge bases, documents) +- Configuration files (.env, JSON configs) +- Uploaded documents +- Recent log files +- Symlink information + +**Output example:** +``` +Backup location: /Users/iamanmp/Projects/claude-os/backups/backup_20251101_135211 +Backup size: 125M +Backup timestamp: 20251101_135211 + +To restore this backup later: + ./scripts/restore_claude_os.sh 20251101_135211 +``` + +### 2. Test Fresh Installation + +Now you can safely test the installation process: + +```bash +# Option 1: Test quick install +./install.sh + +# Option 2: Test full setup +./setup.sh +``` + +### 3. Restore Your Data + +If you need to restore your backup: + +```bash +./scripts/restore_claude_os.sh 20251101_135211 +``` + +Replace `20251101_135211` with your actual backup timestamp. + +--- + +## What Gets Backed Up? + +### Critical Data (Automatically Backed Up) + +1. **SQLite Database** (`data/claude-os.db`) + - All projects + - All knowledge bases + - All documents and embeddings + - Search history + - Typically 100-200MB + +2. **Configuration Files** + - `.env` - Environment variables (Ollama settings, API keys, etc.) + - `claude-os-config.json` - Project configuration + - `claude-os-state.json` - Current session state + - `claude-os-triggers.json` - Custom trigger phrases + +3. **Uploaded Documents** (`data/uploads/`) + - Any files uploaded through the UI + +4. **Recent Logs** (`logs/`) + - Recent log files (< 10MB each) + - Useful for debugging + +5. **Symlink Information** + - Record of `~/.claude/commands/` symlinks + - Record of `~/.claude/skills/` symlinks + - For reference only (recreated by `install.sh`) + +### What's NOT Backed Up (No Need) + +- `node_modules/` - Reinstalled from package.json +- `venv/` - Recreated during installation +- Python packages - Reinstalled from requirements.txt +- Ollama models - Remain in system location +- Templates - Already in git repository +- Large log files (> 10MB) + +--- + +## Detailed Usage + +### Backup Command + +```bash +./scripts/backup_claude_os.sh +``` + +**What it does:** +1. Creates timestamped backup directory +2. Copies all critical files +3. Records symlink state +4. Creates manifest file +5. Shows backup summary + +**No arguments needed** - timestamps are automatic. + +### Restore Command + +```bash +./scripts/restore_claude_os.sh +``` + +**Examples:** +```bash +# Restore specific backup +./scripts/restore_claude_os.sh 20251101_135211 + +# List available backups +./scripts/restore_claude_os.sh +``` + +**What it does:** +1. Verifies backup exists +2. Shows manifest +3. Asks for confirmation (press Enter to continue) +4. Restores all files +5. Provides next steps + +**⚠️ WARNING:** Restore will **overwrite** your current data! Make a new backup first if you want to keep current state. + +--- + +## Testing Fresh Installations + +### Recommended Workflow + +1. **Backup first:** + ```bash + ./scripts/backup_claude_os.sh + ``` + +2. **Stop all services:** + ```bash + ./stop_all_services.sh + ``` + +3. **Clean up (optional but thorough):** + ```bash + # Remove symlinks (will be recreated) + rm ~/.claude/commands/claude-os-*.md + rm ~/.claude/skills/memory + rm ~/.claude/skills/initialize-project + rm ~/.claude/skills/remember-this + + # Remove virtual environment + rm -rf venv venv_py312 venv_py313 + ``` + +4. **Test installation:** + ```bash + # Test quick install + ./install.sh + + # OR test full setup + ./setup.sh + ``` + +5. **Verify it works:** + ```bash + # Start services + ./start.sh + + # Check health + curl http://localhost:8051/health + + # Check UI + open http://localhost:5173 + ``` + +6. **If something goes wrong, restore:** + ```bash + ./scripts/restore_claude_os.sh 20251101_135211 + ./start.sh + ``` + +--- + +## Common Scenarios + +### Scenario 1: Test install.sh for a user report + +```bash +# 1. Backup everything +./scripts/backup_claude_os.sh + +# 2. Clean installation (keep data, test scripts) +rm -rf venv +rm ~/.claude/commands/claude-os-*.md +rm ~/.claude/skills/{memory,initialize-project,remember-this} + +# 3. Test install as if you're a new user +./install.sh + +# 4. Restore your data (database, configs) +./scripts/restore_claude_os.sh +./start.sh +``` + +### Scenario 2: Test setup.sh from scratch + +```bash +# 1. Backup everything +./scripts/backup_claude_os.sh + +# 2. Full clean (simulate fresh machine) +./stop_all_services.sh +rm -rf venv venv_* +rm -rf node_modules +rm -rf data/claude-os.db +rm ~/.claude/commands/claude-os-*.md +rm ~/.claude/skills/{memory,initialize-project,remember-this} + +# 3. Test full setup +./setup.sh +./start_all_services.sh + +# 4. Restore your data +./scripts/restore_claude_os.sh +./start.sh +``` + +### Scenario 3: Test project initialization + +```bash +# 1. Backup current state +./scripts/backup_claude_os.sh + +# 2. Create test project +cd ~/test-project +/claude-os-init # In Claude Code + +# 3. If something breaks, restore +cd ~/Projects/claude-os +./scripts/restore_claude_os.sh +``` + +--- + +## Backup Best Practices + +### When to Backup + +- **Before testing installations** - Always! +- **Before major changes** - Modifying core files +- **Weekly** - If actively developing +- **Before upgrades** - Git pull, dependency updates + +### Backup Management + +```bash +# List all backups +ls -lh backups/ + +# Check backup size +du -sh backups/backup_* + +# Remove old backups (keep last 5) +cd backups +ls -t | tail -n +6 | xargs rm -rf + +# Archive old backups +tar -czf backups_archive_2025.tar.gz backups/ +``` + +### Multiple Backups + +The backup script creates **new backups** each time - it never overwrites: + +```bash +./scripts/backup_claude_os.sh # Creates backup_20251101_135211 +./scripts/backup_claude_os.sh # Creates backup_20251101_140530 +./scripts/backup_claude_os.sh # Creates backup_20251101_141005 +``` + +You can safely run it multiple times! + +--- + +## Troubleshooting + +### "Backup location not found" + +```bash +# List available backups +ls -1 backups/ | grep backup_ + +# Use exact timestamp from list +./scripts/restore_claude_os.sh 20251101_135211 +``` + +### "Permission denied" + +```bash +# Make scripts executable +chmod +x scripts/backup_claude_os.sh scripts/restore_claude_os.sh +``` + +### "Database locked" during backup + +```bash +# Stop services first +./stop_all_services.sh + +# Then backup +./scripts/backup_claude_os.sh +``` + +### Restore doesn't fix everything + +The restore script restores **data** but not: +- Python packages (run `pip install -r requirements.txt`) +- Node modules (run `cd frontend && npm install`) +- Symlinks (run `./install.sh`) +- Running services (run `./start.sh`) + +**Full recovery process:** +```bash +./scripts/restore_claude_os.sh +./install.sh # Recreate symlinks +./start.sh # Start services +``` + +--- + +## File Locations Reference + +### Backed Up Locations + +``` +claude-os/ +├── data/ +│ ├── claude-os.db ← BACKED UP (critical!) +│ └── uploads/ ← BACKED UP +├── .env ← BACKED UP (has secrets) +├── claude-os-config.json ← BACKED UP +├── claude-os-state.json ← BACKED UP +├── claude-os-triggers.json ← BACKED UP +└── logs/ ← BACKED UP (recent only) + +~/.claude/ +├── commands/claude-os-*.md ← Symlink info recorded +└── skills/{memory,etc} ← Symlink info recorded +``` + +### Backup Storage Location + +``` +claude-os/ +└── backups/ + ├── backup_20251101_135211/ + │ ├── claude-os.db + │ ├── .env + │ ├── claude-os-config.json + │ ├── claude-os-state.json + │ ├── claude-os-triggers.json + │ ├── uploads/ + │ ├── logs/ + │ ├── symlink_info.txt + │ └── MANIFEST.txt + └── backup_20251101_140530/ + └── ... +``` + +--- + +## Security Notes + +### .env File Contains Secrets + +The `.env` file may contain: +- `CLAUDE_OS_PASSWORD` - Admin password +- `CLAUDE_OS_SECRET_KEY` - JWT secret +- API keys (if using OpenAI) + +**Backups are stored locally** in `backups/` directory. + +**⚠️ DO NOT:** +- Commit backups to git (.gitignore already excludes them) +- Share backup directories +- Store backups in public locations + +### Recommended Backup Security + +```bash +# Encrypt sensitive backups +tar -czf - backups/backup_20251101_135211 | \ + openssl enc -aes-256-cbc -pbkdf2 -out backup_encrypted.tar.gz.enc + +# Decrypt when needed +openssl enc -aes-256-cbc -pbkdf2 -d -in backup_encrypted.tar.gz.enc | \ + tar -xzf - +``` + +--- + +## Summary + +**You now have:** + +✅ `backup_claude_os.sh` - Backup all your data +✅ `restore_claude_os.sh` - Restore from backup +✅ Safe testing workflow +✅ Your first backup created! + +**Next steps:** + +1. Your backup is ready: `backups/backup_20251101_135211/` +2. You can safely test `./install.sh` +3. If anything breaks: `./scripts/restore_claude_os.sh 20251101_135211` +4. Test away with confidence! 🚀 + +--- + +**Questions?** +- Check `backups/backup_*/MANIFEST.txt` for backup contents +- Run `./scripts/restore_claude_os.sh` with no arguments to list backups +- Backups are fast (30 seconds) - backup often! diff --git a/docs/guides/HOOK_SETUP_QUICK_START.md b/docs/guides/HOOK_SETUP_QUICK_START.md new file mode 100644 index 0000000..f8d362c --- /dev/null +++ b/docs/guides/HOOK_SETUP_QUICK_START.md @@ -0,0 +1,230 @@ +# File Watcher Hooks - Quick Start Guide + +## What Changed? + +The `initialize-project` skill now **automatically configures file watchers** for your project's knowledge bases. No more manual setup needed! + +## Before vs After + +### Before (Manual Setup Required) +```bash +# Initialize project +initialize-project: 1 + +# Then manually enable hooks via API +curl -X POST http://localhost:8051/api/projects/1/hooks/knowledge_docs/enable \ + -H "Content-Type: application/json" \ + -d '{"folder_path": "/path/to/knowledge_docs"}' + +# Then manually start the file watcher +curl -X POST http://localhost:8051/api/watcher/start/1 + +# Only THEN would new files auto-sync +``` + +### After (Fully Automatic) +```bash +# Initialize project +initialize-project: 1 + +# ✨ File watchers are now automatically configured! +# New files will be auto-synced immediately +``` + +## How File Watchers Work + +When you initialize a project, the system automatically: + +1. **Creates hooks for all 4 MCP types:** + - `knowledge_docs` → Watches your project's documentation folder + - `project_profile` → Watches `.claude-os/project-profile/` + - `project_index` → Watches `.claude-os/project-index/` + - `project_memories` → Watches `.claude-os/memories/` + +2. **Starts the file watcher service** + - Monitors all configured folders + - Detects file changes within ~2 seconds + - Automatically syncs changes to knowledge bases + +3. **Creates the necessary folders** + - Project folders are created if they don't exist + - Ready to accept new files immediately + +## Default Folder Mappings + +| MCP Type | Default Folder | Behavior | +|----------|---|---| +| `knowledge_docs` | `docs/` (or `documentation/`) | Watches for markdown, text, PDF files | +| `project_profile` | `.claude-os/project-profile/` | Auto-created, stores profile docs | +| `project_index` | `.claude-os/project-index/` | Auto-created, stores code index | +| `project_memories` | `.claude-os/memories/` | Auto-created, stores insights | + +## Using Custom Folders + +If you want to use a different folder for `knowledge_docs`: + +```bash +# Create your custom folder +mkdir my-docs + +# Enable hook for custom folder +curl -X POST "http://localhost:8051/api/projects/1/hooks/knowledge_docs/enable" \ + -H "Content-Type: application/json" \ + -d '{"folder_path": "/path/to/my-docs"}' + +# Restart the watcher to pick up changes +curl -X POST "http://localhost:8051/api/watcher/restart/1" +``` + +## Verify Hooks Are Working + +### Check Watcher Status +```bash +curl http://localhost:8051/api/watcher/status +``` + +Expected output shows your project is being watched: +```json +{ + "status": { + "enabled": true, + "projects_watched": 1, + "projects": { + "1": { + "watched_paths": { + "knowledge_docs": "/path/to/docs", + "project_profile": "/path/to/.claude-os/project-profile", + ... + }, + "event_handlers": ["knowledge_docs", "project_profile", ...] + } + } + } +} +``` + +### Check Hooks Configuration +```bash +cat /path/to/project/.claude-os/hooks.json +``` + +Should show something like: +```json +{ + "version": "1.0", + "project_id": 1, + "hooks": { + "knowledge_docs": { + "enabled": true, + "folder_path": "/path/to/docs", + "synced_files": {} + }, + ... + } +} +``` + +## Testing Auto-Sync + +### Test knowledge_docs Auto-Sync +```bash +# Create a test file +echo "# Test Document" > /path/to/docs/test.md + +# Wait 2-3 seconds for the watcher to pick it up + +# Verify it was indexed +sqlite3 /path/to/claude-os/data/claude-os.db \ + "SELECT COUNT(*) FROM documents WHERE doc_id LIKE 'test.md%' AND kb_id = 1" +``` + +Should show a count > 0 if successfully indexed. + +## Troubleshooting + +### Hooks not triggering auto-sync? + +1. **Check if watcher is running:** + ```bash + curl http://localhost:8051/api/watcher/status + ``` + If `"enabled": false`, start it: + ```bash + curl -X POST "http://localhost:8051/api/watcher/start/1" + ``` + +2. **Check hooks configuration:** + ```bash + cat .claude-os/hooks.json + ``` + Verify `"enabled": true` for your MCP type + +3. **Check folder permissions:** + - Ensure folder is readable by the MCP server + - Try creating a test file manually + +4. **Check MCP server logs:** + - Look for errors in `/private/tmp/` or application logs + - Check if server is running: `ps aux | grep python | grep server` + +### Files not appearing in search? + +1. **Verify files were indexed:** + ```bash + sqlite3 /path/to/claude-os/data/claude-os.db \ + "SELECT COUNT(*) FROM documents WHERE kb_id = 1" + ``` + +2. **Check file format is supported:** + - Default: `.md`, `.txt`, `.pdf`, `.py`, `.js`, `.ts`, `.json`, `.yaml` + - Configure custom patterns in hooks.json `file_patterns` array + +3. **Manually trigger sync:** + ```bash + curl -X POST "http://localhost:8051/api/projects/1/hooks/sync?mcp_type=knowledge_docs" + ``` + +## Advanced: Restart Watchers + +If watchers stop responding: + +```bash +# Restart a specific project's watcher +curl -X POST "http://localhost:8051/api/watcher/restart/1" + +# Or restart all watchers +# (Note: not available via API, requires server restart) +``` + +## Git Integration + +The system also installs **git post-commit hooks** that: +- Auto-index changed files on each commit +- Periodically expand the index with new files (every 10 commits) +- Track commit count for smart indexing + +This works seamlessly with the file watcher hooks. + +## FAQ + +**Q: Do I need to restart anything after running initialize-project?** +A: No! Everything is set up automatically. File watchers start immediately. + +**Q: Can I add files while the watcher is running?** +A: Yes! Add files anytime. They'll be indexed within ~2 seconds. + +**Q: What if I want to disable auto-sync for a folder?** +A: Disable the hook via API: +```bash +curl -X POST "http://localhost:8051/api/projects/1/hooks/knowledge_docs/disable" +``` + +**Q: Can multiple projects have watchers running?** +A: Yes! The system can monitor multiple projects simultaneously. + +**Q: Do file watchers persist after server restart?** +A: No, watchers stop when the server restarts. They'll restart automatically when projects are loaded. + +--- + +**Last Updated:** October 28, 2025 diff --git a/docs/guides/IDEAL_SESSION_WORKFLOW.md b/docs/guides/IDEAL_SESSION_WORKFLOW.md new file mode 100644 index 0000000..5053a68 --- /dev/null +++ b/docs/guides/IDEAL_SESSION_WORKFLOW.md @@ -0,0 +1,373 @@ +# The Ideal Claude OS Session Workflow + +**What SHOULD happen vs what ACTUALLY happens (and how to fix it)** + +--- + +## 🌅 Morning Coffee Scenario + +You grab your coffee, open your terminal, and type: + +```bash +cd ~/Projects/pistn +code . +# Claude Code CLI opens +``` + +--- + +## ✅ IDEAL: What SHOULD Happen Automatically + +``` +═══════════════════════════════════════════════════════════════ +🚀 CLAUDE OS INITIALIZED +═══════════════════════════════════════════════════════════════ + +Detected Project: Pistn (Ruby on Rails) +Loading context... ⏳ + +[Claude automatically reads:] +✓ CLAUDE.md +✓ .claude-os/config.json +✓ claude-os-state.json +✓ agent-os/config.yml + +[Claude automatically checks:] +✓ Git status (feature/appointment-redesign, 3 files modified) +✓ Recent commits (last 3) +✓ Project memories (searching "appointment dashboard recent") + +[Claude automatically loads:] +✓ 5 relevant memories +✓ Coding standards +✓ Architectural patterns +✓ Kanban board (3 specs, 52 tasks, 45% complete) + +═══════════════════════════════════════════════════════════════ +📚 CONTEXT LOADED - Ready to code! +═══════════════════════════════════════════════════════════════ + +You were working on: Appointment Dashboard Redesign +Progress: 45% complete (23 of 52 tasks done) + +Last session: 2 days ago +Duration: 2h 15m +Completed: Sidebar navigation, card layouts, toggle switches + +Still in progress: + ⏳ PHASE2-TASK3: Implement concern methods + ⏳ PHASE2-TASK4: Add helper methods + +═══════════════════════════════════════════════════════════════ +💡 KEY REMINDERS +═══════════════════════════════════════════════════════════════ + +• 67-page implementation plan in memories +• Zero functionality loss requirement +• Tekmetric integration must work on save +• Use service objects for business logic +• Bootstrap 3.x only (no v4/v5) + +═══════════════════════════════════════════════════════════════ +🎯 SUGGESTED ACTIONS +═══════════════════════════════════════════════════════════════ + +1. Continue Phase 2 (30 min estimated) +2. Commit your 3 modified files first +3. Start something new + +What would you like to do? +═══════════════════════════════════════════════════════════════ +``` + +**You say:** "Let's continue phase 2" + +**Claude:** "Perfect! Let me implement the concern methods for PHASE2-TASK3. Based on our service object pattern, I'll..." + +--- + +## ❌ CURRENT: What ACTUALLY Happens + +``` +You: [Opens Claude Code] + +Claude: Hello! How can I help you today? + +You: Let's continue working on the appointment dashboard + +Claude: I'd be happy to help with the appointment dashboard! + Could you tell me more about the project and what + you've been working on? + +You: *Sigh* We're redesigning the appointment dashboard in + Pistn. We've been working on this for 2 days. I have + a 67-page implementation plan. We completed the sidebar + and cards. We're on phase 2... + +Claude: Thanks for the context! What would you like to work + on specifically? + +You: Let me just share the implementation plan again... + [Copies and pastes 67 pages] +``` + +**Problem:** You spend 15 minutes re-explaining everything Claude should already know! + +--- + +## 🔧 THE FIX: Making It Work Today + +**Until automatic session start is implemented in Claude Code itself, YOU need to trigger it manually:** + +### Step 1: Add This to Your CLAUDE.md + +```markdown +# IMPORTANT: Session Start Protocol + +**EVERY TIME we start a conversation, YOU (Claude) must:** + +1. **Check if this is a Claude OS project** + ```bash + ls -la | grep -E "(CLAUDE.md|.claude-os|agent-os)" + ``` + +2. **If yes, AUTOMATICALLY do the following WITHOUT me asking:** + + a) Read these files: + - CLAUDE.md (you're reading it now!) + - .claude-os/config.json + - claude-os-state.json (if exists) + - agent-os/config.yml (if exists) + + b) Check git context: + ```bash + git branch --show-current + git status --short + git log -3 --oneline + ``` + + c) Search my project memories: + - Use last session task + current branch + "recent" + - Load top 5 memories from {project}-project_memories + + d) Load coding standards: + - Search {project}-project_profile for "coding standards" + + e) Check Kanban board: + - GET /api/projects/{id}/kanban + - Show current spec progress + + f) Present a session start summary showing: + - What we were working on last + - Current progress + - Key reminders + - Suggested next steps + +3. **Then ask:** "What would you like to work on?" + +**DO THIS AUTOMATICALLY. DO NOT wait for me to ask!** +``` + +### Step 2: Create a Morning Routine + +Add this alias to your `~/.zshrc` or `~/.bashrc`: + +```bash +alias pistn='cd ~/Projects/pistn && code . && cat .claude-os/session-reminder.txt' +``` + +Create `.claude-os/session-reminder.txt`: + +``` +═══════════════════════════════════════════════════════════════ +🚨 REMINDER TO CLAUDE 🚨 +═══════════════════════════════════════════════════════════════ + +This is a Claude OS project! + +Please AUTOMATICALLY: +1. Read CLAUDE.md +2. Read .claude-os/config.json +3. Check git status +4. Search project_memories +5. Load coding standards +6. Check Kanban board +7. Present session start summary + +DO NOT make me paste context manually! +═══════════════════════════════════════════════════════════════ +``` + +Now you just type `pistn` and Claude will see the reminder! + +### Step 3: Use Session Commands + +When you want to ensure context is loaded: + +```bash +# Option A: Explicit session start +/claude-os-session start "continue appointment dashboard" + +# Option B: Just remind Claude +"Hey Claude, can you load my project context and tell me + where we left off?" + +# Option C: Direct command +"Read CLAUDE.md, check git status, search my memories for + 'appointment dashboard', and load my coding standards. + Then tell me what we were working on." +``` + +--- + +## 🎯 Making This Automatic (Future) + +**What needs to happen for true automation:** + +### In Claude Code CLI: + +1. **Project Detection Hook** + - When CLI starts, check for `.claude-os/` + - If found, trigger automatic context loading + - Display session start summary + +2. **Auto-Load Behavior** + - Read `CLAUDE.md` into system prompt + - Search knowledge bases automatically + - Present context before user types anything + +3. **Session State Persistence** + - Save session state on exit + - Restore on next start + - Track what was being worked on + +### In Claude OS: + +4. **Session API Endpoint** + ```http + GET /api/projects/{id}/session/start + + Returns: + - Last session summary + - Relevant memories (top 5) + - Coding standards + - Git context + - Kanban status + - Suggested actions + ``` + +5. **MCP Session Tool** + - Expose session data via MCP + - Claude Code can call it automatically + - No user intervention needed + +--- + +## 📋 Checklist: Am I Using Sessions Effectively? + +### ✅ Good Session Practice + +- [ ] Claude presents context at start without me asking +- [ ] I never re-explain the project architecture +- [ ] Claude references past decisions automatically +- [ ] I can pick up exactly where I left off +- [ ] Claude suggests next steps based on history + +### ❌ Bad Session Practice + +- [ ] I paste the same context document every session +- [ ] I explain "we use service objects" every time +- [ ] Claude asks "what's your tech stack?" repeatedly +- [ ] I have to search for what I did yesterday +- [ ] Every session feels like starting over + +--- + +## 🔥 Power User Tips + +### 1. Create Session Shortcuts + +```bash +# ~/.zshrc +alias cs-start='echo "Claude: load context, check memories, show status"' +alias cs-end='echo "Claude: analyze session, suggest saves, update state"' +alias cs-blocker='echo "Claude: track blocker and search for solutions"' +``` + +### 2. Use Quick Saves During Work + +```bash +# When you discover something important +/claude-os-session save "Service objects return model on success, error on fail" + +# When you hit a blocker +/claude-os-session blocker "Tekmetric API 500 errors on appointment sync" + +# When you find a pattern +/claude-os-session pattern "Use localStorage for sidebar state persistence" +``` + +### 3. End Sessions Properly + +```bash +# At end of day +/claude-os-session end + +# Claude will: +# - Analyze what you did +# - Suggest high-value saves +# - Update statistics +# - Prepare context for next session +``` + +### 4. Check Status Mid-Session + +```bash +/claude-os-session status + +# Shows: +# - How long you've been working +# - What context is loaded +# - Active blockers +# - Next suggested action +``` + +--- + +## 🚀 The Ultimate Goal + +**Imagine this future:** + +You open Claude Code. No typing needed. Claude says: + +``` +Welcome back! It's been 2 days since your last session. + +You were redesigning the Appointment Dashboard. You're 45% done +(23 of 52 tasks). Last session you completed the sidebar navigation +and card layouts. + +You have 2 tasks in progress: +- PHASE2-TASK3: Implement concern methods (30 min estimated) +- PHASE2-TASK4: Add helper methods (20 min estimated) + +I have your 67-page implementation plan loaded, plus 5 relevant +memories and all your coding standards. + +Your git branch has 3 uncommitted files. Want to commit those +first or continue with PHASE2-TASK3? +``` + +**That's zero context loss. That's the vision.** + +--- + +## 📖 Related Docs + +- [SESSION_START_PROTOCOL.md](./SESSION_START_PROTOCOL.md) - Detailed protocol +- [claude-os-session.md](../../templates/commands/claude-os-session.md) - Command reference +- [WHAT_IS_CLAUDE_OS.md](./WHAT_IS_CLAUDE_OS.md) - Overall system guide + +--- + +**Until full automation exists, use the CLAUDE.md instructions and session commands to get the same result manually. But it WILL be automatic soon!** 🚀 diff --git a/docs/guides/MANDATORY_SESSIONS.md b/docs/guides/MANDATORY_SESSIONS.md new file mode 100644 index 0000000..37c53fe --- /dev/null +++ b/docs/guides/MANDATORY_SESSIONS.md @@ -0,0 +1,548 @@ +# Mandatory Sessions - The New Claude OS Model + +**Every conversation is a session. Period.** + +--- + +## 🎯 The Philosophy + +**Old Model:** Sessions are optional, you choose when to track work +**New Model:** You're ALWAYS in a session. The only choice is WHAT session. + +**Why?** +- Zero context loss +- Complete work history +- Automatic tracking +- Better insights over time + +--- + +## 🚀 How It Works + +### Every Conversation Start + +``` +═══════════════════════════════════════════════════════════════ +🚀 CLAUDE OS - SESSION MANAGER +═══════════════════════════════════════════════════════════════ + +Project: Pistn +Last Session: Dashboard Redesign (2 days ago, 2h 15m) +Progress: 45% complete (PHASE2-TASK3 in progress) + +Options: + 1. Resume "Dashboard Redesign" [loads full context] + 2. Start new session [what are you working on?] + 3. Quick question [auto-session, no setup needed] + +Choice: _ +═══════════════════════════════════════════════════════════════ +``` + +**You MUST pick one. No "just chatting" option.** + +--- + +## 📋 Session Types + +### 1. Feature Implementation +``` +Type: feature +Duration: Tracked +Kanban: Linked to spec + tasks +Auto-saves: High-value patterns and decisions + +Example: "Dashboard Redesign" +Context: Spec tasks, memories, coding standards +Tracking: Task completion, time per task, blockers +``` + +### 2. Bug Fix +``` +Type: bug +Duration: Tracked +Priority: Detected from description (high/medium/low) +Auto-saves: Root cause, solution, prevention + +Example: "API 500 Errors" +Context: Error logs, similar past issues, integration patterns +Tracking: Time to fix, solution approach, related issues +``` + +### 3. Exploration / Learning +``` +Type: exploration +Duration: Tracked +Auto-saves: Key learnings, architecture insights + +Example: "Understand authentication flow" +Context: Relevant code, architecture docs +Tracking: Files explored, patterns discovered +``` + +### 4. Refactoring / Maintenance +``` +Type: maintenance +Duration: Tracked +Auto-saves: Refactoring patterns, improvements made + +Example: "Clean up controller concerns" +Context: Coding standards, similar refactors +Tracking: Files changed, complexity reduced +``` + +### 5. Code Review +``` +Type: review +Duration: Tracked +Auto-saves: Review comments, patterns identified + +Example: "Review PR #234" +Context: Project standards, common issues +Tracking: Issues found, suggestions made +``` + +### 6. Quick Question (Auto-Managed) +``` +Type: question +Duration: Auto-tracked (ends after 5 min inactivity) +Auto-saves: Only if valuable insight + +Example: "How does Draper work?" +Context: Minimal (just project standards) +Tracking: Questions asked, answers given +``` + +--- + +## 🔄 Session Lifecycle + +### Phase 1: Session Selection (Every Conversation Start) + +**Option 1: Resume Existing Session** +``` +You: "1" (resume) + +Claude: +═══════════════════════════════════════════════════════════════ +✓ RESUMING: Dashboard Redesign +═══════════════════════════════════════════════════════════════ + +[Loads all context automatically:] +✓ Spec: Group Account Rendering (45% complete) +✓ Current Task: PHASE2-TASK3 (Implement concern methods) +✓ 5 relevant memories loaded +✓ Coding standards loaded +✓ Git: 3 files modified on feature/appointment-redesign + +Duration this session: 0h 0m +Total duration: 2h 15m + +Ready! Let's continue implementing PHASE2-TASK3. +═══════════════════════════════════════════════════════════════ +``` + +**Option 2: Start New Session** +``` +You: "2" (new session) + +Claude: "What are you working on? + + (I'll detect the type and load relevant context)" + +You: "Fix the Tekmetric API 500 errors" + +Claude: +═══════════════════════════════════════════════════════════════ +✓ NEW BUG SESSION STARTED +═══════════════════════════════════════════════════════════════ + +Session: "Fix Tekmetric API 500 errors" +Type: Bug Fix (detected) +Priority: High (500 errors are critical) + +[Auto-loaded context:] +✓ Searched memories: "Tekmetric API integration errors" +✓ Found 3 similar issues from past sessions +✓ Loaded integration patterns +✓ Git status checked + +Previous session "Dashboard Redesign" paused. + +Let's debug this! What's the error message? +═══════════════════════════════════════════════════════════════ +``` + +**Option 3: Quick Question** +``` +You: "3" (quick question) + +Claude: "What's your question?" + +You: "How do I use Draper decorators?" + +Claude: +═══════════════════════════════════════════════════════════════ +💬 QUICK QUESTION SESSION +═══════════════════════════════════════════════════════════════ + +[Gives answer] + +This auto-session will end after 5 minutes of inactivity. +Need more help, or ready to resume Dashboard Redesign? +═══════════════════════════════════════════════════════════════ +``` + +### Phase 2: Active Session (During Work) + +**Live Tracking:** +``` +[Active Session: Dashboard Redesign] +Duration: 1h 23m +Files changed: 3 +Quick saves: 2 +Last activity: 2 minutes ago + +/claude-os-session status → Shows current session details +/claude-os-session save "insight" → Quick save to memories +/claude-os-session switch "bug fix" → Switch to different session +``` + +**Smart Prompts:** +``` +[After 2 hours of work] +Claude: "You've been working for 2h. You usually take a break around now. + Want to commit your work and pause the session?" + +[When pattern detected] +Claude: "This looks like the service object pattern. Should I save + this as a reusable pattern for future reference?" + +[When blocker encountered] +Claude: "Want me to track this as a blocker and search for solutions + from past sessions?" +``` + +### Phase 3: Session End (Explicit or Auto) + +**Explicit End:** +``` +You: "/claude-os-session end" + +Claude: +═══════════════════════════════════════════════════════════════ +📊 SESSION SUMMARY: Dashboard Redesign +═══════════════════════════════════════════════════════════════ + +Duration: 1h 23m +Files changed: 3 files +Quick saves: 2 +Commits: 1 + +Work completed: + ✓ Implemented concern methods for PHASE2-TASK3 + ✓ Fixed N+1 query issue + ✓ Added helper methods for PHASE2-TASK4 + +Progress: 45% → 53% (8% increase!) +Tasks completed: 2 tasks (PHASE2-TASK3, PHASE2-TASK4) + +═══════════════════════════════════════════════════════════════ +💾 SMART SAVES DETECTED +═══════════════════════════════════════════════════════════════ + +I found 2 items worth saving: + +1. 💎 HIGH VALUE - Concern Method Pattern + "Extracted group account logic to concern with proper + service object integration. Reusable pattern." + + Save to project_profile? [Y/n] + +2. 📊 MEDIUM VALUE - N+1 Query Fix + "Fixed N+1 in appointments loading by eager loading + with includes(:group_account)" + + Save to project_memories? [Y/n] + +═══════════════════════════════════════════════════════════════ +``` + +**Auto-End (Inactivity):** +``` +[After 15 minutes of inactivity] + +Claude: "Session 'Dashboard Redesign' has been inactive for 15 minutes. + + Options: + 1. Keep session active + 2. Pause session (can resume later) + 3. End session (save and summarize) + + Choice: _" +``` + +--- + +## 🎛️ Session Switching + +### Mid-Session Switch +``` +[Active: Dashboard Redesign, 45m elapsed] + +You: "Actually I need to fix a bug first" + +Claude: "Want to switch sessions? + + 1. Pause 'Dashboard Redesign' and start 'Bug Fix' session + 2. Continue 'Dashboard Redesign' (handle bug within this session) + + Choice: _" + +You: "1" + +Claude: +═══════════════════════════════════════════════════════════════ +✓ SESSION SWITCHED +═══════════════════════════════════════════════════════════════ + +Paused: Dashboard Redesign (45m, 45% complete) +Started: Bug Fix Session + +What's the bug? +═══════════════════════════════════════════════════════════════ +``` + +### Multiple Sessions Same Day +``` +═══════════════════════════════════════════════════════════════ +📊 TODAY'S SESSIONS +═══════════════════════════════════════════════════════════════ + +09:00 - 11:15 Dashboard Redesign 2h 15m ✓ Ended +11:15 - 11:45 API Bug Fix 30m ✓ Ended +12:00 - 13:30 Dashboard Redesign 1h 30m ⏸ Paused +14:00 - 15:30 Code Review 1h 30m 🔄 Active + +Total: 5h 45m across 4 sessions +Most time: Dashboard Redesign (3h 45m, 2 sessions) +═══════════════════════════════════════════════════════════════ +``` + +--- + +## 📊 Session Statistics + +### Daily Summary +``` +═══════════════════════════════════════════════════════════════ +📊 END OF DAY SUMMARY - November 4, 2025 +═══════════════════════════════════════════════════════════════ + +Total sessions: 4 +Total time: 5h 45m +Average session: 1h 26m + +Session breakdown: + • Feature work: 3h 45m (65%) + • Bug fixes: 30m (9%) + • Code review: 1h 30m (26%) + +Productivity: + • Tasks completed: 4 tasks + • Memories saved: 6 insights + • Patterns discovered: 2 patterns + • Blockers resolved: 1 + +Most productive session: Dashboard Redesign (2h 15m, 3 tasks) +Longest session: Dashboard Redesign (2h 15m) + +Great day! 🚀 +═══════════════════════════════════════════════════════════════ +``` + +### Weekly Summary +``` +Week of Oct 28 - Nov 3, 2025 + +Total sessions: 23 +Total time: 32h 15m +Average daily: 4h 36m + +Session types: + • Feature: 18 sessions (24h, 74%) + • Bug fix: 3 sessions (2h, 6%) + • Exploration: 2 sessions (6h 15m, 20%) + +Top projects: + 1. Pistn: 28h (Dashboard Redesign: 18h) + 2. Claude OS: 4h 15m (Kanban feature: 4h 15m) + +Memories saved: 23 insights +Patterns discovered: 5 patterns + +Most productive day: Oct 31 (6h 30m, 8 tasks) +``` + +### Project Summary +``` +Dashboard Redesign - Complete History + +Total sessions: 5 +Total time: 12h 45m +Status: In Progress (53% complete) + +Session history: + • Oct 29: 2h 15m (PHASE1: Sidebar + Cards) + • Oct 31: 3h 00m (PHASE1: Toggles + Forms) + • Nov 1: 2h 30m (PHASE2: Concerns started) + • Nov 3: 3h 00m (PHASE2: Helper methods) + • Nov 4: 2h 00m (PHASE2: Testing) + +Progress: + • Tasks completed: 27 of 52 (53%) + • Phases completed: 1 of 3 + • Estimated remaining: 10h 30m + +Velocity: + • Average: 2.4 tasks per session + • Average: 0.47h per task + • Projected completion: Nov 6 +``` + +--- + +## 🎯 Commands Reference + +### Session Management +```bash +# At conversation start (automatic prompt) +[Choose 1/2/3] + +# During session +/claude-os-session status # Current session details +/claude-os-session save "note" # Quick save +/claude-os-session switch "task" # Switch to different session +/claude-os-session pause # Pause current session +/claude-os-session end # End with summary + +# View history +/claude-os-session today # Today's sessions +/claude-os-session week # This week +/claude-os-session history [task] # History for specific task +``` + +--- + +## 🔧 Configuration + +### Session Preferences (`.claude-os/config.json`) +```json +{ + "session_management": { + "mandatory": true, + "auto_prompt_on_start": true, + "auto_save_frequency": "15_minutes", + "inactivity_timeout": 15, + "auto_switch_detection": true, + "daily_summary": true, + "break_reminders": { + "enabled": true, + "interval_minutes": 120 + } + } +} +``` + +--- + +## 💡 Best Practices + +### 1. Name Sessions Descriptively +``` +✅ Good: "Fix Tekmetric sync 500 errors" +✅ Good: "Implement group account rendering" +❌ Bad: "Work on stuff" +❌ Bad: "Bug fix" +``` + +### 2. Use Session Types Correctly +- **Feature:** Building new functionality +- **Bug:** Fixing specific issues +- **Exploration:** Learning/understanding code +- **Maintenance:** Refactoring/cleanup +- **Review:** Code review +- **Question:** Quick questions (auto-managed) + +### 3. End Sessions Cleanly +``` +Don't just close terminal! +Use: /claude-os-session end + +Benefits: + • Captures work summary + • Suggests valuable saves + • Updates statistics + • Prepares next session +``` + +### 4. Switch Sessions When Context Changes +``` +Don't mix unrelated work in one session! + +Working on Dashboard → API bug appears → Switch sessions! + +Keeps tracking clean and relevant. +``` + +--- + +## 🚀 Benefits Recap + +### For You: +- **Never lose work** - Everything tracked +- **Perfect continuity** - Resume exactly where you left off +- **Understand productivity** - Real metrics +- **Learn from history** - See what works + +### For Me (Claude): +- **Complete context** - Know what we're working on +- **Smart suggestions** - Based on session type +- **Proactive saves** - Capture valuable insights +- **Better guidance** - Relevant to current task + +### For The Team: +- **Shared knowledge** - All insights saved +- **Velocity tracking** - Understand capacity +- **Pattern recognition** - Learn what works +- **Onboarding** - New members see work history + +--- + +## 🎯 The Goal + +**Every moment of coding is tracked, categorized, and learned from.** + +No more: +- ❌ "What was I doing?" +- ❌ "How long did that take?" +- ❌ "Where did we leave off?" +- ❌ "Did we solve this before?" + +Only: +- ✅ Instant context on session start +- ✅ Complete work history +- ✅ Automatic learning +- ✅ Zero context loss + +**This is the complete AI development system working at full power.** 🚀 + +--- + +**Next Steps:** +1. Update CLAUDE.md template with mandatory session flow +2. Update `/claude-os-session` command to reflect new model +3. Start using it TODAY in current projects +4. Track results and iterate + +**Let's make sessions mandatory!** 💪 diff --git a/docs/guides/PORTS_GUIDE.md b/docs/guides/PORTS_GUIDE.md new file mode 100644 index 0000000..ecd9c10 --- /dev/null +++ b/docs/guides/PORTS_GUIDE.md @@ -0,0 +1,233 @@ +# Claude OS Ports Guide + +## Two Different Services + +Claude OS has **two separate services** running on **different ports**: + +### 1. MCP Server (Port 8051) + +**Purpose:** API server for Claude Code integration + +**Technology:** FastAPI (Python) + +**URL:** `http://localhost:8051` + +**Usage:** +- Used by Claude Code (via MCP protocol) +- Handles AI memory operations +- Manages knowledge bases +- Serves API endpoints + +**⚠️ IMPORTANT:** +- **Do NOT open this in a web browser** +- It expects MCP protocol POST requests +- Browser GET requests will show "Method Not Allowed" + +**How to start:** +```bash +./start.sh # Starts MCP server +``` + +--- + +### 2. Web UI (Port 5173) + +**Purpose:** Visual interface for humans + +**Technology:** React + Vite (JavaScript) + +**URL:** `http://localhost:5173` + +**Usage:** +- Browse knowledge bases +- Upload documents +- Search and query +- Project management +- Visual interface + +**✅ CORRECT:** +- **Open this URL in your browser** +- Designed for human interaction +- Nice visual interface + +**How to start:** +```bash +cd frontend +npm install # First time only +npm run dev # Starts on port 5173 +``` + +--- + +## Quick Reference + +| Service | Port | Open in Browser? | Purpose | +|---------|------|------------------|---------| +| **MCP Server** | 8051 | ❌ NO | For Claude Code (API) | +| **Web UI** | 5173 | ✅ YES | For humans (visual interface) | + +--- + +## Common Confusion + +### ❌ Wrong: Opening http://localhost:8051 in browser + +**What you see:** +```json +{ + "detail": "Method Not Allowed" +} +``` + +**Why:** The MCP server expects POST requests with MCP protocol data, not browser GET requests. + +### ✅ Correct: Opening http://localhost:5173 in browser + +**What you see:** +- Nice web interface +- Project management +- Knowledge base browser +- Document upload + +--- + +## Typical Workflow + +### 1. Start MCP Server (for Claude Code) + +```bash +./start.sh +``` + +**Output:** +``` +✅ Claude OS is running! + + 📡 MCP Server: http://localhost:8051 + (For Claude Code integration - do NOT open in browser) +``` + +### 2. Start Web UI (optional, for visual interface) + +```bash +cd frontend +npm run dev +``` + +**Output:** +``` + ➜ Local: http://localhost:5173/ + ➜ Network: use --host to expose +``` + +Now you can: +- Use Claude Code with MCP server (port 8051) +- Open Web UI in browser (port 5173) + +--- + +## Testing Each Service + +### Test MCP Server (Port 8051) + +**Correct way (API call):** +```bash +curl -X POST http://localhost:8051/mcp/query \ + -H "Content-Type: application/json" \ + -d '{"query": "test"}' +``` + +**Wrong way (browser):** +``` +Open http://localhost:8051 in browser +→ Shows "Method Not Allowed" ❌ +``` + +### Test Web UI (Port 5173) + +**Correct way:** +``` +Open http://localhost:5173 in browser +→ Shows nice web interface ✅ +``` + +--- + +## Troubleshooting + +### "Method Not Allowed" error + +**Problem:** You're trying to access the MCP server (port 8051) in a browser + +**Solution:** +- Don't open port 8051 in browser +- That's for Claude Code to use, not humans +- If you want a web interface, start the frontend (port 5173) + +### "Connection refused" on port 5173 + +**Problem:** Web UI is not running + +**Solution:** +```bash +cd frontend +npm install # If first time +npm run dev +``` + +### "Connection refused" on port 8051 + +**Problem:** MCP server is not running + +**Solution:** +```bash +./start.sh +``` + +--- + +## Architecture Diagram + +``` +┌─────────────────────────────────────────┐ +│ YOUR BROWSER │ +│ http://localhost:5173 ✅ │ +│ (Web UI - React) │ +└──────────────┬──────────────────────────┘ + │ HTTP requests + ▼ +┌─────────────────────────────────────────┐ +│ MCP Server (FastAPI) │ +│ http://localhost:8051 │ +│ │ +│ ┌──────────────┐ ┌─────────┐ │ +│ │ API Routes │◄───┤ Claude │ │ +│ │ │ │ Code │ │ +│ └──────┬───────┘ └─────────┘ │ +│ │ │ +│ ▼ │ +│ ┌──────────────┐ │ +│ │ Database │ │ +│ │ (SQLite) │ │ +│ └──────────────┘ │ +└─────────────────────────────────────────┘ +``` + +**Access patterns:** +- Browser → Port 5173 (Web UI) → Port 8051 (MCP Server) → Database +- Claude Code → Port 8051 (MCP Server) → Database + +--- + +## Summary + +**Remember:** +- 🔴 **Port 8051:** For Claude Code (MCP protocol) - Don't open in browser! +- 🟢 **Port 5173:** For humans (Web UI) - Open this in browser! + +**When you run `./start.sh`:** +- MCP server starts on 8051 (for Claude Code) +- Web UI does NOT start automatically +- Start Web UI separately with `cd frontend && npm run dev` + +**Clear now?** 🚀 diff --git a/docs/guides/SESSIONS_GUIDE.md b/docs/guides/SESSIONS_GUIDE.md new file mode 100644 index 0000000..56b8afd --- /dev/null +++ b/docs/guides/SESSIONS_GUIDE.md @@ -0,0 +1,415 @@ +# Session Parsing & Insights Guide + +**Parse Claude Code sessions and extract insights automatically.** + +--- + +## Overview + +Claude Code stores conversation history in `.jsonl` session files located at: +``` +~/.claude/projects/{encoded-project-path}/{session-id}.jsonl +``` + +Claude OS can parse these files to: +- Extract conversations, tool calls, and file changes +- Generate summaries for context loading +- Extract insights (patterns, decisions, blockers) +- Build analytics on your development sessions + +--- + +## Session File Format + +Claude Code session files are JSON Lines format with various entry types: + +```jsonl +{"type": "summary", "summary": "...", "leafUuid": "..."} +{"type": "user", "uuid": "msg-001", "message": {"role": "user", "content": "..."}} +{"type": "assistant", "uuid": "msg-002", "message": {"role": "assistant", "content": [...]}} +{"type": "file-history-snapshot", "messageId": "...", "snapshot": {...}} +``` + +### Entry Types + +| Type | Description | +|------|-------------| +| `summary` | Session summary (usually at start) | +| `user` | User message | +| `assistant` | Assistant response (may contain tool_use) | +| `file-history-snapshot` | File changes made during session | + +--- + +## Using the Session Parser + +### Python API + +```python +from app.core.session_parser import ( + SessionParser, + get_project_sessions_dir, + list_session_files +) + +# Find sessions for a project +project_path = "/Users/me/Projects/myapp" +sessions = list_session_files(project_path) +# Returns: ['/path/to/session1.jsonl', '/path/to/session2.jsonl'] + +# Parse a session +parser = SessionParser(sessions[0]) +session_data = parser.parse() + +# Access parsed data +print(f"Session ID: {session_data.session_id}") +print(f"Messages: {len(session_data.messages)}") +print(f"Tool Calls: {len(session_data.tool_calls)}") +print(f"File Changes: {len(session_data.file_changes)}") +print(f"Duration: {session_data.start_time} to {session_data.end_time}") + +# Get conversation messages +messages = parser.get_conversation() +for msg in messages: + print(f"{msg.role}: {msg.content[:100]}...") + +# Get summary for LLM processing +summary = parser.get_summary_for_extraction(max_tokens=500) +print(summary) +``` + +### REST API + +```bash +# List sessions for a project +curl "http://localhost:8051/api/sessions?project_path=/path/to/project&limit=10" + +# Get session details +curl "http://localhost:8051/api/sessions/abc123?project_path=/path/to/project" + +# Get session summary +curl "http://localhost:8051/api/sessions/abc123/summary?project_path=/path/to/project&max_tokens=500" +``` + +--- + +## Session Data Structure + +### SessionData + +```python +@dataclass +class SessionData: + session_id: str + session_path: str + messages: List[Message] + tool_calls: List[ToolCall] + file_changes: List[FileChange] + start_time: Optional[str] + end_time: Optional[str] + git_branch: Optional[str] + cwd: Optional[str] + total_entries: int +``` + +### Message + +```python +@dataclass +class Message: + role: str # "user" or "assistant" + content: str # Message content + timestamp: str # ISO timestamp + uuid: str # Message UUID + parent_uuid: Optional[str] +``` + +### ToolCall + +```python +@dataclass +class ToolCall: + tool_name: str # e.g., "Read", "Write", "Bash" + timestamp: str + uuid: str + parent_uuid: Optional[str] + input_data: Dict # Tool input parameters +``` + +### FileChange + +```python +@dataclass +class FileChange: + file_path: str + timestamp: str + message_id: str # Which message triggered this change +``` + +--- + +## Insight Extraction + +The InsightExtractor analyzes sessions to identify: + +- **Patterns** - Recurring solutions and approaches +- **Decisions** - Architecture and implementation choices +- **Blockers** - Problems encountered and how they were resolved +- **Discoveries** - New learnings about the codebase + +### Using InsightExtractor + +```python +from app.core.insight_extractor import InsightExtractor, Insight + +# Create extractor with Ollama +extractor = InsightExtractor( + ollama_host="http://localhost:11434", + model="llama3.1:8b" +) + +# Extract insights from a session +parser = SessionParser("/path/to/session.jsonl") +summary = parser.get_summary_for_extraction(max_tokens=1000) + +insights = await extractor.extract_insights(summary) + +for insight in insights: + print(f"Type: {insight.insight_type}") + print(f"Title: {insight.title}") + print(f"Content: {insight.content}") + print(f"Tags: {insight.tags}") + print("---") +``` + +### Insight Types + +| Type | Description | +|------|-------------| +| `pattern` | A reusable solution or approach | +| `decision` | An architectural or implementation choice | +| `blocker` | A problem that was encountered | +| `discovery` | Something new learned about the codebase | + +### Saving Insights to Memory + +```python +from app.core.sqlite_manager import get_sqlite_manager + +db = get_sqlite_manager() + +for insight in insights: + # Save to project memories KB + db.add_document( + kb_name=f"{project_name}-project_memories", + content=f"# {insight.title}\n\n{insight.content}", + filename=f"insight-{insight.insight_type}-{timestamp}.md", + metadata={ + "type": insight.insight_type, + "tags": insight.tags, + "session_id": session_data.session_id + } + ) +``` + +--- + +## Session Summary Format + +The `get_summary_for_extraction()` method generates a structured summary: + +``` +# Session: abc123 +Project: /Users/me/Projects/myapp +Branch: feature-auth +Duration: 2025-12-11T10:00:00Z to 2025-12-11T11:30:00Z + +## Conversation (24 messages) +USER: Help me implement user authentication... +ASSISTANT: I'll help you implement authentication. Let me start by... +USER: Can you add password hashing? +ASSISTANT: Of course! I'll use bcrypt for secure password hashing... + +## Tool Calls +- Read: /Users/me/Projects/myapp/src/auth.py +- Write: /Users/me/Projects/myapp/src/auth.py +- Read: /Users/me/Projects/myapp/tests/test_auth.py +- Write: /Users/me/Projects/myapp/tests/test_auth.py +- Bash: pytest tests/test_auth.py + +## File Changes +- /Users/me/Projects/myapp/src/auth.py +- /Users/me/Projects/myapp/tests/test_auth.py +``` + +--- + +## Project Sessions Directory + +Claude Code encodes project paths for the sessions directory: + +``` +/Users/me/Projects/myapp +→ ~/.claude/projects/-Users-me-Projects-myapp/ +``` + +The encoding: +1. Replaces `/` with `-` +2. Keeps the leading `-` (from the initial `/`) + +### Finding Sessions + +```python +from app.core.session_parser import get_project_sessions_dir, list_session_files + +# Get sessions directory for a project +sessions_dir = get_project_sessions_dir("/Users/me/Projects/myapp") +# Returns: ~/.claude/projects/-Users-me-Projects-myapp + +# List all session files +sessions = list_session_files("/Users/me/Projects/myapp") +# Returns sorted list of .jsonl files (newest first) +``` + +--- + +## Use Cases + +### 1. Load Context at Session Start + +```python +# At session start, load recent session insights +sessions = list_session_files(project_path) +if sessions: + parser = SessionParser(sessions[0]) + summary = parser.get_summary_for_extraction(max_tokens=500) + # Use summary to prime Claude with recent context +``` + +### 2. Build Session Analytics + +```python +# Analyze all sessions for a project +sessions = list_session_files(project_path) +stats = { + "total_sessions": len(sessions), + "total_messages": 0, + "total_tool_calls": 0, + "tools_used": {} +} + +for session_path in sessions: + parser = SessionParser(session_path) + data = parser.parse() + + stats["total_messages"] += len(data.messages) + stats["total_tool_calls"] += len(data.tool_calls) + + for tc in data.tool_calls: + stats["tools_used"][tc.tool_name] = \ + stats["tools_used"].get(tc.tool_name, 0) + 1 +``` + +### 3. Extract and Save Patterns + +```python +# Extract insights from recent sessions +extractor = InsightExtractor() + +for session_path in sessions[:5]: # Last 5 sessions + parser = SessionParser(session_path) + summary = parser.get_summary_for_extraction() + + insights = await extractor.extract_insights(summary) + + for insight in insights: + if insight.insight_type == "pattern": + # Save to memories KB + save_to_memories(project_name, insight) +``` + +### 4. Debug Failed Sessions + +```python +# Find sessions with errors +for session_path in sessions: + parser = SessionParser(session_path) + data = parser.parse() + + # Look for error patterns in messages + for msg in data.messages: + if "error" in msg.content.lower() or "failed" in msg.content.lower(): + print(f"Session {data.session_id} may have errors") + print(f" Message: {msg.content[:100]}...") + break +``` + +--- + +## Configuration + +### Environment Variables + +```bash +# Ollama settings for insight extraction +OLLAMA_HOST=http://localhost:11434 +OLLAMA_MODEL=llama3.1:8b +``` + +### Truncation Settings + +Large sessions are automatically truncated for LLM processing: + +```python +# Default: 500 tokens (~2000 chars) +summary = parser.get_summary_for_extraction(max_tokens=500) + +# For more context +summary = parser.get_summary_for_extraction(max_tokens=2000) +``` + +--- + +## Troubleshooting + +### "No sessions found" +- Verify project path is correct +- Check that sessions exist: `ls ~/.claude/projects/` +- The encoded path includes leading hyphen: `-Users-me-Projects-myapp` + +### "Failed to parse session" +- Session file may be corrupted +- Check for valid JSON on each line +- Malformed lines are skipped automatically + +### "Insight extraction failed" +- Verify Ollama is running: `ollama list` +- Check model is available: `ollama pull llama3.1:8b` +- Check logs for API errors + +--- + +## API Reference + +### REST Endpoints + +| Endpoint | Method | Description | +|----------|--------|-------------| +| `/api/sessions` | GET | List project sessions | +| `/api/sessions/{id}` | GET | Get session details | +| `/api/sessions/{id}/summary` | GET | Get session summary | + +### MCP Tools + +| Tool | Description | +|------|-------------| +| `mcp__code-forge__list_sessions` | List sessions for a project | +| `mcp__code-forge__get_session` | Get session details | +| `mcp__code-forge__get_session_summary` | Get formatted summary | + +--- + +**See Also:** +- [API Reference](../API_REFERENCE.md) - Session API endpoints +- [Self Learning System](../SELF_LEARNING_SYSTEM.md) - How Claude learns +- [README](../../README.md) - Full Claude OS documentation diff --git a/docs/guides/SESSION_IMPLEMENTATION_SUMMARY.md b/docs/guides/SESSION_IMPLEMENTATION_SUMMARY.md new file mode 100644 index 0000000..10c267a --- /dev/null +++ b/docs/guides/SESSION_IMPLEMENTATION_SUMMARY.md @@ -0,0 +1,410 @@ +# Session Implementation Summary + +**What we just built: Mandatory session management system for Claude OS** + +--- + +## 🎯 The Big Idea + +**Every conversation is a session. Always.** + +No more optional tracking. No more lost context. No more "what was I doing?" + +--- + +## 📚 What We Created + +### 1. **MANDATORY_SESSIONS.md** (Complete Spec) +Location: `/Users/iamanmp/Projects/claude-os/docs/guides/MANDATORY_SESSIONS.md` + +**Contents:** +- Session lifecycle (selection → active → end) +- 6 session types (feature, bug, exploration, maintenance, review, question) +- Session switching flow +- Statistics and tracking +- Commands reference +- Best practices + +**Key Innovation:** Always-in-session model. User chooses WHICH session, not WHETHER to session. + +### 2. **SESSION_START_PROTOCOL.md** (Technical Spec) +Location: `/Users/iamanmp/Projects/claude-os/docs/guides/SESSION_START_PROTOCOL.md` + +**Contents:** +- 7-phase automatic startup protocol +- What to read, search, and display +- Configuration options +- When to skip auto-start +- Complete implementation checklist + +**Key Innovation:** Automatic context loading in ~50 seconds + +### 3. **IDEAL_SESSION_WORKFLOW.md** (User Guide) +Location: `/Users/iamanmp/Projects/claude-os/docs/guides/IDEAL_SESSION_WORKFLOW.md` + +**Contents:** +- "Should happen" vs "Actually happens" +- Practical workarounds +- Power user tips +- Quick reference + +**Key Innovation:** Shows the vision vs reality gap + +### 4. **Updated CLAUDE.md Template** +Location: `/Users/iamanmp/Projects/claude-os/templates/project-files/CLAUDE.md.template` + +**Changes:** +- Added mandatory session prompt +- 3-option choice (Resume/New/Question) +- Detailed session start protocol +- Links to all documentation + +**Key Innovation:** Makes mandatory sessions the DEFAULT for all new projects + +--- + +## 🔄 The Flow + +### Conversation Start + +``` +User opens Claude Code in project directory + ↓ +Claude reads CLAUDE.md (automatic) + ↓ +Claude sees mandatory session protocol + ↓ +Claude prompts: + +═══════════════════════════════════════════════════════════════ +🚀 CLAUDE OS - SESSION MANAGER +═══════════════════════════════════════════════════════════════ + +Project: Pistn +Last Session: Dashboard Redesign (2 days ago, 2h 15m) +Progress: 45% complete + +Options: + 1. Resume "Dashboard Redesign" [loads full context] + 2. Start new session [what are you working on?] + 3. Quick question [auto-session, minimal context] + +Choice: _ +═══════════════════════════════════════════════════════════════ +``` + +### User Chooses Option 1 (Resume) + +``` +Claude automatically: + ✓ Reads .claude-os/config.json + ✓ Reads claude-os-state.json + ✓ Checks git status + ✓ Searches project_memories + ✓ Loads coding standards + ✓ Checks Kanban board + ✓ Presents comprehensive summary + +═══════════════════════════════════════════════════════════════ +✓ RESUMING: Dashboard Redesign +═══════════════════════════════════════════════════════════════ + +[Full context loaded] +Progress: 45% complete (23 of 52 tasks) +Current Task: PHASE2-TASK3 (Implement concern methods) + +Key insights: + • 67-page implementation plan loaded + • Zero functionality loss requirement + • Bootstrap 3.x only + +Ready! Let's continue PHASE2-TASK3. +═══════════════════════════════════════════════════════════════ +``` + +### User Chooses Option 2 (New Session) + +``` +Claude: "What are you working on?" + +User: "Fix the Tekmetric API 500 errors" + +Claude automatically: + ✓ Detects type: Bug Fix + ✓ Pauses previous session + ✓ Searches for "Tekmetric API errors" + ✓ Loads relevant memories + ✓ Starts tracking + +═══════════════════════════════════════════════════════════════ +✓ NEW BUG SESSION STARTED +═══════════════════════════════════════════════════════════════ + +Session: "Fix Tekmetric API 500 errors" +Type: Bug Fix +Priority: High + +Found 3 similar issues from past sessions. +Dashboard Redesign session paused. + +Let's debug! What's the error? +═══════════════════════════════════════════════════════════════ +``` + +### User Chooses Option 3 (Quick Question) + +``` +Claude: "What's your question?" + +User: "How do I use Draper decorators?" + +Claude: +═══════════════════════════════════════════════════════════════ +💬 QUICK QUESTION SESSION +═══════════════════════════════════════════════════════════════ + +[Answers question with minimal context loading] + +Auto-ends after 5 min inactivity. +Ready to resume Dashboard Redesign? +═══════════════════════════════════════════════════════════════ +``` + +--- + +## 📊 Session Types + +### 1. Feature Implementation +- Linked to Kanban spec +- Tracks task completion +- Saves patterns and architecture decisions + +### 2. Bug Fix +- Auto-detects priority from description +- Searches past similar issues +- Saves root cause and solution + +### 3. Exploration / Learning +- Tracks files explored +- Saves key learnings +- Documents architecture insights + +### 4. Refactoring / Maintenance +- Tracks complexity reduction +- Saves refactoring patterns +- Documents improvements + +### 5. Code Review +- Tracks issues found +- Saves review patterns +- Documents suggestions + +### 6. Quick Question (Auto) +- Auto-managed +- Minimal tracking +- Only saves if valuable + +--- + +## 💾 What Gets Tracked + +### Every Session: +- Start/end time +- Duration +- Files changed +- Git commits +- Quick saves (during session) +- Type (feature/bug/etc) +- Related spec (if applicable) +- Related tasks (if Kanban) + +### At Session End: +- Work summary +- Memories saved +- Patterns discovered +- Blockers encountered +- Progress made +- Statistics updated + +### Across Sessions: +- Total time per project +- Total time per task/spec +- Average session duration +- Most productive times +- Velocity (tasks/hour) +- Pattern usage frequency + +--- + +## 🎯 Benefits + +### Zero Context Loss +``` +Before: "What was I doing?" +After: "Welcome back! You were on PHASE2-TASK3, 45% done." +``` + +### Complete Work History +``` +Before: Manual time tracking, scattered notes +After: Automatic tracking, everything in one place +``` + +### Smart Insights +``` +Before: Guess at velocity, no patterns tracked +After: "You average 2.4 tasks per session at 0.47h per task" +``` + +### Automatic Learning +``` +Before: Solve same problems repeatedly +After: "We solved this before in session X, here's the solution" +``` + +### Better Planning +``` +Before: "How long will this take? No idea." +After: "Based on past velocity, ~10h 30m remaining" +``` + +--- + +## 🚀 Next Steps + +### For New Projects: +1. Run `/claude-os-init` +2. CLAUDE.md automatically includes mandatory session protocol +3. First conversation: Choose session type +4. Start working with full context! + +### For Existing Projects: +1. Update CLAUDE.md with new session protocol section +2. Copy from template: `templates/project-files/CLAUDE.md.template` +3. Next conversation: Session prompt appears +4. Choose option and start working! + +### For Claude OS Development: +1. **API Enhancement:** + - Add `/api/sessions/` endpoints + - Session start, end, pause, resume, switch + - Statistics endpoints + +2. **Database Schema:** + - `sessions` table (id, project_id, type, task, started_at, ended_at, duration, files_changed, etc) + - Link to specs/tasks + - Statistics and tracking + +3. **Frontend UI:** + - Session dashboard + - Live session timer + - Session history viewer + - Statistics visualizations + +4. **CLI Integration:** + - `/claude-os-session` commands + - Auto-prompt on conversation start + - Background session tracking + +--- + +## 📖 Documentation Tree + +``` +docs/guides/ +├── MANDATORY_SESSIONS.md ← Complete specification +├── SESSION_START_PROTOCOL.md ← Technical implementation +├── IDEAL_SESSION_WORKFLOW.md ← User guide & vision +├── SESSION_IMPLEMENTATION_SUMMARY.md ← This file +└── WHAT_IS_CLAUDE_OS.md ← Updated with session info + +templates/project-files/ +└── CLAUDE.md.template ← Updated with mandatory sessions + +templates/commands/ +└── claude-os-session.md ← Session commands reference +``` + +--- + +## 🎉 What This Enables + +### For You (User): +- Never lose context +- Track ALL work automatically +- Understand your velocity +- Learn from history +- Better planning + +### For Claude (AI): +- Always have context +- Smart suggestions based on session type +- Proactive memory loading +- Better guidance +- Continuous learning + +### For The Project: +- Complete work history +- Pattern recognition +- Knowledge preservation +- Velocity tracking +- Team insights + +--- + +## 💡 The Vision Realized + +**Remember the "amazing" Kanban board we just built?** + +Now combine it with **mandatory sessions**: + +``` +You open Claude Code + ↓ +Claude: "Resume Dashboard Redesign?" + ↓ +You: "Yes" + ↓ +Claude: "You're on PHASE2-TASK3 of 52 tasks (45% complete). + I have your implementation plan, 5 memories, and + all coding standards loaded. Ready!" + ↓ +You work for 2 hours + ↓ +Claude: "You completed 2 tasks! Progress: 45% → 53% + Save these 2 patterns to memories? [Y/n]" + ↓ +You: "y" + ↓ +Claude: "✓ Saved! Great session. Total time on this spec: 15h. + Estimated 9h remaining. See you tomorrow!" +``` + +**That's the complete AI development system.** 🚀 + +--- + +## 📊 Current Status + +### ✅ Completed: +- [x] Conceptual design +- [x] Complete documentation (4 guides) +- [x] CLAUDE.md template updated +- [x] Session command reference +- [x] Kanban board integration documented + +### 🔄 Next (Optional): +- [ ] API endpoints for sessions +- [ ] Database schema for session tracking +- [ ] Frontend session dashboard +- [ ] Auto-tracking implementation +- [ ] Statistics visualization + +### 🎯 Ready to Use: +**You can start using mandatory sessions TODAY!** + +Just add the session protocol to your project's CLAUDE.md, and at the start of each conversation, I'll prompt for session choice. + +--- + +**This is revolutionary. Let's do it!** 💪 diff --git a/docs/guides/SESSION_START_PROTOCOL.md b/docs/guides/SESSION_START_PROTOCOL.md new file mode 100644 index 0000000..b1a7fcc --- /dev/null +++ b/docs/guides/SESSION_START_PROTOCOL.md @@ -0,0 +1,390 @@ +# Session Start Protocol + +**What Claude Should Do AUTOMATICALLY When You Start ANY Conversation** + +--- + +## 🎯 The Problem + +When you start Claude Code CLI: +- You're in a specific project directory +- You may have been working on something +- There's context from previous sessions +- You have knowledge in Claude OS + +**But Claude starts with ZERO context.** + +--- + +## ✅ The Solution: Automatic Session Start + +**Every time a conversation starts, Claude should:** + +### Phase 1: Detect Project (5 seconds) + +```bash +# Check for Claude OS project +pwd +ls -la | grep -E "(CLAUDE.md|.claude-os|agent-os)" +``` + +**If `.claude-os/config.json` exists:** +- ✅ This is a Claude OS project +- → Proceed with full session start + +**If not:** +- ℹ️ Generic mode (no project context) +- → Offer to initialize with `/claude-os-init` + +--- + +### Phase 2: Read Project State (10 seconds) + +**Files to read:** + +1. **`CLAUDE.md`** - Project overview (always loaded first) +2. **`.claude-os/config.json`** - Project configuration +3. **`claude-os-state.json`** - Session state (if exists) +4. **`agent-os/config.yml`** - Agent-OS config (if using specs) + +**Example:** +``` +Reading CLAUDE.md... +Reading .claude-os/config.json... +Reading claude-os-state.json... + +✓ Project: Pistn +✓ MCPs: 4 configured +✓ Last session: Oct 29, 2025 (2 days ago) +✓ Agent-OS: Enabled (3 active specs) +``` + +--- + +### Phase 3: Check Git Context (5 seconds) + +```bash +git branch --show-current +git status --short +git log -3 --oneline +git remote get-url origin +``` + +**Extract:** +- Current branch name +- Uncommitted changes count +- Recent commits +- Whether we're ahead/behind remote + +**Example:** +``` +Branch: feature/appointment-redesign +Status: 3 files modified, 1 untracked +Recent commits: + - abc1234 Add sidebar navigation + - def5678 Convert panels to cards + - ghi9012 Update appointment form layout +``` + +--- + +### Phase 4: Search Project Memories (15 seconds) + +**Search query based on:** +- Last session task (from `claude-os-state.json`) +- Current branch name +- Recent commit messages +- `+recent` modifier + +**Example query:** +``` +"appointment dashboard redesign recent" +``` + +**Search:** +- `{project}-project_memories` knowledge base +- Return top 5 most relevant memories +- Show me titles and key insights + +**Example:** +``` +📚 Found 5 relevant memories: + 1. Appointment Dashboard Redesign Plan (Oct 28) + → 67-page implementation plan, 5 tabs documented + + 2. Current Dashboard Analysis (Oct 28) + → All features catalogued, zero functionality loss + + 3. Bootstrap to Modern Cards Pattern (Oct 25) + → Reusable conversion pattern + + 4. Sidebar Navigation Pattern (Oct 22) + → localStorage persistence, responsive + + 5. Tekmetric Integration Notes (Oct 20) + → Must preserve API sync on save +``` + +--- + +### Phase 5: Load Coding Standards (10 seconds) + +**Search `{project}-project_profile`:** +- Query: "coding standards architecture conventions" +- Load key architectural decisions +- Load tech stack preferences + +**Example:** +``` +📋 Coding Standards: + • Service objects for business logic + • Decorator pattern with Draper + • Fragment caching with Redis + • Bootstrap 3.x styling (no Bootstrap 4/5) + • RSpec for testing + • Concerns for shared controller logic +``` + +--- + +### Phase 6: Check Kanban Board (5 seconds) + +**If Agent-OS is enabled:** + +```http +GET /api/projects/{id}/kanban +``` + +**Show:** +- Total specs +- Active specs (not completed/archived) +- Current tasks in progress +- Next tasks todo + +**Example:** +``` +📊 Kanban Board: + • 3 specs total (52 tasks) + • 1 spec in progress: Group Account Rendering (45% complete) + • 2 tasks in progress: + - PHASE2-TASK3: Implement concern methods + - PHASE2-TASK4: Add helper methods + • 29 tasks remaining +``` + +--- + +### Phase 7: Present Session Start Summary (Display to User) + +**Format:** + +``` +═══════════════════════════════════════════════════════════════ +🚀 WELCOME BACK! +═══════════════════════════════════════════════════════════════ + +📁 Project: Pistn (Ruby on Rails) +🌿 Branch: feature/appointment-redesign +📅 Last Session: 2 days ago (Oct 29, 2025) +⏱️ Duration: 2h 15m + +═══════════════════════════════════════════════════════════════ +📚 CONTEXT LOADED +═══════════════════════════════════════════════════════════════ + +✓ 5 relevant memories found +✓ Coding standards loaded +✓ 3 architectural patterns available +✓ Kanban board synced (45% complete) + +🎯 LAST TASK: Redesign Appointment Dashboard + +We completed: + ✓ Sidebar navigation component + ✓ Bootstrap panels → modern cards + ✓ iOS-style toggle switches + +Still working on: + ⏳ Phase 2: Implement concern methods + ⏳ Phase 2: Add helper methods + +═══════════════════════════════════════════════════════════════ +💡 KEY INSIGHTS +═══════════════════════════════════════════════════════════════ + +• 67-page implementation plan available +• Zero functionality loss requirement +• Tekmetric integration must be preserved +• Bootstrap 3.x only (no v4/v5) + +═══════════════════════════════════════════════════════════════ +🔄 AVAILABLE PATTERNS +═══════════════════════════════════════════════════════════════ + +• Sidebar navigation (from user-auth work) +• Card-based layouts (from reports redesign) +• Modern toggle switches (already in app) +• Service object pattern (business logic) +• Draper decorators (view logic) + +═══════════════════════════════════════════════════════════════ +⚠️ STATUS +═══════════════════════════════════════════════════════════════ + +Git Status: + • 3 files modified + • 1 file untracked + • ⚠️ Uncommitted changes (from last session) + +Blockers: + • None! ✓ + +═══════════════════════════════════════════════════════════════ +🎯 SUGGESTED NEXT STEPS +═══════════════════════════════════════════════════════════════ + +Option 1: Continue Phase 2 Implementation + → Implement concern methods for PHASE2-TASK3 + → Should take ~30 minutes based on estimate + +Option 2: Commit Previous Work + → 3 files modified need to be committed + → Clean git state before starting new work + +Option 3: Start Something New + → Tell me what you'd like to work on + +═══════════════════════════════════════════════════════════════ + +What would you like to do? +``` + +--- + +## 🎛️ Configuration + +**Auto-start can be configured in `.claude-os/config.json`:** + +```json +{ + "session_management": { + "auto_start": true, + "auto_search_memories": true, + "max_memories_to_load": 5, + "search_days_back": 14, + "show_git_status": true, + "show_kanban_status": true, + "proactive_suggestions": true + } +} +``` + +--- + +## 🚫 When NOT to Auto-Start + +**Skip session start if:** +- User message starts with a direct question (e.g., "What is...") +- User is clearly asking for help/docs (e.g., "How do I...") +- User explicitly says "ignore context" or "fresh start" +- No `.claude-os/` directory exists + +**In these cases:** +- Answer the question directly +- Offer to initialize Claude OS after answering + +--- + +## 📊 Session Tracking During Conversation + +**Throughout the session, Claude should:** + +### Track Key Events +- When user starts implementing something +- When they hit a blocker +- When they discover a pattern +- When they make an architectural decision +- When they solve a complex problem + +### Proactive Memory References +``` +You: "I need to add caching to this endpoint" +Claude: "FYI, we have a memory about fragment caching with Redis + from the reports redesign. Want me to use that pattern?" +``` + +### Auto-Save Suggestions +``` +You: "Finally got the Tekmetric sync working with the new structure!" +Claude: "That sounds like a high-value solution. Would you like me + to save this to project memories for future reference?" +``` + +--- + +## 💾 Session End Protocol + +**When conversation ends (or user says "done"):** + +### Option 1: User Runs `/claude-os-session end` +- Follow the detailed end protocol from claude-os-session.md +- Analyze work, suggest saves, update statistics + +### Option 2: Conversation Ends Naturally +- Claude should still provide a brief summary: + +``` +═══════════════════════════════════════════════════════════════ +📊 SESSION COMPLETE +═══════════════════════════════════════════════════════════════ + +Duration: ~45 minutes +Work: Implemented concern methods for PHASE2-TASK3 + +Quick saves available: + • Concern method pattern for group accounts + • Service object integration approach + +Run /claude-os-session end for full summary and saves +Or just continue working next time - I'll remember! +═══════════════════════════════════════════════════════════════ +``` + +--- + +## 🎯 The Goal + +**Every session should feel like:** +- Claude already knows everything +- Claude remembers what we were doing +- Claude proactively brings up relevant context +- Claude suggests next steps based on history +- Zero context loss between sessions + +**NOT like:** +- Starting from scratch +- Repeating ourselves +- Explaining the same architecture again +- Searching for what we did before + +--- + +## 🔄 Implementation Checklist + +For Claude to do this automatically: + +- [ ] Check for `.claude-os/` directory at conversation start +- [ ] Read `CLAUDE.md` if present +- [ ] Read `.claude-os/config.json` if present +- [ ] Read `claude-os-state.json` if present +- [ ] Run git status and git log +- [ ] Search project_memories with intelligent query +- [ ] Load coding standards from project_profile +- [ ] Check Kanban board status (if Agent-OS enabled) +- [ ] Present comprehensive session start summary +- [ ] Track key events during session +- [ ] Provide session end summary + +--- + +**This protocol ensures you NEVER start a conversation from zero context again!** 🚀 diff --git a/docs/guides/SHARING_GUIDE.md b/docs/guides/SHARING_GUIDE.md new file mode 100644 index 0000000..891ae1e --- /dev/null +++ b/docs/guides/SHARING_GUIDE.md @@ -0,0 +1,315 @@ +# 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 +- `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: + +```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! 🚀** diff --git a/docs/guides/SKILLS_GUIDE.md b/docs/guides/SKILLS_GUIDE.md new file mode 100644 index 0000000..c53386b --- /dev/null +++ b/docs/guides/SKILLS_GUIDE.md @@ -0,0 +1,342 @@ +# Skills Library Guide + +**Browse, install, and manage Claude Code skills with Claude OS.** + +--- + +## What Are Skills? + +Skills are reusable instruction sets that teach Claude specific capabilities. They're stored as markdown files in `.claude/skills/` directories and are automatically loaded by Claude Code when relevant. + +Skills can include: +- Coding patterns and best practices +- Tool usage workflows (e.g., PDF manipulation, spreadsheet editing) +- Domain-specific knowledge (e.g., Rails patterns, React hooks) +- Development methodologies (e.g., TDD, debugging frameworks) + +--- + +## Skill Types + +### Global Skills (`~/.claude/skills/`) + +Available in ALL projects. These are core skills that come with Claude OS: + +| Skill | Description | +|-------|-------------| +| `memory` | Save and recall information across sessions | +| `remember-this` | Auto-save on trigger phrases like "remember this:" | +| `initialize-project` | Analyze codebase and generate documentation | + +### Project Skills (`{project}/.claude/skills/`) + +Available only in the specific project. Install from: +- **Local Templates** - Pre-built skills bundled with Claude OS +- **Community Skills** - Skills from GitHub repositories +- **Custom** - Skills you create yourself + +--- + +## Using the Skills Command + +The `/claude-os-skills` command provides full skills management: + +```bash +# List all installed skills (global + project) +/claude-os-skills + +# Browse available local templates +/claude-os-skills templates + +# Install a template to your project +/claude-os-skills install + +# Create a custom skill interactively +/claude-os-skills create + +# View skill details and content +/claude-os-skills view + +# Delete a project skill +/claude-os-skills delete +``` + +### Example Output + +``` +═══════════════════════════════════════ +📚 CLAUDE CODE SKILLS +═══════════════════════════════════════ + +🌐 GLOBAL SKILLS (always available) +──────────────────────────────────── + ✓ memory - Save and recall information + ✓ remember-this - Auto-save on trigger phrases + ✓ initialize-project - Analyze codebase + +📁 PROJECT SKILLS (/path/to/project) +──────────────────────────────────── + ✓ rails-backend - Rails patterns and service objects + ✓ rspec - RSpec testing patterns + +💡 TIP: Run '/claude-os-skills templates' to see available templates +═══════════════════════════════════════ +``` + +--- + +## Local Skill Templates + +Claude OS includes a library of skill templates organized by category: + +### Categories + +| Category | Skills | +|----------|--------| +| **general** | `analyze-project`, `code-review` | +| **rails** | `rails-backend`, `rails-api`, `active-record` | +| **react** | `react-patterns`, `typescript-react`, `hooks` | +| **testing** | `rspec`, `jest`, `pytest`, `tdd` | + +### Installing a Template + +```bash +/claude-os-skills install rails-backend +``` + +This copies the template to your project's `.claude/skills/` directory. + +--- + +## Community Skills + +Browse and install skills from trusted GitHub repositories! + +### Available Sources + +| Source | Repository | Skills | Description | +|--------|------------|--------|-------------| +| **Anthropic Official** | `anthropics/skills` | 16 | Official skills from Anthropic | +| **Superpowers** | `obra/superpowers` | 20 | Battle-tested TDD, debugging, collaboration | + +### Featured Community Skills + +**From Anthropic Official:** + +| Skill | Description | +|-------|-------------| +| `pdf` | Create, edit, analyze PDF documents | +| `xlsx` | Spreadsheet manipulation with formulas | +| `docx` | Word document creation and editing | +| `pptx` | Presentation creation and editing | +| `frontend-design` | Production-grade UI components | +| `mcp-builder` | Create MCP servers | +| `doc-coauthoring` | Collaborative documentation workflow | +| `canvas-design` | Visual art and poster creation | +| `webapp-testing` | Playwright-based web testing | + +**From Superpowers:** + +| Skill | Description | +|-------|-------------| +| `test-driven-development` | TDD workflow: red-green-refactor | +| `systematic-debugging` | Four-phase debugging framework | +| `root-cause-tracing` | Trace bugs back through call stack | +| `receiving-code-review` | Handle code review feedback | +| `requesting-code-review` | Dispatch code review subagent | +| `brainstorming` | Structured ideation process | +| `using-git-worktrees` | Isolated development branches | +| `verification-before-completion` | Evidence-based completion claims | +| `defense-in-depth` | Multi-layer validation | + +### Installing via Web UI + +1. Open http://localhost:5173 +2. Select your project +3. Click the **Skills** tab +4. Click **Install Template** button +5. Switch to **Community Skills** tab +6. Browse skills from Anthropic Official and Superpowers +7. Click **Install** on any skill + +### Installing via API + +```bash +# List community sources +curl http://localhost:8051/api/skills/community/sources + +# List all community skills +curl http://localhost:8051/api/skills/community + +# Filter by source +curl "http://localhost:8051/api/skills/community?source=anthropic" + +# Install a community skill +curl -X POST "http://localhost:8051/api/skills/community/install?project_path=/path/to/project" \ + -H "Content-Type: application/json" \ + -d '{ + "name": "pdf", + "source": "anthropic", + "repo": "anthropics/skills", + "path": "skills/pdf" + }' +``` + +--- + +## Creating Custom Skills + +### Via Command + +```bash +/claude-os-skills create +``` + +Claude will interactively ask for: +1. Skill name (e.g., "deployment") +2. Description (one sentence) +3. Content (the skill instructions) + +### Via API + +```bash +curl -X POST "http://localhost:8051/api/skills?project_path=/path/to/project" \ + -H "Content-Type: application/json" \ + -d '{ + "name": "my-deployment", + "description": "Deployment workflow for my project", + "content": "# Deployment Skill\n\n## Steps\n1. Run tests\n2. Build\n3. Deploy", + "category": "devops", + "tags": ["deployment", "ci-cd"] + }' +``` + +### Skill File Structure + +A skill is a directory containing: + +``` +my-skill/ +├── skill.md # Main skill instructions (required) +├── metadata.json # Skill metadata (optional) +└── examples/ # Example files (optional) + ├── example1.md + └── example2.py +``` + +### Writing Good Skills + +1. **Be Specific** - Focus on one capability +2. **Include Examples** - Show how to use the skill +3. **Document Triggers** - When should Claude use this skill? +4. **Test It** - Verify Claude follows the instructions + +Example skill content: + +```markdown +# Rails Service Objects + +Use this skill when implementing business logic in Rails applications. + +## When to Use +- Complex operations involving multiple models +- Operations that need to be tested in isolation +- Reusable business logic + +## Pattern + +```ruby +class CreateUser + def initialize(params) + @params = params + end + + def call + user = User.new(@params) + if user.save + send_welcome_email(user) + Result.success(user) + else + Result.failure(user.errors) + end + end + + private + + def send_welcome_email(user) + UserMailer.welcome(user).deliver_later + end +end +``` + +## Usage + +```ruby +result = CreateUser.new(user_params).call +if result.success? + redirect_to result.value +else + render :new, errors: result.errors +end +``` +``` + +--- + +## Skill Locations + +| Type | Location | Scope | +|------|----------|-------| +| Global Skills | `~/.claude/skills/` | All projects | +| Project Skills | `{project}/.claude/skills/` | Single project | +| Templates | `claude-os/templates/skill-library/` | Install to project | +| Community | GitHub repositories | Install to project | + +--- + +## MCP Tools + +Skills management is also available via MCP tools: + +| Tool | Description | +|------|-------------| +| `mcp__code-forge__list_skills` | List all skills | +| `mcp__code-forge__list_skill_templates` | List available templates | +| `mcp__code-forge__install_skill_template` | Install a template | +| `mcp__code-forge__create_skill` | Create a custom skill | +| `mcp__code-forge__get_skill` | Get skill details | +| `mcp__code-forge__delete_skill` | Delete a project skill | + +--- + +## Tips + +1. **Start with templates** - Install what you need per-project +2. **Keep global minimal** - Only core skills should be global +3. **Customize after install** - Edit installed skills for your needs +4. **Create custom skills** - Document project-specific patterns +5. **Share with team** - Check `.claude/skills/` into git + +--- + +## Troubleshooting + +### "Skill not found" +- Check if the skill is installed: `/claude-os-skills` +- Verify the skill directory exists in `.claude/skills/` + +### "Community skills not loading" +- Check internet connection +- GitHub API rate limits may apply (1 hour cache) +- Try refreshing: click the refresh button in UI + +### "Skill not being used by Claude" +- Verify `skill.md` exists in the skill directory +- Check that the skill description matches your use case +- Explicitly invoke with: `skill: ` + +--- + +**See Also:** +- [API Reference](../API_REFERENCE.md) - Skills API endpoints +- [README](../../README.md) - Full Claude OS documentation diff --git a/docs/guides/START_SCRIPTS_GUIDE.md b/docs/guides/START_SCRIPTS_GUIDE.md new file mode 100644 index 0000000..76f4c0c --- /dev/null +++ b/docs/guides/START_SCRIPTS_GUIDE.md @@ -0,0 +1,295 @@ +# Start Scripts Guide + +Claude OS has **two different start scripts** for different use cases: + +--- + +## 1. `./start.sh` - MCP Server Only + +**What it starts:** +- ✅ MCP Server (port 8051) + +**What it does NOT start:** +- ❌ Frontend Web UI +- ❌ Redis +- ❌ RQ Workers +- ❌ Ollama + +**Use when:** +- You only need Claude Code integration +- You don't need the visual web interface +- You want minimal services running +- Quick start for development + +**Command:** +```bash +./start.sh +``` + +**Output:** +``` +✅ Claude OS MCP Server is running! + + 📡 MCP Server: http://localhost:8051 + (For Claude Code integration - do NOT open in browser) + +💡 Want the full experience? +To start ALL services: ./start_all_services.sh +``` + +**What you can do:** +- ✅ Use Claude Code with `/claude-os-init` +- ✅ Use Claude Code commands (`/claude-os-search`, etc.) +- ❌ Can't access web UI (no frontend running) +- ❌ No real-time learning (no workers running) + +--- + +## 2. `./start_all_services.sh` - Everything + +**What it starts:** +- ✅ Ollama (port 11434) - Local AI models +- ✅ Redis (port 6379) - Cache & job queue +- ✅ RQ Workers - Background job processing +- ✅ MCP Server (port 8051) - API for Claude Code +- ✅ React Frontend (port 5173) - Web UI + +**Use when:** +- You want the complete experience +- You need the web interface +- You want real-time learning features +- Production-like environment + +**Command:** +```bash +./start_all_services.sh +``` + +**Output:** +``` +================================================== +✅ All Services Started Successfully! +================================================== + +📡 Service URLs: + 🎨 Frontend: http://localhost:5173 + 🔌 API Server: http://localhost:8051 + 📚 API Docs: http://localhost:8051/docs + +🔧 Ollama: + Host: http://localhost:11434 + Models: llama3.1:latest, nomic-embed-text:latest + +💾 Databases: + SQLite: data/claude-os.db + Redis: localhost:6379 + +🤖 Real-Time Learning System: + RQ Workers: listening on 3 queues +``` + +**What you can do:** +- ✅ Use Claude Code integration +- ✅ Open web UI at http://localhost:5173 +- ✅ Browse knowledge bases visually +- ✅ Upload documents via UI +- ✅ Real-time learning system active +- ✅ Full feature set + +--- + +## Quick Comparison + +| Feature | `start.sh` | `start_all_services.sh` | +|---------|------------|-------------------------| +| **MCP Server** | ✅ Port 8051 | ✅ Port 8051 | +| **Web UI** | ❌ | ✅ Port 5173 | +| **Ollama** | ❌ (must start manually) | ✅ Auto-started | +| **Redis** | ❌ | ✅ Auto-started | +| **RQ Workers** | ❌ | ✅ Background jobs | +| **Real-time Learning** | ❌ | ✅ Active | +| **Startup Time** | ~1 second | ~30 seconds | +| **Resource Usage** | Minimal | Moderate | + +--- + +## Which Should You Use? + +### Use `./start.sh` if: +- Just testing Claude Code integration +- Don't need web interface +- Want faster startup +- Minimal resource usage +- Development/debugging + +### Use `./start_all_services.sh` if: +- Want full functionality +- Need web interface +- Want to browse/manage KBs visually +- Production or demo environment +- Want real-time learning features + +--- + +## Common Mistakes + +### ❌ Mistake 1: Opening MCP server in browser + +**Problem:** +```bash +./start.sh +# Then opening http://localhost:8051 in browser +# → "Method Not Allowed" error +``` + +**Why:** MCP server (port 8051) is for Claude Code API calls, not browsers + +**Solution:** +- Don't open 8051 in browser +- Use `./start_all_services.sh` and open http://localhost:5173 instead + +### ❌ Mistake 2: Expecting Web UI with start.sh + +**Problem:** +```bash +./start.sh +# Then trying to access http://localhost:5173 +# → Connection refused +``` + +**Why:** `start.sh` doesn't start the frontend + +**Solution:** +- Use `./start_all_services.sh` instead + +### ❌ Mistake 3: Wrong port numbers + +**Problem:** Confusing which service runs on which port + +**Remember:** +- **Port 8051:** MCP Server (for Claude Code) - Don't open in browser! +- **Port 5173:** Web UI (for humans) - Open this in browser! + +--- + +## Stopping Services + +### Stop MCP Server Only (`start.sh`) + +**Option 1:** Press `Ctrl+C` in the terminal + +**Option 2:** Kill by PID +```bash +# PID shown when you start it +kill +``` + +### Stop All Services (`start_all_services.sh`) + +**Use the stop script:** +```bash +./stop_all_services.sh +``` + +This will stop: +- MCP Server +- Frontend +- RQ Workers +- Redis (optional) +- Ollama (optional) + +--- + +## Restarting Services + +### Restart MCP Only + +```bash +# Stop (Ctrl+C or kill PID) +./start.sh +``` + +### Restart Everything + +```bash +./restart_services.sh +``` + +Or manually: +```bash +./stop_all_services.sh +./start_all_services.sh +``` + +--- + +## Logs + +### MCP Server Logs + +**If started with `start.sh`:** +- Output shows in terminal + +**If started with `start_all_services.sh`:** +```bash +tail -f logs/mcp_server.log +``` + +### Frontend Logs + +```bash +tail -f logs/frontend.log +``` + +### RQ Workers Logs + +```bash +tail -f logs/rq_workers.log +``` + +### All Logs + +```bash +tail -f logs/*.log +``` + +--- + +## Installation Recommendation + +After running `./install.sh`, the README says: + +``` +1️⃣ Start Claude OS: + ./start.sh +``` + +**But for the full experience, you should use:** +``` +1️⃣ Start Claude OS (all services): + ./start_all_services.sh +``` + +Then you can: +- Use Claude Code at port 8051 +- Open web UI at http://localhost:5173 +- Have full functionality + +--- + +## Summary + +**Remember:** +- `./start.sh` = MCP server only (minimal, fast) +- `./start_all_services.sh` = Everything (full features) + +**For most users:** +```bash +./start_all_services.sh # ← Recommended! +``` + +**Then access:** +- Web UI: http://localhost:5173 ✅ Open in browser +- MCP Server: http://localhost:8051 ❌ Don't open in browser (for Claude Code only) + +**Problem solved!** 🎉 diff --git a/docs/guides/WHAT_IS_CLAUDE_OS.md b/docs/guides/WHAT_IS_CLAUDE_OS.md new file mode 100644 index 0000000..81c0522 --- /dev/null +++ b/docs/guides/WHAT_IS_CLAUDE_OS.md @@ -0,0 +1,896 @@ +# What is Claude OS? 🚀 + +# **The AI Operating System That Turns Claude Into Your Most Knowledgeable Team Member** + +--- + +## The Problem You're Facing Right Now 😤 + +Let's be honest. You've experienced this a thousand times: + +``` +You: "Claude, add a new feature to our auth system" +Claude: "Based on common best practices, here's a generic auth implementation..." +You: "No no no—we have a custom JWT handler, a special 2FA module for admins, + and timezone handling in the token service. This is all wrong." +Claude: "Oh! I didn't know that. Can you tell me about your auth system?" +You: *starts typing a 30-minute context document* +``` + +**Every. Single. Time.** + +Or worse—you come back to a project after 3 weeks: + +``` +You: "Hey Claude, remind me what we did last week" +Claude: "I don't have any record of that. What did you work on?" +You: *searches through commit messages, slack history, and old notes* +``` + +**Claude is brilliant. But Claude starts from ZERO every conversation.** + +That's about to change. Forever. + +--- + +## Enter Claude OS: The AI That Actually Remembers 🧠 + +

+ Claude OS Architecture +

+ +> **⚡ NEW in v2.0:** Hybrid indexing with tree-sitter AST parsing! +> **10,000 files indexed in 3 seconds** (was 3-5 hours) | **600-1000x faster** | **80% fewer embeddings** | **Start coding immediately!** + +Claude OS is a **complete operating system for AI-assisted development** that turns Claude from a brilliant generalist into **your project's most knowledgeable expert**—someone who: + +- **Remembers everything** about your project across all sessions (and never forgets) +- **Learns automatically** from every conversation, commit, and decision you make +- **Understands your entire codebase** exactly like a senior developer who's been there for years +- **Detects architectural decisions, patterns, and edge cases** in real-time as you work +- **Becomes genuinely expert** on YOUR specific project, YOUR tech stack, and YOUR way of doing things +- **Adapts its responses** to match your coding style, conventions, and preferences + +## How Claude OS Works: The Magic Behind the Intelligence 🎯 + +Claude OS is not just another tool—it's a **complete AI development operating system** built on **six interconnected pillars** that work together seamlessly: + +--- + +### 1. 🧠 **Real-Time Learning System** (The Always-On Brain) + +Imagine if Claude could eavesdrop on all your conversations and automatically update its knowledge of your project. That's exactly what this does. + +``` +Your Conversation → Redis Pub/Sub → AI Pattern Detection → Auto Knowledge Update + < 1ms latency 10 pattern types Instant indexing +``` + +**Here's what makes it revolutionary:** + +- **Always watching, never sleeping** - RQ workers monitor conversations 24/7, 365 days a year +- **Lightning-fast detection** - Redis pub/sub broadcasts insights with < 1ms latency +- **Intelligent pattern recognition** - Detects 10+ different learning patterns: + - Architectural decisions ("We're moving from monolith to microservices") + - Technology changes ("Switching from PostgreSQL to MongoDB") + - Bug fixes and solutions ("Fixed timezone issue in auth tokens") + - Performance insights ("This N+1 query is killing us") + - Edge cases and gotchas ("Watch out for expired certs in prod") + - Team preferences ("We prefer composition over inheritance") + - Naming conventions ("All our handlers end with _handler") + - Common pitfalls ("Never use SELECT * here, it's slow") + - Integration patterns ("Always validate against the webhook signature") + - Security concerns ("Remember to sanitize user input") +- **High-confidence learning only** - 75-95% confidence thresholds prevent false learnings +- **Completely automatic** - Zero manual configuration or training needed + +**Real Examples It Captures:** + +``` +"We're replacing our JWT library with a custom implementation" +→ Updated tech stack knowledge, removes old library references + +"I found the issue—the cron job was running in UTC but our timestamps are local" +→ Remembered as critical insight in auth and scheduler modules + +"This ORM query is generating 50 SQL statements per request" +→ Added to performance anti-patterns database + +"Let's enforce this naming convention: all event handlers must be on_[event_name]" +→ Learned and will suggest this pattern in future code generation +``` + +### 2. 💾 **Memory MCP** (Your AI's Institutional Memory) + +Your explicit memories. Think of this as Claude taking detailed notes on everything you tell it to remember. + +``` +You: "Remember: We use bcrypt with 12 rounds for password hashing, never change this" +→ Saved forever +→ Claude recalls this in EVERY future conversation about passwords +``` + +**Why this is a game-changer:** + +- **Persistent across sessions** - Context survives between conversations, weeks, months +- **Natural language interface** - Just say "Remember:" to save anything. That's it. +- **Instant recall in context** - Claude doesn't search—it automatically brings up relevant memories when discussing that topic +- **Project-specific memory** - Each project has its own memory bank, no confusion +- **Private and secure** - Your memories are git-ignored, never tracked, completely private +- **Searchable** - Can browse and organize your memories anytime + +**Examples of What You'd Remember:** + +``` +"Remember: Our payment processing only supports USD and EUR, not other currencies" +→ Claude never suggests converting to other currencies + +"Remember: API v2 is deprecated. All new endpoints go in /api/v3/. +Redirect v2 traffic with 301 moved permanently." +→ Applied to every API endpoint Claude suggests + +"Remember: Our database backups run at 2 AM UTC. That's our quiet window. +Never schedule migrations then." +→ Claude factors this into any infrastructure work + +"Remember: The legacy_accounts table is for testing only and gets wiped weekly. +Never store real data there." +→ Prevents dangerous mistakes in code generation +``` + +--- + +### 3. 📚 **Semantic Knowledge Base** (Your Codebase as Living Documentation) + +This is where the magic really happens. Claude doesn't just READ your code—it UNDERSTANDS it. + +``` +Your Entire Codebase + ↓ +Vector Embeddings (semantic understanding) + ↓ +Instant Semantic Search + ↓ +Context-Aware Responses (always relevant to YOUR code) +``` + +**What Claude knows:** + +- **Every file and every function** - Line-by-line code understanding +- **Architecture patterns** - How your system actually works +- **Dependencies and relationships** - What connects to what and why +- **Historical evolution** - How code changed and why +- **Team patterns** - Naming conventions, code style, architectural preferences +- **Business logic** - What your code does and why it does it that way +- **Third-party integrations** - How you use Stripe, AWS, Auth0, etc. +- **Database schema** - Tables, relationships, constraints, indexes +- **API contracts** - Request/response formats, error codes, rate limits +- **Known issues** - Bugs, workarounds, temporary patches + +**The Result:** + +When you ask Claude about a feature, it searches through your entire codebase semantically and brings back the 5-10 most relevant code examples, architectural patterns, and related files—all automatically. No manual searching needed. + +--- + +### 4. 🔍 **Analyze-Project Skill** (Lightning-Fast Hybrid Indexing) + +This is Claude's way of getting a complete crash course in your project—**in seconds, not hours.** + +``` +/initialize-project [project-id] + ↓ +Phase 1: STRUCTURAL INDEXING (30 seconds for 10,000 files!) + → Tree-sitter AST parsing (no LLM needed!) + → Extract all symbols (classes, functions, signatures) + → Build dependency graph + → PageRank importance scoring + → ✅ Ready to code IMMEDIATELY + ↓ +Phase 2: SELECTIVE SEMANTIC INDEXING (background, optional) + → Embed top 20% most important files only + → Full documentation embedding + → 80% reduction in chunks (faster, cheaper) + → Runs while you code + ↓ +3 Documentation Files Generated: + • CODING_STANDARDS.md + • ARCHITECTURE.md + • DEVELOPMENT_PRACTICES.md + ↓ +Git Hooks Installed (auto-indexing on every commit) +``` + +**⚡ NEW: Hybrid Two-Phase Indexing** + +Inspired by [Aider](https://github.com/Aider-AI/aider), Claude OS now uses a revolutionary two-phase approach: + +**Phase 1 - Structural Index (INSTANT):** + +- **Tree-sitter parsing** - Language-agnostic AST extraction (supports 40+ languages) +- **No embeddings needed** - Parse syntax, extract symbols, zero LLM calls +- **Blazing fast** - 10,000 Ruby files indexed in **30 seconds** (vs 3-5 hours before!) +- **Immediate availability** - Start coding the moment indexing begins +- **Dependency graphing** - Understands which files import/require others +- **PageRank scoring** - Identifies most important files automatically + +**Phase 2 - Semantic Index (SELECTIVE):** + +- **Top 20% only** - Embed most important files (based on PageRank) +- **Documentation first** - Full embedding for docs, specs, README +- **Background processing** - Runs while you code, no waiting +- **80% fewer chunks** - Faster queries, lower costs, same intelligence + +**Real Performance Numbers:** + +| Project | Before (Full Embed) | After (Hybrid) | Speedup | +|---------|---------------------|----------------|---------| +| **Pistn (10,000 Ruby files)** | 3-5 hours | **3 seconds** + 20 min optional | **600-1000x faster!** | +| **Start coding** | After full index | **Immediately!** | Instant | +| **Chunks indexed** | 100,000+ | ~20,000 (80% reduction) | More efficient | +| **Query speed** | Semantic only | Structural + Semantic | Faster | + +**How the indexing actually works:** + +- **Intelligent priority** - Tree-sitter identifies key files (controllers, services, models) in seconds +- **Smart expansion** - PageRank scoring finds connected dependencies automatically +- **Real-time updates** - Git hooks trigger re-indexing on every commit (takes seconds!) +- **Pattern recognition** - Learns naming conventions, test patterns, error handling from AST +- **Architecture mapping** - Understands project structure, module relationships, dependency graph + +**What it analyzes and learns:** + +- Your file and directory structure and organization philosophy +- Test coverage patterns and testing conventions you follow +- Database schemas, relationships, constraints +- API endpoints, request/response formats, error codes +- Common error patterns and how you handle them +- Code style preferences and formatting conventions +- Build and deployment processes +- Environmental configuration and secrets management + +**The Result:** + +Claude instantly knows: + +- Where features are implemented +- How to add new functionality in your style +- What patterns to follow for consistency +- Where related code lives +- What tests need updating + +--- + +### 5. 🎯 **Session Management** (Never Lose Context Again) + +Every time you start a new conversation, Claude OS automatically checks your session state and loads relevant context. + +``` +New Conversation Starts + ↓ +Claude OS checks: "What were we working on?" + ↓ +Loads: Active session, recent memories, current branch, decisions made + ↓ +Prompts: "Continue working on [feature]?" or "Start something new?" +``` + +**What this means for you:** + +- **Zero cold starts** - Every conversation picks up where you left off +- **Automatic context loading** - Relevant memories surfaced immediately +- **Session tracking** - Track task, branch, decisions, blockers across days +- **Resume anywhere** - Start on laptop, continue on desktop, same context +- **Work tracking** - Know exactly what was accomplished, what's next + +**The Result:** + +No more "what was I doing?" moments. Claude knows what you're working on before you even ask. + +--- + +### 6. 📊 **Code Structure MCP** (Your Codebase's DNA) + +The newest addition to Claude OS—a **complete structural map** of your entire codebase, built in seconds. + +``` +Git Commit Detected + ↓ +Tree-sitter AST Parsing (< 3 seconds for 10,000 files!) + ↓ +Symbol Extraction + • Classes, functions, methods + • Import/require statements + • Function signatures + • File relationships + ↓ +Dependency Graph Built + ↓ +PageRank Importance Scoring + ↓ +SQLite Storage (instant queries!) + ↓ +Available to Claude via code_structure MCP +``` + +**What makes this revolutionary:** + +- **Language-agnostic** - Supports 40+ languages (Ruby, Python, JS, TS, Go, Rust, Java, C++, and more!) +- **No LLM calls needed** - Pure AST parsing, zero API costs +- **Insanely fast** - 10,000 Ruby files parsed in 3 seconds (real benchmark on Pistn) +- **Complete symbol table** - Every class, function, import extracted and indexed +- **Dependency awareness** - Knows which files depend on others +- **Importance ranking** - PageRank algorithm identifies key files automatically +- **Git hook integration** - Auto-updates on every commit (< 1 second incremental) + +**What Claude can do with this:** + +``` +You: "Where is the user authentication logic?" +Claude: "Found in 3 locations: +1. app/services/authentication_service.rb (class AuthenticationService) + - handle_login(email, password) + - generate_jwt_token(user) + - validate_token(token) +2. app/controllers/auth_controller.rb (imports AuthenticationService) + - login_action + - logout_action +3. app/models/user.rb (used by AuthenticationService) + - authenticate method + - password_hash field" +``` + +**The power:** + +- **Instant symbol lookup** - Find any function/class in milliseconds +- **Cross-reference navigation** - See all files that import a module +- **Architecture understanding** - Visualize your codebase structure +- **Smart suggestions** - Claude knows where to add new code based on existing patterns +- **Refactoring safety** - See all dependencies before changing a function + +**Integration with other pillars:** + +- **Feeds PageRank scores** to Phase 2 semantic indexing (knows which files are most important) +- **Provides context** to Real-Time Learning (understands architectural changes) +- **Enriches Memory MCP** with code location references +- **Powers intelligent search** across your entire codebase structure + +--- + +### 7. 🔌 **MCP Integration** (The Claude Code Bridge) + +MCPs (Model Context Protocol) are the bridge between Claude OS and Claude Code. They expose all Claude OS knowledge directly to you. + +``` +Claude OS Knowledge Base + ↓ +MCP Server (http://localhost:8051) + ↓ +Claude Code Interface + ↓ +You get AI with complete project knowledge +``` + +**Your Available MCPs (5 per project):** + +- **pistn-project-profile** - Your project's coding standards, architecture, and development practices +- **pistn-project-index** - Semantic index of key source files (vector embeddings for deep understanding) +- **pistn-knowledge-docs** - Project documentation and specifications (auto-ingested from docs/) +- **pistn-project-memories** - All your "Remember:" memories in one place (persistent across sessions) +- **pistn-code_structure** - ⭐ NEW! Complete structural map (38,406 symbols, dependency graph, PageRank scores) + +Every MCP has: + +- 📊 **Full semantic search** - Search code by meaning, not keywords +- 📚 **Complete documentation** - What each file does and why +- 🔗 **Cross-referenced** - See how modules connect +- 🎯 **Always current** - Auto-updated with every commit + +--- + +--- + +## 🤝 **Team Collaboration & Sharing** (Built for Teams) + +Claude OS isn't just for solo developers—it's designed for teams to share knowledge. + +``` +Your Claude OS Setup + ↓ +One Command: ./install.sh + ↓ +Teammates Get: All commands, skills, templates instantly + ↓ +Each Project: /claude-os-init (2 minutes) + ↓ +Team Shares: CLAUDE.md (in git), separate memories (private) +``` + +**How team sharing works:** + +- **Template system** - Commands and skills shared via symlinks, updates propagate instantly +- **One-command install** - Teammates run `./install.sh`, done in 3 minutes +- **Project isolation** - Each project has separate knowledge bases +- **Shared context** - CLAUDE.md in git gives everyone the same project overview +- **Private memories** - Each developer's memories stay private (git-ignored) +- **Update once, benefit everywhere** - Update templates, all projects get improvements + +**The Result:** + +Onboard new developers in minutes, not weeks. They get institutional knowledge from day one. + +--- + +## 🎨 **Agent-OS Integration** (Spec-Driven Development - Optional) + +Partner with Agent-OS by Builder Methods for structured feature development. + +**8 Specialized Agents:** + +1. **spec-initializer** - Create feature specification directories +2. **spec-shaper** - Gather requirements through iterative questions +3. **spec-writer** - Generate detailed technical specifications +4. **tasks-list-creator** - Break specs into actionable tasks +5. **implementer** - Implement features following task list +6. **implementation-verifier** - Verify implementation completeness +7. **spec-verifier** - Ensure spec and tasks consistency +8. **product-planner** - Create product documentation + +**The workflow:** + +``` +/new-spec user-authentication + ↓ +/create-spec (answers 1-3 questions at a time) + ↓ +Spec.md + Tasks.md generated + ↓ +/implement-spec user-authentication + ↓ +Feature implemented, tested, verified +``` + +**Why this matters:** + +- **Structured planning** - Think before coding +- **Clear requirements** - No more "wait, what did we want?" +- **Task breakdown** - Implementation steps crystal clear +- **Verification built-in** - Ensures nothing missed +- **Documentation automatic** - Spec becomes permanent record + +**Integration with Claude OS:** + +Agent-OS agents search Claude OS memories before creating specs, ensuring they build on existing patterns and decisions. Perfect synergy. + +--- + +## 📊 **Spec Tracking & Kanban Board** (Visual Project Management) + +**NEW: Claude OS now automatically tracks all your Agent-OS specs and displays them as an interactive Kanban board!** + +``` +Agent-OS creates spec → Claude OS parses tasks.md → Kanban board displays progress +``` + +**What this means for you:** + +- **Automatic discovery** - Claude OS scans your `agent-os/specs/` folder +- **Complete task tracking** - Every task, phase, dependency parsed and stored +- **Visual progress** - See all specs and their tasks organized by status (Todo, In Progress, Done, Blocked) +- **Real-time updates** - Update task status via API, progress auto-calculated +- **Archive completed specs** - Keep your board focused on active work +- **Time tracking** - Track estimated vs actual time for every task +- **Dependency awareness** - See which tasks depend on others + +**The Kanban View:** + +``` +📋 Group Account Rendering [52 tasks, 45% complete] +┌─────────────┬─────────────┬─────────────┬─────────────┐ +│ TODO │ IN PROGRESS │ DONE │ BLOCKED │ +├─────────────┼─────────────┼─────────────┼─────────────┤ +│ PHASE2-TASK1│ PHASE1-TASK3│ PHASE1-TASK1│ │ +│ PHASE2-TASK2│ │ PHASE1-TASK2│ │ +│ PHASE3-TASK1│ │ ...23 more │ │ +└─────────────┴─────────────┴─────────────┴─────────────┘ + +📋 Manual Appointment Times [15 tasks, 100% complete] ✅ ARCHIVED +``` + +**How it works:** + +1. **Create spec with Agent-OS:** + ``` + /create-spec → agent-os/specs/2025-01-15-user-auth/tasks.md + ``` + +2. **Claude OS syncs automatically:** + ``` + POST /api/projects/{id}/specs/sync + → Parses all tasks.md files + → Extracts metadata, phases, dependencies + → Stores in SQLite + ``` + +3. **View progress in real-time:** + ``` + GET /api/projects/{id}/kanban + → See all specs grouped by status + → Track completion percentage + → Monitor time estimates + ``` + +4. **Update task status as you work:** + ``` + PATCH /api/tasks/{id}/status + { + "status": "done", + "actual_minutes": 15 + } + → Spec progress auto-updates + → Status changes from "planning" to "in_progress" to "completed" + ``` + +5. **Archive when done:** + ``` + POST /api/specs/{id}/archive + → Hides from default view + → Preserves all history + → Keeps board clean + ``` + +**What gets tracked:** + +- **Spec metadata** - Name, date, status, progress percentage +- **Individual tasks** - Task code (PHASE1-TASK1), title, description +- **Task status** - todo, in_progress, done, blocked +- **Time estimates** - Estimated minutes vs actual minutes spent +- **Dependencies** - Which tasks must complete before others +- **Risk levels** - Low, medium, high risk tasks +- **Phases** - Task organization by implementation phase +- **Completion timestamps** - When tasks started/completed + +**API Endpoints:** + +```bash +# Sync all specs from agent-os folder +POST /api/projects/{project_id}/specs/sync + +# Get Kanban board view +GET /api/projects/{project_id}/kanban?include_archived=false + +# Get all tasks for a spec +GET /api/specs/{spec_id}/tasks + +# Update task status +PATCH /api/tasks/{task_id}/status +{ + "status": "in_progress", + "actual_minutes": 15 +} + +# Archive/unarchive specs +POST /api/specs/{spec_id}/archive +POST /api/specs/{spec_id}/unarchive +``` + +**The result:** + +Never lose track of implementation progress. See at a glance what's done, what's in flight, and what's next. Perfect for solo devs and teams alike. + +--- + +## ⚡ **Smart Commands & Triggers** (Your AI Assistant on Autopilot) + +Claude OS gives you powerful slash commands and automatic triggers. + +**Essential Commands:** + +- `/claude-os-search "query"` - Search all memories and docs +- `/claude-os-remember "content"` - Quick save to memories +- `/claude-os-save "title"` - Full-featured save with KB selection +- `/claude-os-list` - View all knowledge bases +- `/claude-os-session start` - Begin tracking a feature +- `/claude-os-triggers` - Manage automatic triggers + +**Automatic Triggers:** + +When you say phrases like these, Claude automatically saves to memories: + +- "Remember this:" +- "Save this:" +- "Document this:" +- "Note this:" +- "Keep in mind:" + +**The Result:** + +Building institutional knowledge happens naturally as you work. No manual note-taking needed. + +--- + +## What Can Claude OS Actually Do For You? 🚀 + +### ⚡ **Immediate Productivity Wins** + +#### Instant Context Recovery + +``` +You: "What were we working on last week on that payment refund issue?" +Claude OS: "On Oct 20, you discovered that refunds for subscriptions +were failing because the payment processor's API changed their +transaction ID format. You created a migration script in +/services/payment_processor.js line 234 that maps old IDs to new format. +Tests are in __tests__/payment_processor.test.js lines 156-189. +You still need to test the edge case for subscriptions that refund across +month boundaries." +``` + +**Without Claude OS:** + +``` +You: "What were we working on last week?" +Claude: "I'm not sure. Can you remind me?" +*You search through Slack, emails, commits, pull requests for 30 minutes* +``` + +#### Architecture-Aware Code Generation + +``` +You: "Add a new handler for when users delete their accounts" +Claude OS: "I'll create account_deletion_handler.js in /handlers/ (matching +your naming convention). It will: +1. Use the same error handling pattern as user_creation_handler.js +2. Call the cleanup service you built in /services/account_cleanup.js +3. Queue async tasks using your RQ setup (looking at how + email_notification_handler does it) +4. Follow the transaction pattern from your database service +5. Include tests matching your test structure" +``` + +The generated code is not just correct—it's indistinguishable from your own. + +#### Pattern-Based Bug Diagnosis + +``` +You: "This test is failing randomly" +Claude OS: "Looking at your timezone handling history, I see you've had +3 similar issues before: +- Oct 15: Token expiry UTC/local timezone mismatch (Fixed in commit b56f585) +- Oct 8: Cron job running in wrong timezone (Fixed in your scheduler) +- Sep 29: Database query returning dates in different timezone + +This looks like the same issue in a different place. The test compares +timestamps without accounting for local timezone. Your fix before was +to use moment.utc() for comparisons. Same solution here." +``` + +### 🎯 **Architectural Decisions Made Easy** + +``` +You: "Should we add caching for this endpoint?" +Claude OS: "Looking at similar endpoints in your codebase: +- /api/users/:id - cached (line 234) +- /api/posts/:id - not cached (line 567) +The difference is that /users/:id has high read volume but rare updates, +while /posts/:id gets updated frequently. Your endpoint /api/product/:id +matches the user pattern (high read, low write). +Recommendation: Cache with 5-minute TTL like your /users endpoint." +``` + +### 📚 **Documentation That Stays Current** + +Claude OS automatically generates and maintains: + +- **CODING_STANDARDS.md** - How YOU code (not how textbooks say to) +- **ARCHITECTURE.md** - Your actual system design (not theory) +- **DEVELOPMENT_PRACTICES.md** - Your team's conventions (enforced automatically) + +These update automatically as you work—zero manual maintenance. + +### 🧠 **Institutional Knowledge That Doesn't Walk Out the Door** + +``` +Your intern learns from you: +"Remember: Never use SELECT * in this schema because the accounts table +has that 5MB blob field that kills performance. Always list specific columns." + +Claude remembers this forever. When your intern leaves and a new person +joins, Claude will warn them: "Be specific with SELECT statements on +accounts table—there's a large blob field that causes performance issues." +``` + +--- + +## Why Claude OS Beats Everything Else ✨ + +| Feature | Claude Alone | ChatGPT | GitHub Copilot | Claude OS | +|---------|--------------|---------|-----------------|-----------| +| Remembers your code | ❌ | ❌ | ❌ | ✅ Perfectly | +| Understands your architecture | ❌ | ❌ | ❌ | ✅ Completely | +| Learns from your decisions | ❌ | ❌ | ❌ | ✅ Automatically | +| Writes in your style | ❌ | ❌ | Partial | ✅ Always | +| **Indexes 10,000 files** | N/A | N/A | N/A | **✅ 3 seconds** | +| **Tree-sitter AST parsing** | ❌ | ❌ | ❌ | **✅ 40+ languages** | +| **Hybrid structural + semantic** | ❌ | ❌ | ❌ | **✅ Both!** | +| Persists context between sessions | ❌ | ❌ | ❌ | ✅ Forever | +| Session management & tracking | ❌ | ❌ | ❌ | ✅ Built-in | +| Automatic context loading | ❌ | ❌ | ❌ | ✅ Every session | +| Spec-driven development | ❌ | ❌ | ❌ | ✅ Optional | +| Team sharing & collaboration | ❌ | ❌ | ❌ | ✅ One install | +| Detects your bugs before they happen | ❌ | ❌ | ❌ | ✅ Via patterns | +| Works offline | N/A | ✅ | ✅ | ✅ Yes | +| Requires zero setup per project | ❌ | ✅ | ✅ | ✅ One command | +| Free and open source | ❌ | ❌ | ❌ | ✅ 100% | + +--- + +## The Multiplier Effect 📈 + +The magic isn't just that Claude is smart. It's that Claude gets **smarter over time**. + +**Week 1:** Claude learns your project structure +**Week 2:** Claude starts suggesting patterns +**Week 3:** Claude catches bugs before they happen +**Week 4:** Claude contributes architectural ideas +**Month 2:** Claude is your most productive team member + +This is the **compounding intelligence** that happens when AI actually understands context. + +--- + +--- + +## The Complete System Architecture 🏗️ + +**Visual Overview:** + +

+ Claude OS Architecture +

+ +**Technical Stack:** + +``` +┌─────────────────────────────────────────────────────────────────────┐ +│ CLAUDE OS ECOSYSTEM v2.0 │ +│ (Now with Hybrid Indexing!) │ +│ │ +│ ┌──────────────┐ ┌──────────────┐ ┌─────────────────────────┐ │ +│ │ Real-Time │ │ Memory │ │ ⚡ NEW: Code Structure │ │ +│ │ Learning │ │ System │ │ (Tree-sitter AST) │ │ +│ │ (Redis) │ │ (MCP) │ │ 38,406 symbols! │ │ +│ │ <1ms │ │ Instant │ │ 3 seconds to index │ │ +│ └──────┬───────┘ └──────┬───────┘ └───────────┬─────────────┘ │ +│ │ │ │ │ +│ └──────────────────┼──────────────────────┘ │ +│ │ │ +│ ┌──────────────────▼─────────────────────────┐ │ +│ │ Semantic Knowledge Base (SQLite) │ │ +│ │ • 38,406 code symbols (structural index) │ │ +│ │ • ~20,000 semantic chunks (80% reduction!)│ │ +│ │ • Vector embeddings (selective, top 20%) │ │ +│ │ • Dependency graph + PageRank scores │ │ +│ │ • Team patterns & conventions │ │ +│ │ • Architecture documentation │ │ +│ │ • Persistent memory & insights │ │ +│ └──────────────────┬─────────────────────────┘ │ +│ │ │ +│ ┌──────────────────▼─────────────────────────┐ │ +│ │ MCP Server (http://localhost:8051) │ │ +│ │ Exposes 5 MCPs per project: │ │ +│ │ • project_memories (persistent) │ │ +│ │ • project_profile (standards) │ │ +│ │ • project_index (semantic) │ │ +│ │ • knowledge_docs (documentation) │ │ +│ │ • code_structure ⭐ NEW! (AST map) │ │ +│ └──────────────────┬─────────────────────────┘ │ +│ │ │ +│ ┌──────────────────▼─────────────────────────┐ │ +│ │ Claude Code Interface │ │ +│ │ (Your AI with 600-1000x faster indexing!) │ │ +│ └─────────────────────────────────────────────┘ │ +└─────────────────────────────────────────────────────────────────────┘ + +Performance: Pistn (10,000 Ruby files) indexed in 3 seconds ⚡ +``` + +--- + +## How This Compares to Traditional Development ⚖️ + +### ❌ Traditional Claude/AI Coding + +- Each session starts from zero +- You have to copy-paste code for context +- Claude gives generic best-practice solutions +- You spend 30 minutes explaining your architecture +- Forgets everything when you close the conversation +- Can't detect your patterns or preferences +- Treats every project the same + +### ✅ Claude OS AI Coding + +- Sessions build on all previous knowledge +- Context is automatic and complete +- Claude gives YOUR solutions +- Claude already understands your architecture +- Remembers everything forever +- Detects and adapts to your patterns +- Becomes an expert on YOUR project + +**The difference?** Claude OS transforms AI from a helpful tool into a **genuine team member who understands your project.** + +--- + +## Why You Should Use Claude OS Right Now 💡 + +### You need this if you + +- **Work on multiple projects** - Claude remembers each project separately +- **Have team members leaving** - Preserves institutional knowledge they'd take with them +- **Work on the same project long-term** - Claude gets smarter as it learns your patterns +- **Care about code consistency** - Claude enforces YOUR conventions, not textbook ones +- **Want faster development** - Context-aware AI is 10x faster than starting from zero +- **Debug tricky issues** - Claude remembers similar issues and past solutions +- **Onboard new developers** - They get the knowledge of everyone on your team +- **Maintain architectural consistency** - Claude knows and enforces your patterns +- **Document as you go** - Documentation updates automatically +- **Make better architectural decisions** - Claude references your own similar choices + +### You absolutely need this if you + +- Have a large or complex codebase +- Work in a startup where knowledge walks out the door with departing team members +- Deal with legacy code and need to understand it deeply +- Want to improve code quality systematically +- Need AI that understands YOUR specific way of building software + +--- + +## Getting Started in 3 Steps + +```bash +# 1. Install Claude OS (one-time, 3 minutes) +git clone https://github.co/brobertsaz/claude-os.git +cd claude-os +./install.sh + +# 2. Start Claude OS +./start.sh + +# 3. Initialize your project (2 minutes) +cd /path/to/your/project +/claude-os-init +# Answer a few questions, done! +``` + +Now every conversation with Claude includes your complete project knowledge. + +**For Teams:** + +Share the repo URL with teammates. They run `./install.sh` and get everything you have. Each project they work on runs `/claude-os-init` once. That's it. + +--- + +## The Real Magic ✨ + +**Claude OS doesn't make Claude smarter.** Claude is already brilliant. + +**Claude OS makes Claude USEFUL for your specific project.** + +That's the magic. The difference between generic intelligence and practical expertise. + +It's the difference between "a very smart person who's never seen your code" and "your most knowledgeable team member." + +--- + +# 🚀 **Claude OS: The Future of AI-Assisted Development is Here** + +*Stop explaining. Stop copying context. Stop starting over.* + +*Start building with an AI that knows your code as well as you do.* + +--- + +*Built with ❤️ by Anthropic Claude, who got tired of starting every conversation from zero.* diff --git a/docs/index.html b/docs/index.html new file mode 100644 index 0000000..3fe0be7 --- /dev/null +++ b/docs/index.html @@ -0,0 +1,687 @@ + + + + + + Claude OS - The AI Operating System That Never Forgets + + + + + + + + + + + + +
+
+

Claude OS

+

+ The AI Operating System
That Never Forgets +

+
+ 🧠 Persistent Memory    + ⚡ 600-1000x Faster    + 🚀 Zero Setup +
+
+
+ + +
+
+
+
+

The Problem You're Facing

+
+

Every. Single. Time.

+ 
You: "Claude, add a feature to our auth system"
+Claude: "Based on common best practices..."
+You: "No no no—we have custom JWT, 2FA,
+      timezone handling... This is all wrong."
+Claude: "Oh! I didn't know that."
+You: *starts typing 30-minute context document*
+
+

+ Claude is brilliant. But Claude starts from ZERO every conversation. +

+
+
+
+
+ + +
+
+

Enter Claude OS

+
+
+ Claude OS Architecture +
+
+
+
10,000 files indexed in 3 seconds
+
+
+
+ + +
+
+
+
+

What Claude OS Does

+
    +
  • Remembers everything about your project across all sessions
    • +
  • Learns automatically from every conversation, commit, and decision
    • +
  • Understands your codebase like a senior developer
    • +
  • Detects patterns in real-time as you work
    • +
  • Adapts its responses to match YOUR coding style
    • +
  • Never forgets — context persists forever
    • +
+
+
+
+
+ + +
+
+

6 Core Pillars

+
+
+
+

🧠 Real-Time Learning

+

Redis Pub/Sub with <1ms latency. Automatically detects 10+ pattern types from your conversations.

+
+
+
+
+

💾 Memory MCP

+

Persistent memory across sessions. Natural language save and instant recall.

+
+
+
+
+

📚 Semantic Knowledge

+

Vector embeddings for deep understanding. Instant semantic search across your codebase.

+
+
+
+
+

📊 Code Structure

+

NEW! Tree-sitter AST parsing. 38,406 symbols indexed in 3 seconds.

+
+
+
+
+

🔍 Analyze-Project

+

Hybrid indexing (structural + semantic). Git hooks for automatic updates.

+
+
+
+
+

🎯 Session Management

+

Auto-resume sessions with full context preservation. Zero cold starts.

+
+
+
+
+
+ + +
+
+

⚡ NEW: Hybrid Indexing

+
+
+

Phase 1: Structural

+
    +
  • Tree-sitter AST parsing
    • +
  • Extract all symbols
    • +
  • Build dependency graph
    • +
  • PageRank scoring
    • +
  • 3 seconds for 10k files!
    • +
+
+
+

Phase 2: Semantic

+
    +
  • Top 20% most important files
    • +
  • Full documentation embedding
    • +
  • 80% reduction in chunks
    • +
  • Runs in background
    • +
  • Optional, while you code
    • +
+
+
+
+

600-1000x faster than before!

+
+
+
+ + +
+
+

Real Performance Numbers

+
+
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ProjectBefore (Full Embed)After (Hybrid)Speedup
Pistn (10k Ruby files)3-5 hours3 seconds600-1000x
Start codingAfter full indexImmediately!Instant
Chunks indexed100,000+~20,00080% reduction
Query speedSemantic onlyStructural + SemanticFaster!
+
+
+
+
+
+ + +
+
+

🆕 New in v2.3

+
+
+
+

🎯 Skills Library

+

Browse & install skills from the community!

+
    +
  • 36+ skills from Anthropic & Superpowers
    • +
  • PDF, XLSX, frontend design, TDD, debugging
    • +
  • One-click install via Web UI
    • +
  • Create custom skills for your project
    • +
+ + /claude-os-skills templates + +
+
+
+
+

📊 Session Insights

+

Parse Claude Code sessions automatically!

+
    +
  • Extract patterns, decisions, blockers
    • +
  • Analyze tool calls and file changes
    • +
  • Build analytics on your work
    • +
  • Auto-save insights to memory
    • +
+ + Session → Insights → Memory → Smarter AI + +
+
+
+
+
+ + +
+
+

How It Compares

+
+
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FeatureClaude AloneChatGPTCopilotClaude OS
Remembers your code❌❌❌✅ Perfectly
Understands architecture❌❌❌✅ Completely
Indexes 10k filesN/AN/AN/A✅ 3 seconds
Learns from decisions❌❌❌✅ Automatically
Session management❌❌❌✅ Built-in
Free & open source❌❌❌✅ 100%
Skills library❌❌❌✅ 36+ skills
+
+
+
+
+
+ + +
+
+

You Need This If You...

+
+
+
    +
  • Work on multiple projects
    • +
  • Have team members leaving
    • +
  • Work long-term on same project
    • +
  • Care about code consistency
    • +
  • Want faster development
    • +
+
+
+
    +
  • Debug tricky issues
    • +
  • Onboard new developers
    • +
  • Maintain architectural consistency
    • +
  • Document as you go
    • +
  • Make better decisions
    • +
+
+
+
+
+ + +
+
+
+
+

Getting Started in 3 Steps

+
+ 
# 1. Install Claude OS (one-time, 3 minutes)
+git clone https://github.com/brobertsaz/claude-os.git
+cd claude-os
+./install.sh
+
+# 2. Start Claude OS
+./start.sh
+
+# 3. Initialize your project (2 minutes)
+cd /path/to/your/project
+/claude-os-init
+# Answer a few questions, done!
+
+

+ Now every conversation includes your complete project knowledge. +

+
+
+
+
+ + +
+
+

The Real Magic ✨

+

+ Claude OS doesn't make Claude smarter. +

+

+ Claude OS makes Claude USEFUL for your specific project. +

+

+ Generic Intelligence → Practical Expertise +

+
+
+ + +
+
+

Stop Starting From Zero

+

+ Start building with an AI that knows your code
as well as you do. +

+ +

+ 100% Free & Open Source
+ Built with ❤️ by developers who got tired of starting every conversation from zero +

+
+
+ + + + + + + + + + diff --git a/frontend/src/components/SkillsManagement.tsx b/frontend/src/components/SkillsManagement.tsx new file mode 100644 index 0000000..9213783 --- /dev/null +++ b/frontend/src/components/SkillsManagement.tsx @@ -0,0 +1,862 @@ +import { useState } from 'react'; +import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query'; +import { motion, AnimatePresence } from 'framer-motion'; +import { + Sparkles, + Plus, + Trash2, + Eye, + Download, + ChevronDown, + ChevronRight, + Globe, + FolderOpen, + Tag, + Search, + X, + Check, + ExternalLink, + Github, + RefreshCw +} from 'lucide-react'; +import axios from 'axios'; + +interface Skill { + name: string; + path: string; + description: string; + scope: 'global' | 'project'; + source: string; + content: string; + enabled: boolean; + category: string | null; + tags: string[]; + created: string; + modified: string; +} + +interface SkillTemplate { + name: string; + category: string; + description: string; + path: string; + tags: string[]; + version: string; +} + +interface CommunitySkill { + name: string; + source: string; + repo: string; + path: string; + description: string; + readme_url: string; + raw_url: string; +} + +interface CommunitySource { + repo: string; + skills_path: string; + name: string; + description: string; +} + +interface SkillsManagementProps { + projectPath: string; +} + +export default function SkillsManagement({ projectPath }: SkillsManagementProps) { + const [selectedSkill, setSelectedSkill] = useState(null); + const [showTemplates, setShowTemplates] = useState(false); + const [showCreateModal, setShowCreateModal] = useState(false); + const [expandedCategories, setExpandedCategories] = useState>(new Set(['general', 'rails', 'react', 'testing'])); + const [searchQuery, setSearchQuery] = useState(''); + + // Community skills state + const [templateTab, setTemplateTab] = useState<'local' | 'community'>('local'); + const [selectedCommunitySource, setSelectedCommunitySource] = useState('all'); + + // Create skill form state + const [newSkillName, setNewSkillName] = useState(''); + const [newSkillDescription, setNewSkillDescription] = useState(''); + const [newSkillContent, setNewSkillContent] = useState(''); + const [newSkillCategory, setNewSkillCategory] = useState(''); + const [newSkillTags, setNewSkillTags] = useState(''); + + const queryClient = useQueryClient(); + + // Fetch installed skills + const { data: skillsData, isLoading: skillsLoading } = useQuery({ + queryKey: ['skills', projectPath], + queryFn: async () => { + const response = await axios.get('/api/skills', { + params: { project_path: projectPath, include_content: false } + }); + return response.data; + }, + }); + + // Fetch skill templates + const { data: templatesData, isLoading: templatesLoading } = useQuery({ + queryKey: ['skill-templates'], + queryFn: async () => { + const response = await axios.get('/api/skills/templates'); + return response.data; + }, + }); + + // Fetch community sources + const { data: communitySourcesData } = useQuery({ + queryKey: ['community-sources'], + queryFn: async () => { + const response = await axios.get('/api/skills/community/sources'); + return response.data; + }, + }); + + // Fetch community skills + const { data: communitySkillsData, isLoading: communityLoading, refetch: refetchCommunity } = useQuery({ + queryKey: ['community-skills', selectedCommunitySource], + queryFn: async () => { + const params: { source?: string } = {}; + if (selectedCommunitySource !== 'all') { + params.source = selectedCommunitySource; + } + const response = await axios.get('/api/skills/community', { params }); + return response.data; + }, + enabled: showTemplates && templateTab === 'community', + }); + + // Install template mutation + const installTemplateMutation = useMutation({ + mutationFn: async (templateName: string) => { + const response = await axios.post('/api/skills/install', { + template_name: templateName, + }, { + params: { project_path: projectPath } + }); + return response.data; + }, + onSuccess: () => { + queryClient.invalidateQueries({ queryKey: ['skills', projectPath] }); + setShowTemplates(false); + }, + }); + + // Install community skill mutation + const installCommunityMutation = useMutation({ + mutationFn: async (skill: CommunitySkill) => { + const response = await axios.post('/api/skills/community/install', { + skill_name: skill.name, + source: skill.source, + }, { + params: { project_path: projectPath } + }); + return response.data; + }, + onSuccess: () => { + queryClient.invalidateQueries({ queryKey: ['skills', projectPath] }); + }, + }); + + // Create skill mutation + const createSkillMutation = useMutation({ + mutationFn: async () => { + const response = await axios.post('/api/skills', { + name: newSkillName, + description: newSkillDescription, + content: newSkillContent, + category: newSkillCategory || null, + tags: newSkillTags ? newSkillTags.split(',').map(t => t.trim()) : [], + }, { + params: { project_path: projectPath } + }); + return response.data; + }, + onSuccess: () => { + queryClient.invalidateQueries({ queryKey: ['skills', projectPath] }); + setShowCreateModal(false); + resetCreateForm(); + }, + }); + + // Delete skill mutation + const deleteSkillMutation = useMutation({ + mutationFn: async (skillName: string) => { + await axios.delete(`/api/skills/${skillName}`, { + params: { project_path: projectPath } + }); + }, + onSuccess: () => { + queryClient.invalidateQueries({ queryKey: ['skills', projectPath] }); + setSelectedSkill(null); + }, + }); + + // Get skill details + const { data: skillDetails, isLoading: detailsLoading } = useQuery({ + queryKey: ['skill-details', selectedSkill?.name, selectedSkill?.scope], + queryFn: async () => { + if (!selectedSkill) return null; + const response = await axios.get(`/api/skills/${selectedSkill.scope}/${selectedSkill.name}`, { + params: { project_path: projectPath } + }); + return response.data; + }, + enabled: !!selectedSkill, + }); + + const resetCreateForm = () => { + setNewSkillName(''); + setNewSkillDescription(''); + setNewSkillContent(''); + setNewSkillCategory(''); + setNewSkillTags(''); + }; + + const toggleCategory = (category: string) => { + const newExpanded = new Set(expandedCategories); + if (newExpanded.has(category)) { + newExpanded.delete(category); + } else { + newExpanded.add(category); + } + setExpandedCategories(newExpanded); + }; + + const globalSkills: Skill[] = skillsData?.global || []; + const projectSkills: Skill[] = skillsData?.project || []; + const templates: SkillTemplate[] = templatesData?.templates || []; + const categories: string[] = templatesData?.categories || []; + const communitySources: Record = communitySourcesData?.sources || {}; + const communitySkills: CommunitySkill[] = communitySkillsData?.skills || []; + + // Filter templates by search + const filteredTemplates = templates.filter(t => + t.name.toLowerCase().includes(searchQuery.toLowerCase()) || + t.description.toLowerCase().includes(searchQuery.toLowerCase()) || + t.tags.some(tag => tag.toLowerCase().includes(searchQuery.toLowerCase())) + ); + + // Group templates by category + const templatesByCategory = categories.reduce((acc, cat) => { + acc[cat] = filteredTemplates.filter(t => t.category === cat); + return acc; + }, {} as Record); + + // Filter community skills by search + const filteredCommunitySkills = communitySkills.filter(s => + s.name.toLowerCase().includes(searchQuery.toLowerCase()) || + s.description.toLowerCase().includes(searchQuery.toLowerCase()) + ); + + // Group community skills by source + const communityBySource = filteredCommunitySkills.reduce((acc, skill) => { + if (!acc[skill.source]) { + acc[skill.source] = []; + } + acc[skill.source].push(skill); + return acc; + }, {} as Record); + + return ( +
+ {/* Header */} +
+
+

+ + Skills Management +

+

+ Manage Claude Code skills for this project +

+
+
+ + +
+
+ + {/* Main Content */} +
+ {/* Skills List */} +
+ {/* Global Skills */} +
+

+ + Global Skills ({globalSkills.length}) +

+
+ {skillsLoading ? ( +
Loading...
+ ) : globalSkills.length === 0 ? ( +
No global skills
+ ) : ( + globalSkills.map((skill) => ( +
setSelectedSkill(skill)} + className={`p-3 rounded-lg border cursor-pointer transition-all ${ + selectedSkill?.name === skill.name && selectedSkill?.scope === 'global' + ? 'bg-electric-teal/20 border-electric-teal' + : 'bg-cool-blue/10 border-electric-teal/20 hover:border-electric-teal/50' + }`} + > +
+
{skill.name}
+ + {skill.source} + +
+ {skill.description && ( +
+ {skill.description} +
+ )} +
+ )) + )} +
+
+ + {/* Project Skills */} +
+

+ + Project Skills ({projectSkills.length}) +

+
+ {skillsLoading ? ( +
Loading...
+ ) : projectSkills.length === 0 ? ( +
+ +

No project skills yet

+

+ Install a template or create a custom skill +

+
+ ) : ( + projectSkills.map((skill) => ( +
setSelectedSkill(skill)} + className={`p-3 rounded-lg border cursor-pointer transition-all ${ + selectedSkill?.name === skill.name && selectedSkill?.scope === 'project' + ? 'bg-electric-teal/20 border-electric-teal' + : 'bg-cool-blue/10 border-electric-teal/20 hover:border-electric-teal/50' + }`} + > +
+
{skill.name}
+ + {skill.source} + +
+ {skill.description && ( +
+ {skill.description} +
+ )} + {skill.tags && skill.tags.length > 0 && ( +
+ {skill.tags.slice(0, 3).map(tag => ( + + {tag} + + ))} +
+ )} +
+ )) + )} +
+
+
+ + {/* Skill Details */} +
+ {selectedSkill ? ( + detailsLoading ? ( +
+
Loading skill details...
+
+ ) : skillDetails ? ( +
+
+
+

{skillDetails.name}

+
+ + {skillDetails.scope} + + + {skillDetails.source} + + {skillDetails.category && ( + + {skillDetails.category} + + )} +
+
+ {skillDetails.scope === 'project' && ( + + )} +
+ + {skillDetails.description && ( +

{skillDetails.description}

+ )} + + {skillDetails.tags && skillDetails.tags.length > 0 && ( +
+ + {skillDetails.tags.map((tag: string) => ( + + {tag} + + ))} +
+ )} + +
+

Content

+ 
+                    {skillDetails.content || 'No content available'}
+
+
+ +
+ Created: {new Date(skillDetails.created).toLocaleDateString()} + Modified: {new Date(skillDetails.modified).toLocaleDateString()} +
+
+ ) : ( +
+
Failed to load skill details
+
+ ) + ) : ( +
+
+ +

Select a Skill

+

+ Click on a skill to view its details and content +

+
+
+ )} +
+
+ + {/* Install Template Modal */} + + {showTemplates && ( + setShowTemplates(false)} + > + e.stopPropagation()} + > +
+

Install Skills

+ +
+ + {/* Tab Selector */} +
+ + +
+ + {/* Search and Source Filter */} +
+
+ + setSearchQuery(e.target.value)} + placeholder={templateTab === 'local' ? 'Search templates...' : 'Search community skills...'} + className="input w-full pl-10" + /> +
+ {templateTab === 'community' && ( + <> + + + + )} +
+ + {/* Content based on tab */} +
+ {templateTab === 'local' ? ( + // Local Templates + templatesLoading ? ( +
Loading templates...
+ ) : ( + categories.map((category) => { + const categoryTemplates = templatesByCategory[category] || []; + if (categoryTemplates.length === 0) return null; + + return ( +
+ + {expandedCategories.has(category) && ( +
+ {categoryTemplates.map((template) => { + const isInstalled = projectSkills.some(s => s.name === template.name); + return ( +
+
+
+
{template.name}
+
+ {template.description} +
+
+ {template.tags.map(tag => ( + + {tag} + + ))} +
+
+ +
+
+ ); + })} +
+ )} +
+ ); + }) + ) + ) : ( + // Community Skills + communityLoading ? ( +
+ +
Fetching community skills from GitHub...
+
This may take a moment
+
+ ) : filteredCommunitySkills.length === 0 ? ( +
+ +
No community skills found
+
Try a different search or source
+
+ ) : ( + Object.entries(communityBySource).map(([source, skills]) => { + const sourceInfo = communitySources[source]; + return ( +
+ + {expandedCategories.has(source) && ( +
+ {skills.map((skill) => { + const isInstalled = projectSkills.some(s => s.name === skill.name); + return ( +
+
+
+
+
{skill.name}
+ + + +
+
+ {skill.description || 'No description available'} +
+
+ {skill.repo} +
+
+ +
+
+ ); + })} +
+ )} +
+ ); + }) + ) + )} +
+ + + )} + + + {/* Create Skill Modal */} + + {showCreateModal && ( + setShowCreateModal(false)} + > + e.stopPropagation()} + > +

Create Custom Skill

+ +
+
+ + setNewSkillName(e.target.value)} + placeholder="my-skill" + className="input w-full" + /> +
+ +
+ + setNewSkillDescription(e.target.value)} + placeholder="What this skill does..." + className="input w-full" + /> +
+ +
+ + setNewSkillCategory(e.target.value)} + placeholder="e.g., backend, frontend, testing" + className="input w-full" + /> +
+ +
+ + setNewSkillTags(e.target.value)} + placeholder="ruby, rails, api" + className="input w-full" + /> +
+ +
+ +