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 folder or an isolated worktree 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 executing a run has a matching local directory, the agent uses it in in_place mode or an isolated worktree of it in worktree mode; other computers keep using the project's GitHub repositories or the workspace repositories.
Add a GitHub repository
Open the project and click Add repository in Resources → Repositories. Search for a repository already linked to the workspace, or paste a Git URL. Workspace repositories are managed in Settings → Code; once GitHub is connected, the same page offers Pick from GitHub to import repositories the App is authorized for.
Pasting a GitHub branch URL (https://github.com/owner/repo/tree/branch) fills in the repository URL and starting branch separately. URL-encoded branch names are decoded; query parameters and page anchors are excluded. Check the starting branch before adding the repository. Changing the repository URL clears the previous starting branch unless the new URL specifies one.
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 → Code; 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.
For a managed repository, the agent starts in the task working directory. multica repo checkout normally creates a subdirectory for the repository and prints its path. Run commands that need the repository root from that path. If the agent process itself must start at the root and you control the runtime computer, attach an existing checkout as a local directory. Both in_place and worktree start the agent at a repository root; prefer worktree for git repositories to keep runs isolated and parallel. See How runs share the directory.
Add a local directory
The UI for adding a local directory is Desktop-only, because browsers cannot pick folders on your computer.
This is for special cases; do not pick it just because it is convenient. 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 run is simply not viable.
If your directory is an ordinary git repo you can clone, use github_repo instead: it uses worktree mode by default, so any number of runs on the same repo can proceed at once. A local_directory processes one run at a time by default; if the directory is a git repo you can opt into worktree mode to get concurrency back (see How runs share the directory). If you are unsure, compare the two resource types at the top of this page.
Make sure Desktop's local daemon is online.
For an existing project, open Resources → Local folders and follow the steps below. When creating a project, use the Local folder tab instead; the folder and mode are saved when you create the project.
Under your computer, click Choose folder..., then pick the folder to use.
Pick Edit directly or Run in parallel, described under How runs share the directory, then click Add folder. Desktop preselects Run in parallel when the folder is a git repository the runtime on that machine can isolate, and Edit directly otherwise. To change it later, click the folder's mode label in Resources and choose another mode; the selection saves immediately.
Preselection applies only to a directory you are linking now. A directory linked earlier keeps the mode it was saved with, so an existing setup is never switched under you.
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.
In the default in_place mode a local directory is not an isolated environment: the agent directly sees and modifies your current branch and uncommitted files, and Multica does not automatically switch branches, stash, commit, push, or open PRs. Worktree mode is different — see How runs share the directory below.
How runs share the directory
A local directory has two execution modes, set per resource with execution_mode. Desktop shows them as Edit directly and Run in parallel when you add a folder, and as Direct and Parallel on the folder's mode label; the API, the CLI and the rest of this page use the identifiers.
The agent works directly in your directory, and runs execute one at a time. When two runs 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 or consume a daemon execution slot. A waiting run can be cancelled; otherwise it resumes startup once both the directory and execution capacity are available.
A plain non-git directory can only use this mode: worktree mode covers git repositories.
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>
# Link a local git repo and let runs execute concurrently in their own worktrees
multica project resource add <project-id> \
--type local_directory \
--local-path /absolute/path/to/repo \
--daemon-id <daemon-id> \
--execution-mode worktree
# Switch an existing local directory between modes
multica project resource update <project-id> <resource-id> --execution-mode worktree
multica project resource update <project-id> <resource-id> --execution-mode in_place
# Remove a resource
multica project resource remove <project-id> <resource-id>Resource changes affect runs 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 run.
- Runs — see run states such as
waiting_local_directory.