mini-openclaw: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

---

Project Overview

Mini-OpenClaw is a file-first AI agent system with a React frontend and FastAPI/LangGraph backend. It combines conversational AI with transparent file-based memory, skills plugins, and RAG knowledge retrieval.

Core Philosophy

• File-first Memory: All persistent state (sessions, memory, skills) is stored as files, not databases
• Skills as Plugins: Custom tools defined in backend/skills/*/SKILL.md files
• Transparent Thinking: Agent tool calls and reasoning are displayed to the user in real-time
• No Cloud Lock-in: Uses local LLM (DeepSeek/Claude/OpenAI) and on-disk storage

---

Development Commands

Environment Setup

# Activate conda environment (required for backend)
conda activate langgraph

# Install frontend dependencies
cd frontend
npm install

Running the Project

Important: On Windows, use the following ports due to Hyper-V port reservation issues (see DEV_NOTES.md):

• Backend: 9000 (not 8000/8002/8888 which are reserved)
• Frontend: 5173

Terminal 1 - Backend (run from project root):

conda activate langgraph
python -m uvicorn backend.app:app --reload --port 9000

Terminal 2 - Frontend (run from frontend directory):

cd frontend
npm run dev

Frontend Commands

npm run dev      # Start dev server
npm run build    # Production build
npm run lint     # ESLint
npm run test     # Run vitest tests
npm run test:watch  # Watch mode for tests

Backend Testing

# Access Swagger UI for API documentation
# http://localhost:9000/docs

---

Architecture

Frontend (React + Vite + shadcn/ui)

frontend/
├── src/
│   ├── pages/Index.tsx          # Main layout (3-panel: Sidebar | Chat | Inspector)
│   ├── components/
│   │   ├── ChatStage.tsx        # Chat interface with streaming + thinking chain
│   │   ├── AppSidebar.tsx      # Sessions list + System prompt view
│   │   └── InspectorPanel.tsx   # File editor for memory/skills
│   ├── lib/store.tsx            # React Context for global state
│   └── api.ts                  # API client (streaming fetch, sessions, files)
└── vite.config.ts               # IMPORTANT: host: "localhost" (not "::") for Windows