167 lines
4.4 KiB
Markdown
167 lines
4.4 KiB
Markdown
# Super Multica
|
|
|
|
A multi-component architecture for distributed agent systems.
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
src/
|
|
├── agent/ # Core agent module
|
|
│ ├── context-window/ # Token-aware context management
|
|
│ ├── profile/ # Agent profile management
|
|
│ ├── session/ # Session persistence with compaction
|
|
│ ├── skills/ # Modular skill system
|
|
│ └── tools/ # Agent tools
|
|
│ └── web/ # Web fetch and search tools
|
|
├── gateway/ # WebSocket gateway for remote access
|
|
├── hub/ # Agent coordination hub
|
|
└── shared/ # Shared types
|
|
|
|
apps/
|
|
├── desktop/ # Electron desktop app (recommended)
|
|
└── web/ # Next.js web application
|
|
|
|
packages/
|
|
├── sdk/ # Gateway client SDK
|
|
├── store/ # Zustand state management
|
|
└── ui/ # Shared UI components
|
|
|
|
skills/ # Bundled skills (commit, code-review)
|
|
```
|
|
|
|
## Getting Started
|
|
|
|
```bash
|
|
pnpm install
|
|
```
|
|
|
|
### Development
|
|
|
|
```bash
|
|
# Desktop app (recommended for local development)
|
|
pnpm dev
|
|
|
|
# Gateway + Web app (for remote/mobile clients)
|
|
pnpm dev:gateway # Start Gateway on :3000
|
|
pnpm dev:web # Start Web app on :3001
|
|
pnpm dev:all # Start both Gateway and Web app
|
|
```
|
|
|
|
The Desktop app runs a standalone Hub with embedded Agent Engine - no Gateway required for local use.
|
|
|
|
### Credentials
|
|
|
|
```bash
|
|
multica credentials init
|
|
```
|
|
|
|
Creates:
|
|
- `~/.super-multica/credentials.json5` — LLM providers + tools
|
|
- `~/.super-multica/skills.env.json5` — skill/plugin API keys
|
|
|
|
Example `credentials.json5`:
|
|
|
|
```json5
|
|
{
|
|
version: 1,
|
|
llm: {
|
|
provider: "openai",
|
|
providers: {
|
|
openai: { apiKey: "sk-xxx", model: "gpt-4o" }
|
|
}
|
|
},
|
|
tools: {
|
|
brave: { apiKey: "brv-..." }
|
|
}
|
|
}
|
|
```
|
|
|
|
### LLM Providers
|
|
|
|
**OAuth Providers** (external CLI login):
|
|
- `claude-code` — requires `claude login`
|
|
- `openai-codex` — requires `codex login`
|
|
|
|
**API Key Providers** (configure in `credentials.json5`):
|
|
- `anthropic`, `openai`, `kimi-coding`, `google`, `groq`, `mistral`, `xai`, `openrouter`
|
|
|
|
Check status: `/provider` in interactive mode
|
|
|
|
## CLI
|
|
|
|
```bash
|
|
multica # Interactive mode
|
|
multica run "prompt" # Single prompt
|
|
multica chat --profile my-agent # Use profile
|
|
multica --session abc123 # Continue session
|
|
multica session list # List sessions
|
|
multica profile list # List profiles
|
|
multica skills list # List skills
|
|
multica help # Show help
|
|
```
|
|
|
|
Short alias: `mu`
|
|
|
|
## Sessions
|
|
|
|
Sessions persist to `~/.super-multica/sessions/<id>/` with JSONL message history and JSON metadata. Context windows are automatically managed with token-aware compaction.
|
|
|
|
## Profiles
|
|
|
|
Profiles define agent identity, personality, and memory in `~/.super-multica/agent-profiles/<id>/`.
|
|
|
|
```bash
|
|
multica profile new my-agent # Create profile
|
|
multica profile list # List all
|
|
multica profile edit my-agent # Open in file manager
|
|
```
|
|
|
|
Profile files: `soul.md`, `user.md`, `workspace.md`, `memory.md`, `memory/*.md`
|
|
|
|
## Skills
|
|
|
|
Skills extend agent functionality via `SKILL.md` files. See [Skills Documentation](./src/agent/skills/README.md).
|
|
|
|
```bash
|
|
multica skills list # List skills
|
|
multica skills add owner/repo # Install from GitHub
|
|
multica skills status # Check status
|
|
```
|
|
|
|
Built-in: `commit`, `code-review`, `skill-creator`
|
|
|
|
## Tools
|
|
|
|
Available tools: `read`, `write`, `edit`, `glob`, `exec`, `process`, `web_fetch`, `web_search`, `memory_search`, `sessions_spawn`
|
|
|
|
See [Tools Documentation](./src/agent/tools/README.md) for details.
|
|
|
|
## Architecture
|
|
|
|
```
|
|
Desktop App (standalone, recommended)
|
|
└─ Hub (embedded)
|
|
└─ Agent Engine
|
|
|
|
Web/Mobile Clients
|
|
→ Gateway (WebSocket, :3000)
|
|
→ Hub
|
|
→ Agent Engine
|
|
```
|
|
|
|
- **Desktop App**: Electron app with embedded Hub, no Gateway needed
|
|
- **Gateway**: WebSocket server for remote clients
|
|
- **Hub**: Agent lifecycle and event distribution
|
|
|
|
## Scripts
|
|
|
|
```bash
|
|
pnpm dev # Desktop app (recommended)
|
|
pnpm dev:gateway # Gateway only
|
|
pnpm dev:web # Web app only
|
|
pnpm dev:all # Gateway + Web
|
|
|
|
pnpm build # Production build
|
|
pnpm typecheck # Type check
|
|
pnpm test # Run tests
|
|
```
|