From 0f2dfdbca87db1ea1d9143378bd235b6caf0e935 Mon Sep 17 00:00:00 2001 From: Jiayuan Date: Wed, 1 Apr 2026 14:05:19 +0800 Subject: [PATCH] docs: add CLI/Daemon guide and rename LOCAL_DEVELOPMENT.md to CONTRIBUTING.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add CLI_AND_DAEMON.md with full command reference, daemon configuration, profiles, and self-hosted setup instructions - Rename LOCAL_DEVELOPMENT.md → CONTRIBUTING.md for conventional naming - Update README.md references and link to the new CLI guide --- CLI_AND_DAEMON.md | 328 ++++++++++++++++++++++++ LOCAL_DEVELOPMENT.md => CONTRIBUTING.md | 4 +- README.md | 34 +-- 3 files changed, 335 insertions(+), 31 deletions(-) create mode 100644 CLI_AND_DAEMON.md rename LOCAL_DEVELOPMENT.md => CONTRIBUTING.md (98%) diff --git a/CLI_AND_DAEMON.md b/CLI_AND_DAEMON.md new file mode 100644 index 00000000..f2a0df8f --- /dev/null +++ b/CLI_AND_DAEMON.md @@ -0,0 +1,328 @@ +# CLI and Agent Daemon Guide + +The `multica` CLI connects your local machine to Multica. It handles authentication, workspace management, issue tracking, and runs the agent daemon that executes AI tasks locally. + +## Installation + +### Homebrew (macOS/Linux) + +```bash +brew tap multica-ai/tap +brew install multica-cli +``` + +### Build from Source + +```bash +git clone https://github.com/multica-ai/multica.git +cd multica +make build +cp server/bin/multica /usr/local/bin/multica +``` + +### Update + +```bash +multica update +``` + +This auto-detects your installation method (Homebrew or manual) and upgrades accordingly. + +## Quick Start + +```bash +# 1. Authenticate (opens browser for login) +multica login + +# 2. Start the agent daemon +multica daemon start + +# 3. Done — agents in your watched workspaces can now execute tasks on your machine +``` + +`multica login` automatically discovers all workspaces you belong to and adds them to the daemon watch list. + +## Authentication + +### Browser Login + +```bash +multica login +``` + +Opens your browser for OAuth authentication, creates a 90-day personal access token, and auto-configures your workspaces. + +### Token Login + +```bash +multica login --token +``` + +Authenticate by pasting a personal access token directly. Useful for headless environments. + +### Check Status + +```bash +multica auth status +``` + +Shows your current server, user, and token validity. + +### Logout + +```bash +multica auth logout +``` + +Removes the stored authentication token. + +## Agent Daemon + +The daemon is the local agent runtime. It detects available AI CLIs on your machine, registers them with the Multica server, and executes tasks when agents are assigned work. + +### Start + +```bash +multica daemon start +``` + +By default, the daemon runs in the background and logs to `~/.multica/daemon.log`. + +To run in the foreground (useful for debugging): + +```bash +multica daemon start --foreground +``` + +### Stop + +```bash +multica daemon stop +``` + +### Status + +```bash +multica daemon status +multica daemon status --output json +``` + +Shows PID, uptime, detected agents, and watched workspaces. + +### Logs + +```bash +multica daemon logs # Last 50 lines +multica daemon logs -f # Follow (tail -f) +multica daemon logs -n 100 # Last 100 lines +``` + +### Supported Agents + +The daemon auto-detects these AI CLIs on your PATH: + +| CLI | Command | Description | +|-----|---------|-------------| +| [Claude Code](https://docs.anthropic.com/en/docs/claude-code) | `claude` | Anthropic's coding agent | +| [Codex](https://github.com/openai/codex) | `codex` | OpenAI's coding agent | + +You need at least one installed. The daemon registers each detected CLI as an available runtime. + +### How It Works + +1. On start, the daemon detects installed agent CLIs and registers a runtime for each agent in each watched workspace +2. It polls the server at a configurable interval (default: 3s) for claimed tasks +3. When a task arrives, it creates an isolated workspace directory, spawns the agent CLI, and streams results back +4. Heartbeats are sent periodically (default: 15s) so the server knows the daemon is alive +5. On shutdown, all runtimes are deregistered + +### Configuration + +Daemon behavior is configured via flags or environment variables: + +| Setting | Flag | Env Variable | Default | +|---------|------|--------------|---------| +| Poll interval | `--poll-interval` | `MULTICA_DAEMON_POLL_INTERVAL` | `3s` | +| Heartbeat interval | `--heartbeat-interval` | `MULTICA_DAEMON_HEARTBEAT_INTERVAL` | `15s` | +| Agent timeout | `--agent-timeout` | `MULTICA_AGENT_TIMEOUT` | `2h` | +| Max concurrent tasks | `--max-concurrent-tasks` | `MULTICA_DAEMON_MAX_CONCURRENT_TASKS` | `20` | +| Daemon ID | `--daemon-id` | `MULTICA_DAEMON_ID` | hostname | +| Device name | `--device-name` | `MULTICA_DAEMON_DEVICE_NAME` | hostname | +| Runtime name | `--runtime-name` | `MULTICA_AGENT_RUNTIME_NAME` | `Local Agent` | +| Workspaces root | — | `MULTICA_WORKSPACES_ROOT` | `~/multica_workspaces` | + +Agent-specific overrides: + +| Variable | Description | +|----------|-------------| +| `MULTICA_CLAUDE_PATH` | Custom path to the `claude` binary | +| `MULTICA_CLAUDE_MODEL` | Override the Claude model used | +| `MULTICA_CODEX_PATH` | Custom path to the `codex` binary | +| `MULTICA_CODEX_MODEL` | Override the Codex model used | + +### Self-Hosted Server + +When connecting to a self-hosted Multica instance, point the CLI to your server before logging in: + +```bash +export MULTICA_APP_URL=https://app.example.com +export MULTICA_SERVER_URL=wss://api.example.com/ws + +multica login +multica daemon start +``` + +Or set them persistently: + +```bash +multica config set app_url https://app.example.com +multica config set server_url wss://api.example.com/ws +``` + +### Profiles + +Profiles let you run multiple daemons on the same machine — for example, one for production and one for a staging server. + +```bash +# Start a daemon for the staging server +multica --profile staging login +multica --profile staging daemon start + +# Default profile runs separately +multica daemon start +``` + +Each profile gets its own config directory (`~/.multica/profiles//`), daemon state, health port, and workspace root. + +## Workspaces + +### List Workspaces + +```bash +multica workspace list +``` + +Watched workspaces are marked with `*`. The daemon only processes tasks for watched workspaces. + +### Watch / Unwatch + +```bash +multica workspace watch +multica workspace unwatch +``` + +### Get Details + +```bash +multica workspace get +multica workspace get --output json +``` + +### List Members + +```bash +multica workspace members +``` + +## Issues + +### List Issues + +```bash +multica issue list +multica issue list --status in_progress +multica issue list --priority urgent --assignee "Agent Name" +multica issue list --limit 20 --output json +``` + +Available filters: `--status`, `--priority`, `--assignee`, `--limit`. + +### Get Issue + +```bash +multica issue get +multica issue get --output json +``` + +### Create Issue + +```bash +multica issue create --title "Fix login bug" --description "..." --priority high --assignee "Lambda" +``` + +Flags: `--title` (required), `--description`, `--status`, `--priority`, `--assignee`, `--parent`, `--due-date`. + +### Update Issue + +```bash +multica issue update --title "New title" --priority urgent +``` + +### Assign Issue + +```bash +multica issue assign --to "Lambda" +multica issue assign --unassign +``` + +### Change Status + +```bash +multica issue status in_progress +``` + +Valid statuses: `backlog`, `todo`, `in_progress`, `in_review`, `done`, `blocked`, `cancelled`. + +### Comments + +```bash +# List comments +multica issue comment list + +# Add a comment +multica issue comment add --content "Looks good, merging now" + +# Reply to a specific comment +multica issue comment add --parent --content "Thanks!" + +# Delete a comment +multica issue comment delete +``` + +## Configuration + +### View Config + +```bash +multica config show +``` + +Shows config file path, server URL, app URL, and default workspace. + +### Set Values + +```bash +multica config set server_url wss://api.example.com/ws +multica config set app_url https://app.example.com +multica config set workspace_id +``` + +## Other Commands + +```bash +multica version # Show CLI version and commit hash +multica update # Update to latest version +multica agent list # List agents in the current workspace +``` + +## Output Formats + +Most commands support `--output` with two formats: + +- `table` — human-readable table (default for list commands) +- `json` — structured JSON (useful for scripting and automation) + +```bash +multica issue list --output json +multica daemon status --output json +``` diff --git a/LOCAL_DEVELOPMENT.md b/CONTRIBUTING.md similarity index 98% rename from LOCAL_DEVELOPMENT.md rename to CONTRIBUTING.md index 50b9f80e..d0b8006f 100644 --- a/LOCAL_DEVELOPMENT.md +++ b/CONTRIBUTING.md @@ -1,6 +1,6 @@ -# Local Development Guide +# Contributing Guide -This guide documents the intended local development workflow for Multica. +This guide documents the local development workflow for contributors working on the Multica codebase. It covers: diff --git a/README.md b/README.md index db3e2660..56bc8780 100644 --- a/README.md +++ b/README.md @@ -42,43 +42,19 @@ make start The `multica` CLI connects your local machine to Multica — authenticate, manage workspaces, and run the agent daemon. -### Install - ```bash +# Install brew tap multica-ai/tap brew install multica-cli -``` -Or build from source: - -```bash -make build -cp server/bin/multica /usr/local/bin/multica -``` - -### Connect Your Agent Runtime - -```bash -# 1. Authenticate +# Authenticate and start multica login - -# 2. Watch your workspace -multica workspace watch - -# 3. Start the local agent daemon multica daemon start ``` The daemon auto-detects available agent CLIs (`claude`, `codex`) on your PATH. When an agent is assigned a task, the daemon creates an isolated environment, runs the agent, and reports results back. -### Other Commands - -```bash -multica workspace list # List workspaces (watched ones marked with *) -multica agent list # List agents in the current workspace -multica daemon status # Show daemon status -multica version # Show CLI version -``` +See the [CLI and Daemon Guide](CLI_AND_DAEMON.md) for the full command reference, daemon configuration, and advanced usage. ## Architecture @@ -101,7 +77,7 @@ multica version # Show CLI version ## Development -For contributors working on the Multica codebase, see the [Local Development Guide](LOCAL_DEVELOPMENT.md). +For contributors working on the Multica codebase, see the [Contributing Guide](CONTRIBUTING.md). ### Prerequisites @@ -119,7 +95,7 @@ make setup make start ``` -See [LOCAL_DEVELOPMENT.md](LOCAL_DEVELOPMENT.md) for the full development workflow, worktree support, testing, and troubleshooting. +See [CONTRIBUTING.md](CONTRIBUTING.md) for the full development workflow, worktree support, testing, and troubleshooting. ## License