Claude OS Documentation

Claude OS functions as an ecosystem that augments Claude's intelligence by providing project-specific context through several integrated layers:

Core Components

• Real-Time Learning System (Redis): Provides <1ms latency for immediate context updates.
• Memory System (MCP): Provides instant access to persistent project memories.
• Code Structure (Tree-sitter AST): A new feature that uses AST mapping to index symbols (e.g., 38,406 symbols in seconds) for deep structural understanding.
• Semantic Knowledge Base (SQLite): The central repository containing:
  • Structural index of code symbols.
  • Semantic chunks (optimized for reduced noise).
  • Vector embeddings for semantic search.
  • Dependency graphs and PageRank scores.
  • Team patterns, conventions, and architecture documentation.

Integration Layer

• MCP Server (http://localhost:8051): Exposes 5 Model Context Protocol (MCP) servers per project:
  • project_memories: Persistent memories.
  • project_profile: Project standards and conventions.
  • project_index: Semantic search capabilities.
  • knowledge_docs: Project documentation.
  • code_structure: The AST-based map of the codebase.
• Claude Code Interface: The final layer where Claude interacts with the indexed data, enabling significantly faster indexing compared to traditional methods.

Agent-OS organizes project knowledge and feature development into a specific directory hierarchy. This structure ensures that product vision, feature specifications, and coding standards are maintained systematically:

• agent-os/config.yml: Agent-OS configuration.
• agent-os/product/: Contains high-level product documentation:
  • mission.md: Product mission and goals.
  • roadmap.md: Feature roadmap.
  • tech-stack.md: Technology stack definitions.
• agent-os/specs/: Contains feature-specific directories organized by date and name (e.g., YYYY-MM-DD-feature-name/). Each spec directory includes:
  • planning/: Contains requirements.md and a visuals/ folder for assets.
  • spec.md: The detailed technical specification.
  • tasks.md: The actionable task breakdown.
• agent-os/standards/: Contains coding standards used as agent skills.

agent-os/
├── config.yml          # Agent-OS configuration
├── product/            # Product documentation
│   ├── mission.md      # Product mission and goals
│   ├── roadmap.md      # Feature roadmap
│   └── tech-stack.md  # Technology stack
├── specs/              # Feature specifications
│   └── YYYY-MM-DD-feature-name/
│       ├── planning/
│       │   ├── requirements.md
│       │   └── visuals/
│       ├── spec.md
│       └── tasks.md
└── standards/          # Coding standards (as skills)

Use the Context Pattern to provide global data (like authentication) to a component tree.

1. Create a context using createContext.
2. Wrap the application (or a subtree) in a Provider component that manages the state.
3. Export a custom hook (e.g., useAuth) that calls useContext and throws an error if used outside the provider. This ensures type safety and prevents runtime errors when accessing undefined contexts.

// src/context/AuthContext.tsx
import { createContext, useContext, useState, ReactNode } from 'react';

interface AuthContextType {
  user: User | null;
  login: (credentials: Credentials) => Promise<void>;
  logout: () => void;
  isAuthenticated: boolean;
}

const AuthContext = createContext<AuthContextType | undefined>(undefined);

export function AuthProvider({ children }: { children: ReactNode }) {
  const [user, setUser] = useState<User | null>(null);

  const login = async (credentials: Credentials) => {
    const user = await authApi.login(credentials);
    setUser(user);
  };

  const logout = () => {
    setUser(null);
    authApi.logout();
  };

  return (
    <AuthContext.Provider value={{
      user,
      login,
      logout,
      isAuthenticated: !!user
    }}>
      {children}
    </AuthContext.Provider>
  );
}

export function useAuth() {
  const context = useContext(AuthContext);
  if (!context) {
    throw new Error('useAuth must be used within AuthProvider');
  }
  return context;
}

Agent-OS organizes project intelligence into a specific directory hierarchy. When using Agent-OS, your project should follow this structure:

• agent-os/config.yml: Agent-OS configuration.
• agent-os/product/: High-level product documentation including mission.md, roadmap.md, and tech-stack.md.
• agent-os/specs/: Feature-specific specifications. Each feature resides in agent-os/specs/YYYY-MM-DD-feature-name/ and contains planning/, spec.md, and tasks.md.
• agent-os/standards/: Coding standards categorized by backend/, frontend/, global/, and testing/.

agent-os/
├── config.yml          # Agent-OS configuration
├── product/            # Product documentation
│   ├── mission.md      # Product mission and goals
│   ├── roadmap.md      # Feature roadmap
│   └── tech-stack.md   # Technology stack documentation
├── specs/              # Feature specifications
│   └── YYYY-MM-DD-feature-name/
│       ├── planning/
│       ├── spec.md
│       └── tasks.md
└── standards/          # Coding standards
    ├── backend/
    ├── frontend/
    ├── global/
    └── testing/

Claude OS consists of two distinct services running on different ports. It is critical to use the correct port depending on whether you are interacting with the system via a web browser or via Claude Code (MCP protocol).

1. MCP Server (Port 8051)

• Purpose: API server for Claude Code integration. It handles AI memory, knowledge bases, and serves API endpoints.
• Technology: FastAPI (Python).
• Access: Used by Claude Code via the MCP protocol.
• ⚠️ Warning: Do NOT open http://localhost:8051 in a web browser. Browser GET requests will return a {"detail": "Method Not Allowed"} error because the server expects MCP protocol POST requests.

2. Web UI (Port 5173)

• Purpose: Visual interface for human users to browse knowledge bases, upload documents, search, and manage projects.
• Technology: React + Vite.
• Access: Open http://localhost:5173 in your web browser.

Summary Table