multica/README.md

Super Multica

Super Multica is a distributed AI agent framework and product monorepo. It provides a local-first agent runtime plus CLI, gateway, web, and mobile integration surfaces.

What this project does:

• runs AI agent sessions with tools, skills, and persistent session state
• supports scheduled/automated execution workflows
• supports both standalone local usage and remote-access client workflows

This repository keeps docs focused on:

1. Development workflow
2. Testing workflow
3. Operational process

Architecture details are still source-of-truth in code, but docs keep minimal project context for onboarding.

Quick Start (Workflow)

pnpm install
pnpm multica credentials init
pnpm multica

Run local desktop workflow:

pnpm dev

Local Full-Stack Development (pnpm dev:local)

Use this when you need Gateway + Web + Desktop together for end-to-end dev.

Setup:

1. Copy .env.example to .env in repo root
2. Set TELEGRAM_BOT_TOKEN in .env (from @BotFather)
3. Run:

pnpm dev:local

What starts:

Service	Address	Notes
Gateway	http://localhost:4000	Telegram long-polling mode
Web	http://localhost:3000	OAuth login flow
Desktop	—	Connects to local Gateway + Web

Data isolation:

• runtime data: ~/.super-multica-dev
• workspace data: ~/Documents/Multica-dev

Related:

pnpm dev:local:archive

Workflow Commands

# 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
pnpm dev:local:archive

# Build / quality
pnpm build
pnpm typecheck
pnpm test

Testing Workflow

# Unit/integration
pnpm test
pnpm test:watch
pnpm test:coverage

# Type safety gate
pnpm typecheck

# Agent E2E
pnpm multica run --run-log "your test prompt"

E2E process docs:

• docs/e2e-testing-guide.md
• docs/e2e-finance-benchmark.md

Runtime Paths

By default, runtime data is stored under:

• ~/.super-multica

You can isolate environments with:

• SMC_DATA_DIR=~/.super-multica-dev (or other path)

Process Docs

• CLAUDE.md
• docs/development.md
• docs/cli.md
• docs/credentials.md
• docs/skills-and-tools.md
• docs/package-management.md
• docs/e2e-testing-guide.md
• docs/e2e-finance-benchmark.md