multica Documentation

File: README.md Copy Chapter

What is Multica? Copy Chapter

You already run Claude Code, Codex, and three other agents. Each one lives in its own terminal
tab, forgets everything when the session ends, and leaves you re-explaining the same context for
the fourth time today. The more agents you add, the more of your day goes to babysitting them.

Multica puts those agents and your teammates in one workspace. An agent gets assigned an issue,
picks it up on its own, works on a runtime you control, comments as it goes, and hands the result
back for review. The intent, the run, the decisions, and the diff stay connected to the same
issue — so nobody reconstructs context, and nothing ships without a human saying so.

Build the team. Copy Chapter

Claude Code, Codex, Cursor, Kimi — you don't pick one. You hire them all.

• 23 agent CLIs → Claude Code, Codex, Cursor, Copilot, Kimi, OpenCode, and more.
• Agents as teammates → Give each one a name, a provider, and a runtime — they show up on the board like anyone else.
• Squads → Put agents and people on one team; the leader routes the work.
• Skills → Turn a solved problem into a playbook every agent reuses.
• Your own runtime → Their desk is your machine — a daemon on your laptop or cloud box. Code never leaves it.

Hand off the work. Copy Chapter

It starts as three rough sentences in an issue. It ends as a pull request.

• Assign an issue → Pick an agent as assignee the way you'd pick a colleague — it takes the work from there.
• Autopilots → Run standups, audits, and reports on a cron — nobody to remind.
• Chat → Ask your workspace a question, or start work without filing anything.
• Projects → Group work and attach the repos and docs agents need as context.

Stay in the loop. Copy Chapter

Which agent touched this? What did it run? What did it cost? Open the run.

• Execution log → Replay every tool call, command, and error, timestamped.
• Token usage → See what each run cost, per agent and per issue.
• Review gates → Work lands in review, not in main. You decide what ships.
• Inbox → Get pinged when an agent needs a call, not for every step.
• Retries and timeouts → Failed runs retry on their own, or stop and tell you why.

Make it yours. Copy Chapter

Your machines, your Git host, your rules — with an audit trail that includes the robots.

• Self-host everything → Docker Compose or Helm, on your own infrastructure.
• Any Git host → GitHub, GitLab, Gitea, or Forgejo — self-hosted included.
• Workspaces → Separate agents, issues, and settings per team.
• Roles and access scopes → owner, admin, and member — and exactly which agents each member can run.
• Security model → What an agent can reach, and what it can't.
• Slack, Lark, DingTalk, WeCom, and Telegram → Trigger and follow agent work where your team already talks. DingTalk, WeCom, and Telegram are community-maintained.
• Web, desktop, and mobile → The same workspace on macOS, Windows, Linux, and iPhone — iOS builds from source today, not yet on the App Store.
• CLI and API → Every surface is scriptable. Agents drive Multica through the same CLI you do.

Get started Copy Chapter

No terminal required: sign up at multica.ai, or download
Multica Desktop for macOS, Windows, and Linux — it connects
the computer it runs on as a runtime automatically.

The one prerequisite: the machine that will run agents needs at least one
supported agent CLI installed and signed in — Claude Code, Codex, Cursor, and
friends. Multica drives them; it doesn't ship them.

Self-hosting the whole thing

curl -fsSL https://raw.githubusercontent.com/multica-ai/multica/main/scripts/install.sh | bash -s -- --with-server
multica setup self-host

On Windows, set $env:MULTICA_MODE="with-server", then run the PowerShell installer:
irm https://raw.githubusercontent.com/multica-ai/multica/main/scripts/install.ps1 | iex.

This pulls the official images from GHCR and requires Docker. See the
Self-Hosting Guide; if the selected GHCR tag has not been published yet,
fall back to make selfhost-build from a checkout.

Your first agent in five minutes Copy Chapter

1. Sign in. multica.ai in the browser, or open
Multica Desktop.

2. Connect a computer. A runtime is any machine agents can work on — your laptop, or a
cloud box. Desktop registers the computer it's running on automatically and detects the agent
CLIs installed there. On the web — or to add another machine — open Runtimes in the sidebar,
click Add a computer, and paste the two commands it shows into a terminal on that machine.

3. Create an agent. Open Agents in the sidebar and click New agent. Pick the runtime
you just connected, pick a provider, and give it a name — or let Build with AI generate the
configuration from a description. That name is how it shows up on the board and in comments.

4. Assign it something. File an issue and set the agent as assignee. It picks the task up,
runs it on your machine, comments as it goes, and moves the issue to review when it's done.

Full walkthrough: Quickstart · Tutorial

Runtimes Copy Chapter

Multica does not ship a model. It drives the agent CLIs you already have installed and
authenticated, so switching providers is a dropdown, not a migration.

Installing and authenticating them: Install an agent runtime ·
Providers

Documentation Copy Chapter

Architecture Copy Chapter

Web  ·  Desktop (macOS/Windows/Linux)  ·  iOS
                          │
                          ▼
   ┌──────────────┐   ┌──────────────┐   ┌──────────────────┐
   │   Next.js    │──>│  Go backend  │──>│   PostgreSQL     │
   │   frontend   │<──│  (Chi + WS)  │<──│   (pgvector)     │
   └──────────────┘   └──────┬───────┘   └──────────────────┘
                             │  tasks over WebSocket
                      ┌──────┴───────┐
                      │ Agent daemon │  runs on your machine, next to your code
                      └──────┬───────┘
                             │  spawns
                      ┌──────┴───────────────────────────────┐
                      │  Claude Code · Codex · Cursor · …    │
                      │  (any of the 23 runtimes above)      │
                      └──────────────────────────────────────┘

Development Copy Chapter

Contributors: start with the Contributing Guide.

Prerequisites: Node.js 22, pnpm 10.28.2, Go 1.26.6, Docker

make dev

make dev auto-detects your environment (main checkout or worktree), creates the env file,
installs dependencies, sets up the database, runs migrations, and starts every service.

See CONTRIBUTING.md for the full workflow, worktree support, testing, and
troubleshooting. The iOS client lives in apps/mobile/ — its
README covers building it onto your own iPhone.

We release most weekdays, so main moves quickly — pull often.

Why "Multica"? Copy Chapter

Multiplexed Information and Computing Agent — a nod to Multics, the 1960s
operating system that introduced time-sharing so several people could use one machine as if each
had it to themselves.

Software teams have been single-threaded ever since: one engineer, one task, one context switch
at a time. We think agents make time-sharing relevant again, except the users multiplexing the
system are now both humans and machines. A small team shouldn't feel small.

The longer argument, and where we think this goes: VISION.md.

License Copy Chapter

Multica License — the complete Apache License 2.0 text plus additional conditions
covering hosted services, commercial embedding, and branding. Self-host it, modify it, build on
it; the exact terms are in the LICENSE, attribution notices in NOTICE.

File: apps/docs/content/docs/developers/architecture.mdx Copy Chapter

title: Project architecture Copy Chapter

Multica consists of a Go backend, multiple clients, and a daemon that runs on execution computers. PostgreSQL stores collaboration data; the daemon claims tasks and invokes local AI coding tools.

Web / Desktop / Mobile / CLI
             │
       HTTP + WebSocket
             │
      Go API ───────── PostgreSQL
             │
      daemon WebSocket
             │
     local daemon ─── AI coding tools

For a product-facing explanation, see How Multica works. This page focuses on how the code is layered.

Repository layout Copy Chapter

Shared packages export .ts and .tsx source files directly and are compiled by their consuming applications. The dependency direction is views → core + ui; core and ui do not depend on each other.

Code sharing between Web and Desktop Copy Chapter

Web and Desktop share three layers:

1. packages/core handles APIs, caching, permissions, and platform-independent state.
2. packages/ui provides foundational components.
3. packages/views composes business pages.

Platform capabilities such as routing, cookies, and Electron IPC stay in the application layer. Shared pages navigate through NavigationAdapter and do not import next/* or react-router-dom directly.

For example, an issue feature needed by both Web and Desktop usually touches:

packages/core/issues/      queries, mutations, cache updates
packages/views/issues/     pages and business components
apps/web/platform/         Next.js routing adapter
apps/desktop/.../platform/ Electron routing adapter

Mobile does not reuse these React pages. It may import types and pure functions from @multica/core, but it owns its UI, query keys, state, realtime subscriptions, and release process.

Frontend state Copy Chapter

Server data and client state are managed separately:

• TanStack Query owns server data such as issues, agents, members, and inbox items.
• Zustand owns client state such as filters, drafts, dialogs, and layout.
• The current workspace is route-driven and is mirrored at the platform layer only where requests, persisted namespaces, or reconnection require it.
• React Context carries only platform plumbing such as the workspace ID and navigation adapter.

WebSocket events should update or invalidate the TanStack Query cache. Do not copy server objects into Zustand. Mutations that navigate, such as creating, deleting, or leaving a workspace, must wait for server confirmation before clearing local state.

API responses are parsed with zod schemas at the packages/core/api/ boundary. An installed Desktop client may connect to a newer backend, so network JSON must not be asserted directly as a TypeScript type.

Backend layers Copy Chapter

The main entry points are in server/cmd/:

Requests usually flow in this direction:

router → middleware → handler → service → sqlc query → PostgreSQL

• internal/middleware/ handles authentication, workspace, and request boundaries.
• internal/handler/ parses HTTP input and produces responses.
• internal/service/ owns cross-query business workflows and transactions.
• pkg/db/queries/ contains handwritten SQL.
• pkg/db/generated/ is generated by sqlc and must not be edited directly.
• internal/integrations/ handles external events from GitHub, Slack, Feishu, and other services.
• internal/storage/ handles local and S3 attachments.

PostgreSQL is the source of truth for business data. Redis is optional and is used for cross-instance realtime events, caching, or temporary coordination. Without Redis, a single-instance development environment uses in-process implementations.

Realtime connections Copy Chapter

Multica has two distinct WebSocket paths:

• internal/realtime/ pushes issue, comment, inbox, and other changes to user clients.
• internal/daemonws/ connects daemons to wake runtimes and perform daemon RPC.

WebSocket reduces latency, but the database remains the final state. Clients must recalibrate through queries after reconnecting. The daemon also keeps a polling path so that one disconnect cannot leave a queued task stuck forever.

Code path for one execution Copy Chapter

1. A user assigns an issue, mentions an agent, or an automation triggers.
2. TaskService creates a queued task and notifies the corresponding runtime.
3. The daemon claims the task through the daemon API.
4. The server issues temporary credentials bound to the task and agent.
5. The daemon prepares a local directory and invokes the matching provider backend in pkg/agent.
6. The tool runs locally while the daemon uploads progress, messages, and final status.
7. The server updates the task and issue, then refreshes clients through realtime events.

The provider adapter layer normalizes startup, streaming events, cancellation, and usage data across AI coding tools, while the daemon still owns local directories and sessions.

Multi-workspace boundaries Copy Chapter

Business queries must be scoped by workspace_id, and membership is checked before a request enters a workspace route. X-Workspace-ID selects the current workspace but does not replace authorization checks.

An issue's assignee is polymorphic and may point to a member, agent, or squad. New queries, cache keys, and realtime events must preserve both the workspace and assignee type instead of assuming that a resource ID is globally unique context.

Next steps Copy Chapter

• Contributing — Local environments, worktrees, and test locations.
• Development conventions — Repository contracts for naming, terminology, and Chinese copy.

File: apps/docs/content/docs/developers/contributing.mdx Copy Chapter

title: Contributing Copy Chapter

import { Callout } from "fumadocs-ui/components/callout";

Multica is a Go backend and pnpm monorepo. The simplest way to start locally is make dev; it prepares the environment, database, and migrations for the current checkout, then starts Web and API.

Requirements Copy Chapter

• Node.js 22
• pnpm 10.28.2
• Go 1.26.6
• Docker Engine or Docker Desktop
• Git and Make

Treat the root package.json, server/go.mod, and CI workflows as the source of truth for versions.

First start Copy Chapter

git clone https://github.com/multica-ai/multica.git
cd multica
make dev

The primary checkout uses .env. If the file does not exist, make dev creates it from .env.example, then starts the shared PostgreSQL instance, installs dependencies, runs migrations, and starts API and Web.

Default addresses:

Web: http://localhost:3000
API: http://localhost:8080

The fixed local verification code comes from the development configuration. Do not use a local .env for an internet-facing deployment.

Developing in a worktree Copy Chapter

The repository supports running the primary checkout and multiple worktrees at the same time. They share one PostgreSQL container but use separate databases and ports.

git worktree add ../multica-feature -b feat/my-change main
cd ../multica-feature
make setup-worktree
make start-worktree

make setup-worktree generates .env.worktree; the database name and ports are derived from the path. To start it again:

make start-worktree

To stop Web and API for the current worktree:

make stop-worktree

You may also run make dev directly. The script detects a worktree through its .git file and selects .env.worktree.

Common commands Copy Chapter

Full workflow Copy Section

make dev              # Prepare and start the current checkout
make start            # Start API and Web with the existing environment
make stop             # Stop processes for the current checkout
make check            # Run the complete local verification workflow
make build            # Build the server, CLI, and migrate binaries

Frontend Copy Section

pnpm install
pnpm dev:web
pnpm dev:desktop
pnpm build
pnpm typecheck
pnpm lint
pnpm test

Root commands exclude Mobile by default. Mobile has separate scripts and CI; read apps/mobile/CLAUDE.md before changing it.

Backend Copy Section

make server
make daemon
make test
make migrate-up
make migrate-down
make sqlc

To run a CLI command from source:

make cli ARGS="issue list"

Changing frontend features Copy Chapter

Place features needed by both Web and Desktop according to responsibility:

1. Put API types, queries, mutations, and platform-independent logic in packages/core/.
2. Put foundational UI in packages/ui/; it must not depend on business code.
3. Put business pages and components in packages/views/.
4. Keep Next.js, Electron, and routing adapters in the corresponding app.
5. Wire shared pages into both Web and Desktop.

TanStack Query owns server data. Zustand owns client state such as filters, drafts, and layout. See Project architecture and the root CLAUDE.md for the exact boundary.

When adding or changing an API, update the zod schema in packages/core/api/ and add parsing tests for missing fields, unknown enum values, and malformed data.

Changing the database Copy Chapter

Migrations live in server/migrations/, and queries live in server/pkg/db/queries/.

1. Use the next unused numeric prefix and create both .up.sql and .down.sql.
2. Do not add database foreign keys, cascade deletes, or cascade updates. Enforce relationships and cleanup in the application layer.
3. Every new index must use CREATE INDEX CONCURRENTLY or CREATE UNIQUE INDEX CONCURRENTLY.
4. Put each concurrent index in a migration file containing only that statement.
5. Run make sqlc after changing queries and commit the generated changes in server/pkg/db/generated/.
6. Do not edit sqlc-generated files directly.

Use an application transaction in the service layer when multiple writes must succeed or roll back together.

Test locations Copy Chapter

Run the check closest to the change first, then expand the scope. For a Docs-only change:

pnpm --filter @multica/docs typecheck

For shared frontend changes:

pnpm typecheck
pnpm test

For backend changes:

make test

Before submitting:

make check

make check runs TypeScript typechecking and unit tests, Go tests, and Playwright E2E. CI also builds and lints according to the changed scope and runs platform- or installer-specific tests.

Resetting the current development database Copy Chapter

When you need clean data, reset the database named by the current checkout's environment file:

make stop
make db-reset
make start

make db-reset drops and recreates the current POSTGRES_DB and refuses to connect to a remote database. Before running it, check .env or .env.worktree and confirm the target database.

Before submitting Copy Chapter

• Read the root CLAUDE.md and relevant nested instructions.
• Change only the scope required by the task.
• Write code comments in English.
• Do not commit .env, tokens, build artifacts, or local paths.
• Use conventional commits such as feat(scope), fix(scope), or docs.
• Describe behavior changes and the verification commands actually run in the PR.

Next steps Copy Chapter

• Development conventions — Repository contracts for naming, terminology, and Chinese copy.
• Project architecture — Layers, shared packages, and the code path for one execution.

File: apps/docs/content/docs/index.mdx Copy Chapter

title: Welcome Copy Chapter

What Multica can do Copy Chapter

• Hand work to agents — assign an issue the way you would to a teammate; the agent posts progress and delivers results.
• Share all context — discussions, records, and deliverables stay in the workspace, visible to the whole team at any time.
• Let work run itself — set up scheduled runs and let multiple agents collaborate automatically.
• Capture team know-how — save what works as a skill that every agent can reuse.

Where to start Copy Chapter

• Complete your first run — create an agent, hand it its first task, and see the result come back.
• Core concepts — meet all of Multica's core objects and how they relate, in three minutes.
• Self-host Multica — deploy Multica on your own infrastructure.

Most-visited pages Copy Chapter

• Get agents working — the four ways to trigger an agent.
• Create and configure agents — create your first agent from blank or with AI.
• Install AI coding tools — give your computer the ability to execute.
• Tasks — read the status, retries, and logs of every run.
• Troubleshooting — agent not moving? Start here.

Community Copy Chapter

Questions, product suggestions, or interest in contributing to Multica — reach us through these channels: