diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 00000000..e39cc77b --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,92 @@ +# CLAUDE.md + +This file gives coding agents high-signal guidance for this repository. + +## 1. Project Snapshot + +Super Multica is a pnpm monorepo for a distributed AI agent system: + +- Agent engine + Hub: `packages/core` +- Desktop app (primary local runtime): `apps/desktop` +- CLI: `apps/cli` +- Remote access gateway: `apps/gateway` +- Web client: `apps/web` + +## 2. Monorepo Map + +```text +apps/ + cli desktop gateway server web mobile + +packages/ + core sdk ui store hooks types utils + +skills/ + skill assets and runtime helper scripts +``` + +## 3. Core Commands + +```bash +pnpm install +pnpm multica +pnpm multica run "" +pnpm dev +pnpm dev:gateway +pnpm dev:web +pnpm dev:local +pnpm build +pnpm typecheck +pnpm test +``` + +## 4. Architecture Notes + +- Desktop app embeds Hub + Agent runtime. +- Gateway is optional for local desktop usage, required for remote/web-style access. +- Web app depends on gateway/API setup. +- Sessions are directory-based: `~/.super-multica/sessions//`. + +## 5. Data and Credentials + +- Default data dir: `~/.super-multica` (override with `SMC_DATA_DIR`) +- Credentials: `~/.super-multica/credentials.json5` (override with `SMC_CREDENTIALS_PATH`) +- Initialize credentials via `pnpm multica credentials init` + +## 6. Coding Rules + +- TypeScript strict mode is enabled; keep types explicit. +- Keep comments in code **English only**. +- Prefer existing patterns/components over introducing parallel abstractions. +- Avoid broad refactors unless required by the task. +- Keep docs concise and aligned with current code behavior. + +## 7. Testing Rules + +- Test runner: Vitest. +- Mock policy: mock external/third-party dependencies only. +- Do not mock internal modules when real integration can be tested. +- Prefer temp directories and real file I/O for storage-related tests. + +## 8. Commit Rules + +- Use atomic commits grouped by logical intent. +- Conventional format: + - `feat(scope): ...` + - `fix(scope): ...` + - `refactor(scope): ...` + - `docs: ...` + - `test(scope): ...` + - `chore(scope): ...` + +## 9. Minimum Pre-Push Checks + +```bash +pnpm typecheck +pnpm test +``` + +## 10. E2E Docs + +- `docs/e2e-testing-guide.md` +- `docs/e2e-finance-benchmark.md` diff --git a/README.md b/README.md new file mode 100644 index 00000000..bb89feda --- /dev/null +++ b/README.md @@ -0,0 +1,88 @@ +# Super Multica + +Super Multica is a monorepo for a distributed AI agent framework. +It includes a local-first Desktop app, CLI, Gateway/Web access, and reusable core packages. + +## Current Documentation Strategy + +The docs set is intentionally **small and high-signal**. +For current status and priorities, see: + +- `docs/README.md` + +## Monorepo Layout + +```text +apps/ + cli/ @multica/cli Command-line interface + desktop/ @multica/desktop Electron desktop app (primary local runtime) + gateway/ @multica/gateway NestJS WebSocket gateway + server/ @multica/server NestJS REST server + web/ @multica/web Next.js web app + mobile/ @multica/mobile React Native app + +packages/ + core/ @multica/core Agent, Hub, tools, channels, cron, heartbeat + sdk/ @multica/sdk Gateway client SDK + ui/ @multica/ui Shared React UI components + store/ @multica/store Zustand stores + hooks/ @multica/hooks Shared hooks + types/ @multica/types Shared types + utils/ @multica/utils Shared utilities +``` + +## Quick Start + +```bash +pnpm install +pnpm multica credentials init +pnpm multica +``` + +Run desktop app in dev mode: + +```bash +pnpm dev +``` + +## Common Commands + +```bash +# CLI +pnpm multica +pnpm multica run "Hello" +pnpm multica chat +pnpm multica help + +# Development +pnpm dev +pnpm dev:desktop +pnpm dev:gateway +pnpm dev:web +pnpm dev:local + +# Build / quality +pnpm build +pnpm typecheck +pnpm test +``` + +## Runtime Data + +By default, runtime data is stored under: + +- `~/.super-multica` + +You can isolate environments with: + +- `SMC_DATA_DIR=~/.super-multica-dev` (or other path) + +## Core Docs + +- `CLAUDE.md` (AI coding guidance in this repo) +- `docs/development.md` +- `docs/cli.md` +- `docs/credentials.md` +- `docs/skills-and-tools.md` +- `docs/e2e-testing-guide.md` +- `docs/e2e-finance-benchmark.md` diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 00000000..6f2f74f7 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,26 @@ +# Documentation Index (Priority-Based) + +This repo keeps documentation intentionally small to reduce stale AI context. + +## P0 (Keep Fresh) + +1. `README.md` +2. `CLAUDE.md` +3. `docs/development.md` +4. `docs/cli.md` +5. `docs/credentials.md` + +## P1 (Operational) + +1. `docs/skills-and-tools.md` +2. `docs/package-management.md` +3. `docs/e2e-testing-guide.md` + +## P2 (Benchmarks / Specialized) + +1. `docs/e2e-finance-benchmark.md` + +## Regeneration Rule + +When code behavior changes, update only impacted P0/P1 docs first. +If unsure, prefer deleting stale sections over keeping speculative content. diff --git a/docs/cli.md b/docs/cli.md new file mode 100644 index 00000000..df3c6317 --- /dev/null +++ b/docs/cli.md @@ -0,0 +1,129 @@ +# CLI Guide (`multica`) + +## Entry + +```bash +pnpm multica +``` + +Equivalent command names: + +- `multica` +- `mu` + +## Core Commands + +```bash +multica # interactive chat (default) +multica run "" # one-shot run +multica chat # explicit interactive mode +multica session # session management +multica profile # profile management +multica skills # skill management +multica tools # tool policy inspection +multica credentials # credentials management +multica cron # scheduled tasks +multica dev [service] # start dev services +multica help +``` + +## Run Mode + +```bash +multica run [options] +echo "prompt" | multica run +``` + +Common options: + +- `--profile ` +- `--provider ` +- `--model ` +- `--session ` +- `--cwd ` +- `--run-log` +- `--tools-allow a,b,c` +- `--tools-deny a,b,c` +- `--context-window ` + +## Chat Mode + +```bash +multica chat [options] +multica [options] +``` + +In-chat commands: + +- `/help` +- `/exit` +- `/clear` +- `/session` +- `/new` +- `/multiline` +- `/provider` +- `/model` + +## Sessions + +```bash +multica session list +multica session show +multica session delete +``` + +Session data root: + +- `~/.super-multica/sessions/` +- or `SMC_DATA_DIR/sessions/` + +## Profiles + +```bash +multica profile list +multica profile new +multica profile setup +multica profile show +multica profile edit +multica profile delete +``` + +## Skills + +```bash +multica skills list +multica skills status [id] +multica skills install +multica skills add +multica skills remove +``` + +## Tools + +```bash +multica tools list +multica tools list --allow group:fs,web_fetch +multica tools list --deny exec +multica tools groups +``` + +## Credentials + +```bash +multica credentials init +multica credentials show +multica credentials edit +``` + +## Cron + +```bash +multica cron status +multica cron list +multica cron add -n "name" --every "30m" --message "..." +multica cron run +multica cron enable +multica cron disable +multica cron remove +multica cron logs +``` diff --git a/docs/credentials.md b/docs/credentials.md new file mode 100644 index 00000000..8ac73f57 --- /dev/null +++ b/docs/credentials.md @@ -0,0 +1,76 @@ +# Credentials Guide + +## Initialize + +```bash +pnpm multica credentials init +``` + +This creates: + +- `~/.super-multica/credentials.json5` + +## Path Resolution + +Credential file lookup order: + +1. `SMC_CREDENTIALS_PATH` (explicit override) +2. `SMC_DATA_DIR/credentials.json5` (or default data dir) +3. `~/.super-multica/credentials.json5` fallback + +## Minimal Template + +```json5 +{ + version: 1, + llm: { + provider: "kimi-coding", + providers: { + "kimi-coding": { + apiKey: "your-key", + }, + }, + }, + tools: { + // tool-specific keys + }, +} +``` + +## Multi-Key Rotation (Per Provider) + +You can define multiple keys under one provider namespace: + +```json5 +{ + llm: { + providers: { + "anthropic": { apiKey: "primary" }, + "anthropic:backup": { apiKey: "backup" }, + }, + order: { + anthropic: ["anthropic", "anthropic:backup"], + }, + }, +} +``` + +## OAuth Providers + +- `claude-code`: run `claude login` +- `openai-codex`: run `codex login` + +API-key providers are configured directly in `credentials.json5`. + +## Tool Credentials + +Tool credentials are read from: + +- `credentials.json5` under `tools` +- skill-level `.env` files under skill directories + +## Security + +- Keep credentials file mode private (`600` on Unix-like systems). +- Do not commit keys into the repository. +- Prefer isolated data dirs (`SMC_DATA_DIR`) for test/dev environments. diff --git a/docs/development.md b/docs/development.md new file mode 100644 index 00000000..c2ce3837 --- /dev/null +++ b/docs/development.md @@ -0,0 +1,83 @@ +# Development Guide + +## Prerequisites + +- Node.js 20+ +- pnpm 10+ +- macOS/Linux/Windows + +## Install + +```bash +pnpm install +``` + +`.npmrc` must keep: + +```ini +shamefully-hoist=true +``` + +## Main Dev Entry Points + +```bash +# Recommended local desktop workflow +pnpm dev + +# Service-specific +pnpm dev:desktop +pnpm dev:gateway +pnpm dev:web + +# Full local stack with isolated dev data +pnpm dev:local +``` + +## What Each Command Does + +- `pnpm dev`: builds shared packages, then runs `types + utils + core + desktop` watch flow. +- `pnpm dev:desktop`: Electron desktop only. +- `pnpm dev:gateway`: NestJS WebSocket gateway (`PORT`, default `3000`). +- `pnpm dev:web`: Next.js web app (`3000` by script). +- `pnpm dev:local`: gateway + web + desktop with dev-safe env defaults. + +## Important Environment Variables + +- `SMC_DATA_DIR`: override runtime data root (default `~/.super-multica`) +- `GATEWAY_URL`: gateway endpoint for desktop/CLI hub connection +- `MULTICA_API_URL`: required by web/data tools +- `PORT`: gateway/server port +- `MULTICA_WORKSPACE_DIR`: override workspace root +- `MULTICA_RUN_LOG=1`: enable structured run-log output + +## Local Full-Stack Notes + +`pnpm dev:local` expects root `.env` with Telegram credentials: + +```bash +cp .env.example .env +``` + +At minimum set: + +- `TELEGRAM_BOT_TOKEN` + +## Build / Quality + +```bash +pnpm build +pnpm typecheck +pnpm test +pnpm test:coverage +``` + +## Useful Reset Commands + +```bash +# Reset default + dev data dirs used by desktop scripts +pnpm dev:desktop:reset + +# Reset and relaunch desktop onboarding flow +pnpm dev:desktop:fresh +pnpm dev:desktop:onboarding +``` diff --git a/docs/package-management.md b/docs/package-management.md new file mode 100644 index 00000000..b8aa23a3 --- /dev/null +++ b/docs/package-management.md @@ -0,0 +1,48 @@ +# Package Management + +## Workspace + +- Package manager: `pnpm` (workspace mode) +- Build orchestrator: `turbo` + +## Required `.npmrc` + +Keep this in repo root: + +```ini +shamefully-hoist=true +``` + +This is required for Electron packaging compatibility in this monorepo. + +## Install + +```bash +pnpm install +``` + +## Clean Reinstall (When Needed) + +Use this when lockfile/hoist state is corrupted or after major package-manager config changes: + +```bash +rm -rf node_modules apps/*/node_modules packages/*/node_modules +rm -f pnpm-lock.yaml +pnpm install +``` + +## Build / Check + +```bash +pnpm build +pnpm typecheck +pnpm test +``` + +## Targeted Commands + +```bash +pnpm --filter @multica/desktop build +pnpm --filter @multica/core build +pnpm --filter @multica/web dev +``` diff --git a/docs/skills-and-tools.md b/docs/skills-and-tools.md new file mode 100644 index 00000000..a332b3dd --- /dev/null +++ b/docs/skills-and-tools.md @@ -0,0 +1,86 @@ +# Skills and Tools + +## Skills Loading Model + +Skills are loaded from two sources with precedence: + +1. Managed skills: `~/.super-multica/skills/` +2. Profile skills: `~/.super-multica/agent-profiles//skills/` + +Profile skills override managed skills when IDs conflict. + +## Skill File Contract + +A valid skill directory must include: + +- `SKILL.md` + +Optional runtime files: + +- `.env` +- helper scripts/assets + +## Current Repo Note + +This repository intentionally keeps docs and bundled skill metadata minimal. +If a directory under `skills/` does not contain `SKILL.md`, it will not be loaded as a skill. + +## Skills CLI + +```bash +multica skills list +multica skills status [id] +multica skills install +multica skills add +multica skills remove +``` + +## Tool System + +`@multica/core` composes: + +- base coding tools (`read/write/edit/...`) +- extended tools (`exec`, `process`, `glob`, `web_fetch`, `web_search`, `data`, `cron`, `delegate`) +- conditional tools (`memory_search`, `send_file`) + +Tool errors are wrapped into structured tool results instead of crashing runs. + +## Tool Groups + +Supported group aliases: + +- `group:fs` -> `read, write, edit, glob` +- `group:runtime` -> `exec, process` +- `group:web` -> `web_search, web_fetch` +- `group:memory` -> `memory_search` +- `group:subagent` -> `delegate` +- `group:cron` -> `cron` +- `group:data` -> `data` +- `group:core` -> core local/web/data set + +## Tool Policy Example + +```json5 +{ + tools: { + allow: ["group:fs", "web_search", "web_fetch"], + deny: ["exec"], + byProvider: { + "openai": { + deny: ["data"], + }, + }, + }, +} +``` + +`deny` always has priority over `allow`. + +## Inspect Effective Tools + +```bash +multica tools list +multica tools list --allow group:fs,web_fetch +multica tools list --deny exec +multica tools groups +```