multica/CLAUDE.md

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

# Install dependencies
pnpm install

# Multica CLI (unified entry point)
multica                   # Interactive mode (default)
multica run "<prompt>"    # Run a single prompt
multica chat              # Interactive REPL mode
multica session list      # List sessions
multica profile list      # List profiles
multica skills list       # List skills
multica tools list        # List tools
multica credentials init  # Initialize credentials
multica dev               # Start all dev services
multica help              # Show help

# Development servers
multica dev               # All services (gateway:3000, console:4000, web:3001)
multica dev gateway       # WebSocket gateway only
multica dev console       # NestJS console with agent
multica dev web           # Next.js web app
multica dev desktop       # Electron desktop app

# 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). Unified CLI in src/agent/cli/index.ts with subcommands in src/agent/cli/commands/.

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

Code Style

• Comments: Always write code comments in English, regardless of the conversation language.

Credentials Setup

Use JSON5 credential files instead of .env:

multica credentials init

This creates:

• ~/.super-multica/credentials.json5 (LLM providers + built-in tools)
• ~/.super-multica/skills.env.json5 (skills / plugins / integrations)

Atomic Commits

After completing any task that modifies code, you MUST create atomic commits before ending the conversation.

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

Format: Conventional commits — <type>(<scope>): <description>

Types: feat, fix, refactor, docs, test, chore

Rules:

• Each commit should be independently meaningful and buildable
• Related test files go with their implementation
• Never create empty commits or combine unrelated changes
• If all changes are related to one logical unit, a single commit is fine
• Keep commit messages concise but descriptive
• git commit --amend only for immediate small fixes to the last commit

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"