External repositories

External repository tools let agents inspect upstream projects, framework source, or reference implementations without mixing that code into the current worktree.

The workflow is alias-based: register a repository once, then search and read it by alias.

Tool inventory

Tool	Side effects	Purpose
`external_repo_add`	Clones or fetches plugin-managed Git state.	Registers an external repository by alias.
`external_repo_list`	Reads plugin-managed state.	Lists repositories registered for the current project.
`external_repo_search`	Read-only.	Searches inside a registered repository.
`external_repo_read`	Read-only.	Reads a file or line range from a registered repository.
`external_repo_tree`	Read-only.	Shows a compact tree for a registered repository.
`external_repo_status`	Read-only.	Reports ref, commit, dirty state, and local path.
`external_repo_update`	Fetches and checks out plugin-managed Git state.	Explicitly refreshes a registered repository.

Basic workflow

Register the repository with a short alias.
Use external_repo_tree when you need orientation.
Use external_repo_search to find relevant symbols, filenames, or text.
Use external_repo_read for exact files and line ranges.
Use external_repo_update only when you intentionally want fresher reference code.

This keeps external code inspection explicit and repeatable.

Storage model

External repositories are stored under the resolved plugin data directory:

<dataDir>/external-repos/
  mirrors/<repo_hash>.git
  projects/<project_hash>/registry.json
  projects/<project_hash>/<alias>/worktree

Mirror caches are shared by repository URL hash. Worktrees and registries are scoped to the current project hash.

Safety boundaries

The external repository tools do not expose arbitrary shell execution. They mutate only plugin-managed mirror/worktree state when registering or explicitly updating repositories.

Path handling is intentionally strict:

reads, trees, and searches must stay inside the registered worktree
symlink escapes are rejected
search does not follow symlinks
agents use aliases instead of arbitrary local paths

Use these tools when external source code is useful context, but should remain separate from the project you are editing.

On this page