Project resources

Link GitHub repositories or local directories to a project so later runs get a stable working context.

Project resources tell agents which code this body of work uses and where to run. Resources stay linked to the project, so there is no need to re-paste repository URLs or local paths into every issue.

Two resource types are supported today:

Resource	Best for	Where runs happen
GitHub repository	Code shared by the team, with checkouts managed by the runtime	A runtime-managed working directory
Local directory	An existing checkout, a very large repository, or when you want to inspect local changes directly	The original directory on a specific computer

How resources enter a run

When an agent works an issue inside the project, Multica adds the project name, project description, and resource list to the run's context, and writes .multica/project/resources.json into the working directory.

The workspace's linked repository list is always included in the run context. Repositories linked to the project additionally specify the code and default ref this body of work uses.

A local directory only applies to the daemon it is bound to. When the daemon running a task has a matching local directory, the agent works directly in that directory; other computers keep using the project's GitHub repositories or the workspace repositories.

Add a GitHub repository

Open the project and choose "Add resource" under Resources. Pick a repository already linked to the workspace, or paste a Git URL. Workspace repositories are managed in Settings → Repositories; once GitHub is connected, the same page offers Pick from GitHub to import repositories the App is authorized for.

Repositories are not limited to GitHub: any Git URL the runtime can reach works as a repository resource. Self-hosted Multica can also connect self-hosted Forgejo, Gitea, or GitLab under Settings → Integrations → Git hosting; see Self-hosted Git hosting.

When creating a project, you can also pick repositories directly under Repos. One project can link multiple GitHub repositories.

A resource's ref sets the branch, tag, or commit that later checkouts use by default. default_branch_hint only gives the agent a default-branch hint and does not force a branch switch.

Add a local directory

The UI for adding a local directory is Desktop-only, because browsers cannot pick folders on your computer.

This is an escape hatch, not a more convenient default. local_directory exists for people who have no other option — the canonical case is a game project whose checkout is tens of gigabytes, where re-cloning per task is simply not viable.

If your directory is an ordinary git repo you can clone, use github_repo instead: it runs in worktree mode by default, so tasks on the same repo run with unlimited concurrency. Choosing local_directory means every task on that folder runs strictly one at a time, forever. Read "When to pick" below before you commit to it.

Make sure Desktop's local daemon is online.
Open the project's Resources.
Choose "Add local directory", then pick the folder to use.

The directory must be an absolute path, must already exist, and must be readable and writable by the current daemon. These paths are rejected: system roots and drive roots (/, C:\), home directories themselves and the parents of home directories (such as /Users, /home, /root), and system directories such as /etc, /var, /tmp, /usr, and /opt. If the chosen path is a symlink, it is resolved to its real path first and validated again by the same rules; the serial lock also applies to the real path.

Each project can link at most one local directory per daemon. Different computers on a team can each link their own directory for the same project.

A local directory is not an isolated environment. The agent directly sees and modifies your current branch and uncommitted files; Multica does not automatically switch branches, stash, commit, push, or open PRs.

Local directories run serially

When two tasks use the same real directory, the later one enters waiting_local_directory and continues after the earlier one releases the directory. Two paths that reach the same directory through different symlinks serialize the same way.

Waiting does not modify the directory. A waiting task can be cancelled; otherwise it waits until the directory becomes available.

To work on several changes at once, use a GitHub repository resource so the runtime prepares a separate working directory for each piece of work.

What gets written during a run

Beyond the code changes the agent makes, the runtime may also write into the directory the instruction files the current AI coding tool needs, plus .multica/project/resources.json. Add them to .gitignore if you do not want them under version control.

Multica never deletes a linked local directory when cleaning up run environments. The agent's changes to the directory are the same kind of changes as running an AI coding tool in your terminal yourself, and need the same review.

Manage resources with the CLI

# Link a repository when creating a project
multica project create \
  --title "Agent UX" \
  --repo https://github.com/multica-ai/multica

# List and add resources
multica project resource list <project-id>
multica project resource add <project-id> \
  --type github_repo \
  --url https://github.com/multica-ai/multica \
  --ref main

# Link a local directory on a specific daemon
multica project resource add <project-id> \
  --type local_directory \
  --local-path /absolute/path/to/repo \
  --daemon-id <daemon-id>

# Remove a resource
multica project resource remove <project-id> <resource-id>

Resource changes affect tasks created afterwards; they do not rewrite records of runs that already ended.

Next steps

Projects — learn about project context, progress, and the lead.
Daemons and runtimes — learn which computer picks up a task.
Tasks — see run states such as waiting_local_directory.