b1d80f29ae
* feat(agent): improve interactive CLI with colors, spinner, and status bar - Add colors.ts module with ANSI terminal color utilities - Add spinner animation for tool execution feedback - Add persistent status bar showing session/provider/model - Apply colors to welcome banner, prompts, commands, and suggestions - Support NO_COLOR env for accessibility Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * fix(agent): correct cursor position with ANSI-colored prompts Strip ANSI escape codes when calculating visual length of prompt to ensure cursor is positioned correctly after colored text. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * fix(agent): prevent duplicate input echo in interactive CLI Lazy-initialize readline.Interface only when multiline mode is active. This prevents readline from interfering with autocomplete's raw mode, which was causing user input to be echoed twice. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * refactor(agent): move CLI files to dedicated cli/ directory Reorganize CLI-related files into src/agent/cli/ for better separation: - interactive.ts (was interactive-cli.ts) - non-interactive.ts (was cli.ts) - profile.ts, skills.ts, tools.ts (was *-cli.ts) - autocomplete.ts, colors.ts, output.ts (CLI utilities) Update all imports, package.json scripts, and build configuration. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
117 lines
4.7 KiB
Markdown
117 lines
4.7 KiB
Markdown
# 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). CLI tools are organized in `src/agent/cli/` (interactive, non-interactive, profile, skills, tools).
|
|
|
|
**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.
|
|
|
|
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"`
|