From 456d9c5429118839b9fe71a8a111aaa12ed6ad2f Mon Sep 17 00:00:00 2001 From: Naiyuan Qing <145280634+NevilleQingNY@users.noreply.github.com> Date: Fri, 30 Jan 2026 21:50:12 +0800 Subject: [PATCH] docs: rewrite CLAUDE.md with project architecture and commands Co-Authored-By: Claude Opus 4.5 --- CLAUDE.md | 149 ++++++++++++++++++++++++++++++++++-------------------- 1 file changed, 94 insertions(+), 55 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 633454cb..b571775a 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,63 +1,102 @@ -# Project Instructions for AI Agents +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## Project Overview + +Super Multica is a distributed AI agent framework with a monorepo architecture. It includes an agent engine with multi-provider LLM support, a WebSocket gateway, a console hub for multi-agent coordination, and frontend apps (Next.js web, Electron desktop). + +## Monorepo Structure + +- **`src/`** — Core modules (agent engine, gateway, console, client, shared types) +- **`apps/web`** — Next.js 16 web app (`@multica/web`, port 3001) +- **`apps/desktop`** — Electron + Vite + React desktop app (`@multica/desktop`) +- **`packages/ui`** — Shared UI component library (`@multica/ui`, Shadcn/Tailwind CSS v4) +- **`packages/sdk`** — Gateway client SDK (`@multica/sdk`, Socket.io) +- **`packages/store`** — Zustand state management (`@multica/store`) +- **`skills/`** — Bundled agent skills (commit, code-review, skill-creator) + +## Common Commands + +```bash +# Install dependencies +pnpm install + +# Development (all services concurrently: gateway:3000, console, web:3001) +pnpm dev + +# Individual services +pnpm dev:gateway # WebSocket gateway only +pnpm dev:console # NestJS console with agent +pnpm dev:web # Next.js web app +pnpm dev:desktop # Electron desktop app + +# Agent CLI +pnpm agent:cli # Non-interactive agent +pnpm agent:interactive # Interactive REPL mode + +# Build (turbo-orchestrated) +pnpm build + +# Type checking +pnpm typecheck + +# Testing (vitest, tests live in src/**/*.test.ts) +pnpm test # Single run +pnpm test:watch # Watch mode +pnpm test:coverage # With v8 coverage +``` + +## Architecture + +``` +Frontend (web:3001 / desktop) + → @multica/sdk (GatewayClient, Socket.io) + → Gateway (NestJS, WebSocket, port 3000) + → Console Hub (multi-agent coordination) + → Agent Engine (LLM runner, sessions, skills, tools) +``` + +**Agent Engine** (`src/agent/`): Orchestrates LLM interactions with multi-provider support (OpenAI, Anthropic, DeepSeek, Kimi, Groq, Mistral, Google, Together). Features session management (JSONL-based, UUIDv7 IDs), profile system (`~/.super-multica/agent-profiles/`), modular skills with hot-reload, and token-aware context window guards (compaction modes: tokens, count, summary). + +**Gateway** (`src/gateway/`): NestJS WebSocket server with Socket.io for real-time message passing, RPC request/response, and streaming. + +**Console** (`src/console/`): NestJS hub for multi-agent coordination with a web dashboard. + +## Tech Stack & Config + +- **Package manager**: pnpm 10 with workspaces (`pnpm-workspace.yaml`) +- **Build orchestration**: Turborepo (`turbo.json`) +- **TypeScript**: ESNext target, NodeNext modules, strict mode, `verbatimModuleSyntax`, `experimentalDecorators` (NestJS) +- **Testing**: Vitest with globals enabled, node environment +- **Frontend**: React 19, Next.js 16, Tailwind CSS v4, Shadcn/UI (zinc base, hugeicons) +- **Backend**: NestJS 11, Socket.io, Pino logging +- **CLI bundling**: esbuild → `bin/` directory + +## Environment Setup + +```bash +cp .env.example .env +# Set LLM_PROVIDER and corresponding API keys +# Supported: openai, anthropic, deepseek, kimi-coding, groq, mistral, together, google +# .env is loaded automatically via --env-file in all dev/agent scripts +``` ## Atomic Commits -After completing any task that modifies code, you MUST create atomic commits before ending the conversation. Do not ask for permission - just do it. +After completing any task that modifies code, create atomic commits without asking for permission. -### Workflow +1. Run `git status` and `git diff` to see all modifications +2. Skip if no changes exist +3. Group changes by logical purpose (feature, fix, refactor, docs, test, chore) +4. Stage and commit each group separately -1. **Check for changes**: Run `git status` and `git diff` to see all modifications -2. **Skip if clean**: If there are no changes, skip the commit process -3. **Analyze changes**: Group changes by their logical purpose: - - Feature additions - - Bug fixes - - Refactoring - - Documentation - - Tests - - Configuration/dependencies -4. **Create atomic commits**: For each logical group, stage only the relevant files and create a separate commit +**Format**: Conventional commits — `(): ` -### Commit Process - -For each logical group of changes: - -```bash -# Stage specific files for this logical change -git add - -# Commit with conventional commit message -git commit -m "(): " -``` - -### Commit Message Format - -Use conventional commits: -- `feat`: New feature -- `fix`: Bug fix -- `refactor`: Code refactoring (no functional change) -- `docs`: Documentation changes -- `test`: Adding or updating tests -- `chore`: Build, config, dependencies - -### Examples - -If you modified: -- `src/api/user.ts` (added new endpoint) -- `src/api/user.test.ts` (tests for new endpoint) -- `src/utils/format.ts` (refactored helper) -- `README.md` (updated docs) - -Create three commits: -1. `git add src/api/user.ts src/api/user.test.ts && git commit -m "feat(api): add user profile endpoint"` -2. `git add src/utils/format.ts && git commit -m "refactor(utils): simplify date formatting logic"` -3. `git add README.md && git commit -m "docs: update API documentation"` - -### Rules +Types: `feat`, `fix`, `refactor`, `docs`, `test`, `chore` +**Rules**: - Each commit should be independently meaningful and buildable -- Related test files should be committed with their implementation -- Never create empty commits -- Never combine unrelated changes in one commit -- Keep commit messages concise but descriptive -- If all changes are related to one logical unit, a single commit is fine -- `git commit --amend` can be used for immediate small fixes to the last commit, but not for unrelated changes +- Related test files go with their implementation +- Never create empty commits or combine unrelated changes +- `git commit --amend` only for immediate small fixes to the last commit