multica-runtimes-and-repos

Name: multica-runtimes-and-repos
Author: multica-ai

9installs5.2kforks

How to install multica-runtimes-and-repos?

multica-ai/multica/multica-runtimes-and-repos

$npx -y skills add multica-ai/multica --skill multica-runtimes-and-repos

Installs into the current project.

Summary

Use when inspecting or debugging Multica runtimes, daemon task claiming, agent not running, workdir/session reuse, or repository checkout. Covers runtime online/offline state, daemon heartbeat/claim chain, task-scoped repo checkout, project repo context, local_directory caveats,

Files · 1

View on GitHub

SKILL.md

1	# Multica Runtimes and Repos
2
3	## Quick start
4
5	For "agent did not run" or "repo checkout failed", read the chain before changing anything:
6
7	```bash
8	multica agent get <agent-id> --output json
9	multica runtime list --output json
10	multica repo checkout <repo-url>
11	```
12
13	Runtime and repo commands affect active agent execution. Do not restart daemons, update runtimes, or check out arbitrary repos just to test.
14
15	## Core model
16
17	A runtime is the execution target behind an agent. A daemon owns local runtime processes and claims queued tasks from the server.
18
19	The chain is:
20
21	1. user action creates or updates an `agent_task_queue` row;
22	2. the task points at an agent and runtime;
23	3. server wakes the runtime over daemon websocket when possible;
24	4. daemon polls/claims the task;
25	5. server returns task context, repos, project resources, prior session/workdir hints, and task token;
26	6. daemon prepares a workdir and launches the provider CLI;
27	7. `multica repo checkout` talks to the local daemon, not directly to GitHub.
28
29	## CLI
30
31	```bash
32	multica runtime list --output json
33	multica runtime usage <runtime-id> --output json
34	multica runtime activity <runtime-id> --output json
35	multica runtime update <runtime-id> --target-version <version> --output json
36	multica runtime delete <runtime-id>
37	multica repo checkout <url>
38	multica repo checkout <url> --ref <branch-or-sha>
39	```
40
41	`runtime update` and `runtime delete` are writes. Starting a runtime update is limited to its owner or a workspace owner/admin; the original initiator may keep polling that specific in-flight request if their admin role changes. `runtime delete` removes a runtime registration; if active agents are still bound, it refuses unless the user explicitly passes `--cascade`, which archives those agents and cancels their queued/running tasks before deleting the runtime. `repo checkout` creates a dedicated branch in the task working directory. Most runtimes use a linked worktree; Linux Codex uses task-local Git metadata so its `workspace-write` sandbox can stage and commit without making the shared `.repos` cache writable.
42
43	`repo checkout` requires `MULTICA_DAEMON_PORT`; it is intended to run inside a daemon task. If absent, you are not in the normal agent checkout path. When a project `github_repo` resource has `resource_ref.ref`, `repo checkout <url>` uses that ref by default for the current task; an explicit `repo checkout <url> --ref <branch-or-sha>` overrides it.
44
45	## Debugging an agent that did not run
46
47	Check in this order:
48
49	1. Was a task supposed to be created? Inspect issue/comment/autopilot context.
50	2. Is the assignee an agent or squad? A squad routes to its leader.
51	3. Is the agent archived or bound to a runtime the actor cannot use?
52	4. Is the runtime online? `multica runtime list --output json`.
53	5. Did the daemon heartbeat recently? Runtime `last_seen_at` is the visible clue.
54	6. Did the task get claimed or is it stuck pending/running/waiting for local directory?
55	7. If repo checkout failed, classify it after checking whether repo context was
56	present in the task/project context.
57
58	## Repos
59
60	The runtime brief lists repos available to this task. Treat that list as the authority for agent checkout unless the user explicitly asks to bind a new project resource.
61
62	Workspace repos and project resources are not the same thing:
63
64	- workspace repo metadata can appear in workspace context;
65	- `github_repo` project resources are durable project context and can affect future tasks; optional `resource_ref.ref` pins the default checkout ref for tasks in that project;
66	- `local_directory` resources point at a path owned by a daemon and carry local-machine assumptions.
67
68	Do not add a project resource just because `repo checkout` failed. First determine whether the user asked for durable project context or just a task checkout.
69
70	More source-backed details: `references/runtimes-and-repos-source-map.md`.

People who liked this also viewed

6 picks

Type

multica-runtimes-and-repos

9installs5.2kforks

View on GitHub

How to install multica-runtimes-and-repos?

multica-ai/multica/multica-runtimes-and-repos

$npx -y skills add multica-ai/multica --skill multica-runtimes-and-repos

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Multica Runtimes and Repos
2
3	## Quick start
4
5	For "agent did not run" or "repo checkout failed", read the chain before changing anything:
6
7	```bash
8	multica agent get <agent-id> --output json
9	multica runtime list --output json
10	multica repo checkout <repo-url>
11	```
12
13	Runtime and repo commands affect active agent execution. Do not restart daemons, update runtimes, or check out arbitrary repos just to test.
14
15	## Core model
16
17	A runtime is the execution target behind an agent. A daemon owns local runtime processes and claims queued tasks from the server.
18
19	The chain is:
20
21	1. user action creates or updates an `agent_task_queue` row;
22	2. the task points at an agent and runtime;
23	3. server wakes the runtime over daemon websocket when possible;
24	4. daemon polls/claims the task;
25	5. server returns task context, repos, project resources, prior session/workdir hints, and task token;
26	6. daemon prepares a workdir and launches the provider CLI;
27	7. `multica repo checkout` talks to the local daemon, not directly to GitHub.
28
29	## CLI
30
31	```bash
32	multica runtime list --output json
33	multica runtime usage <runtime-id> --output json
34	multica runtime activity <runtime-id> --output json
35	multica runtime update <runtime-id> --target-version <version> --output json
36	multica runtime delete <runtime-id>
37	multica repo checkout <url>
38	multica repo checkout <url> --ref <branch-or-sha>
39	```
40
41	`runtime update` and `runtime delete` are writes. Starting a runtime update is limited to its owner or a workspace owner/admin; the original initiator may keep polling that specific in-flight request if their admin role changes. `runtime delete` removes a runtime registration; if active agents are still bound, it refuses unless the user explicitly passes `--cascade`, which archives those agents and cancels their queued/running tasks before deleting the runtime. `repo checkout` creates a dedicated branch in the task working directory. Most runtimes use a linked worktree; Linux Codex uses task-local Git metadata so its `workspace-write` sandbox can stage and commit without making the shared `.repos` cache writable.
42
43	`repo checkout` requires `MULTICA_DAEMON_PORT`; it is intended to run inside a daemon task. If absent, you are not in the normal agent checkout path. When a project `github_repo` resource has `resource_ref.ref`, `repo checkout <url>` uses that ref by default for the current task; an explicit `repo checkout <url> --ref <branch-or-sha>` overrides it.
44
45	## Debugging an agent that did not run
46
47	Check in this order:
48
49	1. Was a task supposed to be created? Inspect issue/comment/autopilot context.
50	2. Is the assignee an agent or squad? A squad routes to its leader.
51	3. Is the agent archived or bound to a runtime the actor cannot use?
52	4. Is the runtime online? `multica runtime list --output json`.
53	5. Did the daemon heartbeat recently? Runtime `last_seen_at` is the visible clue.
54	6. Did the task get claimed or is it stuck pending/running/waiting for local directory?
55	7. If repo checkout failed, classify it after checking whether repo context was
56	present in the task/project context.
57
58	## Repos
59
60	The runtime brief lists repos available to this task. Treat that list as the authority for agent checkout unless the user explicitly asks to bind a new project resource.
61
62	Workspace repos and project resources are not the same thing:
63
64	- workspace repo metadata can appear in workspace context;
65	- `github_repo` project resources are durable project context and can affect future tasks; optional `resource_ref.ref` pins the default checkout ref for tasks in that project;
66	- `local_directory` resources point at a path owned by a daemon and carry local-machine assumptions.
67
68	Do not add a project resource just because `repo checkout` failed. First determine whether the user asked for durable project context or just a task checkout.
69
70	More source-backed details: `references/runtimes-and-repos-source-map.md`.

People who liked this also viewed

6 picks

Type