Query isolated Git worktree code maps with ProjectAtlas
Register existing Git worktrees under explicit MCP aliases, refresh their separate code maps, and return bounded source evidence across selected checkouts.
npx skills add agentskillexchange/skills --skill query-isolated-git-worktree-code-maps-with-projectatlas
Use ProjectAtlas when a coding agent must answer a source or dependency question across existing Git worktrees without confusing branch-local code maps. The operator selects a control checkout and connects its native ProjectAtlas MCP process. The agent registers existing checkouts under explicit aliases, initializes missing target maps, and returns source evidence labelled with the checkout that produced it.
What this skill actually does
Invoke this before planning or reviewing a change spanning parallel checkouts, especially when a single current-directory selection could route a query into the wrong branch. The deliverable is a bounded, alias-labelled source and relationship report. Ordinary single-checkout browsing can use the short atlas CLI; this skill specifically covers per-request MCP routing and explicit read-only federation.
- Install a version-matched native runtime and MCP host configuration using the upstream setup guide. Read the complete matching ProjectAtlas skill. Select the control checkout explicitly; the reserved alias main refers to that control, regardless of its branch name. Initialize its local atlas only when absent.
- Call atlas_worktree_list(include_retired: false), select an existing checkout using the returned stable selector, then call atlas_worktree_add(worktree: "RETURNED_SELECTOR", alias: "issue-430"). Resolve ambiguous or blocked selections before continuing.
- For an absent target map or typed init_required response, call atlas_init(worktree: "issue-430"). Let the supported initializer hydrate a compatible baseline or perform its full-init fallback. Keep each checkout’s writable SQLite map separate.
- Call atlas_session_brief(worktree: "issue-430", query: "YOUR_SCOPED_QUESTION", compact: true). Follow its returned summary, search, relation, or exact-slice next_call without reconstructing selectors or cursors. Pass the same worktree alias on every root-scoped request. Never supply both worktree and project_path.
- After saved edits, refresh the affected map with atlas_watch_once(worktree: "issue-430") when needed. For an explicit cross-worktree relation question, use atlas_symbol_relations(worktrees: ["main", "issue-430"], view: "detailed", file: "AN_ACTUAL_SOURCE_FILE", compact: true). Federation accepts two to eight aliases and retains each participant’s evidence and coverage labels.
- Finish at exact current source slices. Report the selected aliases, paths, evidence, unresolved relationships, freshness blockers and coverage limits. Treat static graph results as navigation evidence; they do not establish runtime execution. Stop when the question is answered.
Scope boundary: registration, refresh and query of independently owned worktree maps. This workflow does not create, switch, merge, prune or delete Git worktrees or branches, dispatch agent jobs, or share a writable database across divergent checkouts. Keep typed recovery guidance and do not reset a database as an orientation shortcut. Removing an Atlas registration retires its alias and leaves Git and the target files intact.
Prerequisites: existing local Git worktrees, a version-matched ProjectAtlas native runtime, and an MCP-compatible coding host. The upstream README documents Codex, Claude Code and OpenCode integrations. Framework: MCP, because explicit alias routing and federated graph queries use the MCP tool surface.
Verification boundary: exact upstream metadata, release, skill and worktree documentation were inspected. Installation and runtime behavior were not executed, and no security review is claimed. GitHub showed 456 stars and 11 forks on 2026-10-25; v0.5.0 was released that day. Package adoption and independent token-savings claims were not established.
Canonical source: ProjectAtlas. Versioned worktree workflow. Version-matched agent skill.