docs: add CLI/Daemon guide and rename LOCAL_DEVELOPMENT.md to CONTRIBUTING.md
- 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
This commit is contained in:
Jiayuan
parent
3f612c37f2
commit
0f2dfdbca8
3 changed files with 335 additions and 31 deletions
328
CLI_AND_DAEMON.md
Normal file
328
CLI_AND_DAEMON.md
Normal file
|
|
@ -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/<name>/`), 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 <workspace-id>
|
||||||
|
multica workspace unwatch <workspace-id>
|
||||||
|
```
|
||||||
|
|
||||||
|
### Get Details
|
||||||
|
|
||||||
|
```bash
|
||||||
|
multica workspace get <workspace-id>
|
||||||
|
multica workspace get <workspace-id> --output json
|
||||||
|
```
|
||||||
|
|
||||||
|
### List Members
|
||||||
|
|
||||||
|
```bash
|
||||||
|
multica workspace members <workspace-id>
|
||||||
|
```
|
||||||
|
|
||||||
|
## 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 <id>
|
||||||
|
multica issue get <id> --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 <id> --title "New title" --priority urgent
|
||||||
|
```
|
||||||
|
|
||||||
|
### Assign Issue
|
||||||
|
|
||||||
|
```bash
|
||||||
|
multica issue assign <id> --to "Lambda"
|
||||||
|
multica issue assign <id> --unassign
|
||||||
|
```
|
||||||
|
|
||||||
|
### Change Status
|
||||||
|
|
||||||
|
```bash
|
||||||
|
multica issue status <id> in_progress
|
||||||
|
```
|
||||||
|
|
||||||
|
Valid statuses: `backlog`, `todo`, `in_progress`, `in_review`, `done`, `blocked`, `cancelled`.
|
||||||
|
|
||||||
|
### Comments
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# List comments
|
||||||
|
multica issue comment list <issue-id>
|
||||||
|
|
||||||
|
# Add a comment
|
||||||
|
multica issue comment add <issue-id> --content "Looks good, merging now"
|
||||||
|
|
||||||
|
# Reply to a specific comment
|
||||||
|
multica issue comment add <issue-id> --parent <comment-id> --content "Thanks!"
|
||||||
|
|
||||||
|
# Delete a comment
|
||||||
|
multica issue comment delete <comment-id>
|
||||||
|
```
|
||||||
|
|
||||||
|
## 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 <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
|
||||||
|
```
|
||||||
|
|
@ -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:
|
It covers:
|
||||||
|
|
||||||
34
README.md
34
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.
|
The `multica` CLI connects your local machine to Multica — authenticate, manage workspaces, and run the agent daemon.
|
||||||
|
|
||||||
### Install
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
|
# Install
|
||||||
brew tap multica-ai/tap
|
brew tap multica-ai/tap
|
||||||
brew install multica-cli
|
brew install multica-cli
|
||||||
```
|
|
||||||
|
|
||||||
Or build from source:
|
# Authenticate and start
|
||||||
|
|
||||||
```bash
|
|
||||||
make build
|
|
||||||
cp server/bin/multica /usr/local/bin/multica
|
|
||||||
```
|
|
||||||
|
|
||||||
### Connect Your Agent Runtime
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# 1. Authenticate
|
|
||||||
multica login
|
multica login
|
||||||
|
|
||||||
# 2. Watch your workspace
|
|
||||||
multica workspace watch <workspace-id>
|
|
||||||
|
|
||||||
# 3. Start the local agent daemon
|
|
||||||
multica daemon start
|
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.
|
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
|
See the [CLI and Daemon Guide](CLI_AND_DAEMON.md) for the full command reference, daemon configuration, and advanced usage.
|
||||||
|
|
||||||
```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
|
|
||||||
```
|
|
||||||
|
|
||||||
## Architecture
|
## Architecture
|
||||||
|
|
||||||
|
|
@ -101,7 +77,7 @@ multica version # Show CLI version
|
||||||
|
|
||||||
## Development
|
## 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
|
### Prerequisites
|
||||||
|
|
||||||
|
|
@ -119,7 +95,7 @@ make setup
|
||||||
make start
|
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
|
## License
|
||||||
|
|
||||||
|
|
|
||||||
Loading…
Add table
Add a link
Reference in a new issue