New: 97,000+ skills indexed from GitHub repos with 100+ stars · every skill safety-checkedBrowse top skillsTop skills
Esc to closeBrowse all skills
Submit a skillBrowse skills
Submit a skillBrowse skills

Agent skill

Project Switching

by marcus in marcus/sidecar

Project switching implementation in sidecar: project discovery, state management, UI flow, modal rendering, filtering, theme preview, and plugin reinitialization.

MITAuto-check passedFrontend & Design

Install Project Switching

skills CLI
$ npx skills add marcus/sidecar --skill project-switching -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install marcus/sidecar project-switching --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/marcus/sidecar.git skills-src && mkdir -p .claude/skills && cp -r skills-src/.claude/skills/project-switching .claude/skills/project-switching && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
project-switching
GitHub stars
1.1k
Token cost
~1.8k tokens
SKILL.md length
582 words
Files
2 (incl. references)
Skills in repo
19
Repo updated
First seen
Licence
MIT

At a glance

Project switching implementation in sidecar: project discovery, state management, UI flow, modal rendering, filtering, theme preview, and plugin reinitialization.

  • Works in 9 steps: Skip if same project (show toast) → Save active plugin state for old workdir → Check for saved worktree to restore → …
  • Working on the project switcher feature
  • SKILL.md covers Architecture Overview, Project vs Worktree Switching, Configuration and Core Flow, plus 9 more sections
  • Instructions only: no scripts, shell commands, URLs or credentials in SKILL.md

What it does

Project Switching is an agent skill from marcus/sidecar. Project switching implementation in sidecar: project discovery, state management, UI flow, modal rendering, filtering, theme preview, and plugin reinitialization. Use when working on the project switcher feature, project management, worktree switching, or the project configuration system.

Its SKILL.md is about 1.8k tokens, which your agent loads only when the skill is triggered. The skill folder holds 2 other files, including reference files (for example `references/implementation-details.md`).

It sits in Frontend & Design, covering Git worktrees, State management and Project management. The repository describes itself as: Use sidecar next to CLI agents for diffs, file trees, conversation history, and task management with td. The licence is MIT.

When your agent uses it

  • Working on the project switcher feature
  • Project management
  • Worktree switching
  • The project configuration system

Example prompts

  • “/project-switching”

Workflow steps

9 steps, taken from the first numbered list in SKILL.md.

  1. Skip if same project (show toast)
  2. Save active plugin state for old workdir
  3. Check for saved worktree to restore
  4. Update m.ui.WorkDir and repo name
  5. Apply project-specific theme
  6. Reinitialize all plugins via m.registry.Reinit(targetPath)
  7. Send WindowSizeMsg for layout recalculation
  8. Restore previously active plugin for new workdir
  9. Return toast notification

What it can do on your machine

Read from SKILL.md and the folder at commit 3792a4e. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    No scripts in the folder and no shell commands in SKILL.md (its code samples are go and json).

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Project Switching loads about 1.8k tokens when it runs, and up to ~4.2k if it reads all its reference files. Until then it costs about 77 tokens; SKILL.md has 582 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~77
When it runs · the whole SKILL.md, loaded when a task matches
~1.8k
With references · SKILL.md plus every file in references/, read only if the agent opens them
~4.2k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from marcus/sidecar at commit 3792a4e, republished under its MIT licence (© marcus). 582 words, ~1,756 tokens.

Download SKILL.mdSave it as .claude/skills/project-switching/SKILL.md (or your agent's skills folder). This skill also uses 1 other file; get the full folder from GitHub.
name
project-switching
description
Project switching implementation in sidecar: project discovery, state management, UI flow, modal rendering, filtering, theme preview, and plugin reinitialization. Use when working on the project switcher feature, project management, worktree switching, or the project configuration system.
user-invocable
false

Project Switching

Switch between git repositories without restarting sidecar. Press @ to open the project switcher modal.

Architecture Overview

The project switcher uses the app's declarative modal library (internal/modal/) for rendering and mouse handling.

Key Files
FileContents
internal/app/model.goState, init, reset, filter, switch, theme preview
internal/app/update.goKeyboard and mouse handlers
internal/app/view.goModal building and section rendering
internal/modal/Modal library (builder, sections, layout)
internal/config/types.goProjectConfig struct
internal/config/loader.goConfig loading with path validation
Model State
go
// internal/app/model.go
showProjectSwitcher         bool
projectSwitcherCursor       int
projectSwitcherScroll       int
projectSwitcherInput        textinput.Model
projectSwitcherFiltered     []config.ProjectConfig
projectSwitcherModal        *modal.Modal           // Cached modal instance
projectSwitcherModalWidth   int                    // Width for cache invalidation
projectSwitcherMouseHandler *mouse.Handler

Project vs Worktree Switching

  • Project Switching (@): Switch between configured projects from config.json (arbitrary repos)
  • Worktree Switching (W): Switch between git worktrees within the current repository

Configuration

Projects are configured in ~/.config/sidecar/config.json:

json
{
  "projects": {
    "list": [
      {"name": "sidecar", "path": "~/code/sidecar"},
      {"name": "td", "path": "~/code/td", "theme": "dark"}
    ]
  }
}

Paths support ~ expansion. Projects can have per-project themes.

Core Flow

Opening (@ key)
go
case "@":
    m.showProjectSwitcher = !m.showProjectSwitcher
    if m.showProjectSwitcher {
        m.activeContext = "project-switcher"
        m.initProjectSwitcher()
    } else {
        m.resetProjectSwitcher()
        m.updateContext()
    }
Initialization (model.go:433-454)

initProjectSwitcher() clears cached modal, creates text input with "Filter projects..." placeholder, loads all projects, pre-selects current project, and previews its theme.

Cleanup (model.go:413-423)

resetProjectSwitcher() resets all state, clears modal cache, and restores current project's theme (undoing any live preview).

Modal Rendering

Uses internal/modal/ with a builder pattern and lazy caching.

Modal Structure
+-------------------------------------------+
| Switch Project                            |  <- Title
| [Filter projects...                    ]  |  <- Input section
| 3 of 10 projects                          |  <- Count section
|   ^ 2 more above                          |  <- Scroll indicator
| > sidecar                                 |  <- Selected item
|   ~/code/sidecar                          |
|   td (current)                            |  <- Current project (green)
|   v 5 more below                          |  <- Scroll indicator
| enter switch  up/down navigate  esc close |  <- Hints section
+-------------------------------------------+
Caching (view.go:114-137)

ensureProjectSwitcherModal() builds modal only when it does not exist or width changed. Call clearProjectSwitcherModal() when content changes (filter input, cursor movement with scroll).

Section Types
TypeFactoryPurpose
Inputmodal.Input()Text input with focus
Custommodal.Custom()Complex content with focusables
Textmodal.Text()Static text
Buttonsmodal.Buttons()Button row

Keyboard Handling (update.go:600-690)

Priority: KeyType switch (special keys) -> String switch (named keys) -> Fallthrough to textinput.

KeyAction
EscClear filter (if set) or close modal
EnterSwitch to selected project
Up/DownArrow navigation
ctrl+n/ctrl+pEmacs-style navigation
Other keysForwarded to text input for filtering
Esc Behavior

First Esc clears filter if set. Second Esc (or first with empty filter) closes modal.

Navigation

Cursor movement updates projectSwitcherCursor and calls projectSwitcherEnsureCursorVisible() to maintain scroll window (max 8 visible items).

Filtering (model.go:457-470)

filterProjects() does case-insensitive substring match on both Name and Path fields. On filter change: clear modal cache, clamp cursor, reset scroll, preview theme.

Mouse Handling (update.go:1073-1115)

Uses modal library's HandleMouse(). Each project item has a focusable ID (project-switcher-item-N). Click on item triggers switch. Hover state managed by modal library via hoverID string.

Show full SKILL.md (231 more words)Show less

Theme Preview (model.go:580-586)

previewProjectTheme() applies the selected project's theme live. Called on init, cursor movement, and filter changes. Theme is restored in resetProjectSwitcher().

Project Switching (model.go:485-577)

switchProject() performs:

  1. Skip if same project (show toast)
  2. Save active plugin state for old workdir
  3. Check for saved worktree to restore
  4. Update m.ui.WorkDir and repo name
  5. Apply project-specific theme
  6. Reinitialize all plugins via m.registry.Reinit(targetPath)
  7. Send WindowSizeMsg for layout recalculation
  8. Restore previously active plugin for new workdir
  9. Return toast notification
What Happens on Switch
  1. All plugins stop (file watchers, git commands, etc.)
  2. Plugin context updates to new working directory
  3. All plugins reinitialize with new path
  4. Previously active plugin for that project is restored
  5. Toast notification confirms the switch

State Persistence

Per-project state saved in ~/.config/sidecar/state.json:

  • Active plugin per project
  • File browser cursor position and expanded directories
  • Sidebar widths and view preferences

Common Pitfalls

  1. Forgetting updateContext() -- Call after closing modal to restore app context
  2. Stale modal cache -- Call clearProjectSwitcherModal() when content changes
  3. Cursor out of bounds -- Always clamp after filtering
  4. Printable keys vs navigation -- Keep printable characters routed to textinput
  5. Theme preview cleanup -- Always restore theme in resetProjectSwitcher()
  6. Focusable coordinates -- Each project takes 2 lines (name + path)

Adding Features

See references/implementation-details.md for detailed implementation patterns including adding keyboard shortcuts, project metadata, filter algorithms, and new modal sections.

© marcus, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 1 other file (references) in .claude/skills/project-switching of marcus/sidecar.

  • SKILL.md
  • references/implementation-details.md

Open the folder on GitHubat commit 3792a4e

Compare with similar skills

Project Switching next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Project Switching compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Project Switching this skillmarcus/sidecar1.1k—~1.8kAutomated safety check: PassMIT
Shep Workstreamsshep-ai/shep264—~2.5kAutomated safety check: PassMIT
Vc Review Situationwithkynam/vibecode-pro-max-kit1.1k—~2.2kAutomated safety check: PassMIT
Dify Component Writing Guidelanggenius/dify158k—~626Automated safety check: PassCustom licence
Worklog Designregisx001/Worklog258—~3.3kAutomated safety check: PassMIT
Codex Issue Coordinatorowainlewis/blueprint412—~2.6kAutomated safety check: PassMIT

Similar skills

  • Shep Workstreams

    shep-ai/shep

    A skill your agent uses when a large body of work (a version milestone, an epic, a roadmap, a set of PRDs/design docs) needs to be broken into parallel workstreams and executed with the shep CLI.

    264 GitHub stars~2.5k tokensUpdated 2 days ago
    Product & Project ManagementAuto-check passed

  • Vc Review Situation

    withkynam/vibecode-pro-max-kit

    A skill your agent uses when you need a read-only situation review and handoff summary of current branch state, local/remote refs, worktrees, active project plans, selected-plan hints, and suggested…

    1.1k GitHub stars~2.2k tokensUpdated 3 mo ago
    Product & Project ManagementAuto-check passed

  • Dify Component Writing Guide

    langgenius/dify

    Use when implementing or refactoring React/TypeScript components and the task requires decisions about component ownership, feature boundaries, state, data…

    158k GitHub stars~626 tokensUpdated today
    Frontend & DesignAuto-check passed

  • Worklog Design

    regisx001/Worklog

    Design and UI skill for the Worklog desktop project manager.

    258 GitHub stars~3.3k tokensUpdated 1 mo ago
    Frontend & DesignAuto-check passed

  • Codex Issue Coordinator

    owainlewis/blueprint

    Lets one Codex thread run a batch of GitHub issues through separate worker threads, each with its own worktree, branch, tested pull request and gated merge.

    412 GitHub stars~2.6k tokensUpdated yesterday
    Agent WorkflowsAuto-check passed

  • Expressive Mvc

    gabeklein/expressive-mvc

    Class-based reactive state management for React (Expressive MVC).

    103 GitHub stars~5.9k tokensUpdated today
    Frontend & DesignAuto-check passed

More from marcus/sidecar

All 19 skills in this repo

  • Create Adapter

    marcus/sidecar

    Create conversation adapters for importing AI chat history from different tools (Claude Code, Cursor, Warp, Codex, etc.).

    1.1k GitHub stars~4.8k tokensUpdated 2 days ago
    Auto-check passed

  • Create Modal

    marcus/sidecar

    Create declarative modals using the modal library API. An agent skill from marcus/sidecar.

    1.1k GitHub stars~2.6k tokensUpdated 2 days ago
    Auto-check passed

  • Create Plugin

    marcus/sidecar

    Create new sidecar plugins implementing the plugin.Plugin interface, rendering views with Bubble Tea, handling keyboard input via keymap contexts, and integrating with the app shell (footer hints…

    1.1k GitHub stars~2.3k tokensUpdated 2 days ago
    Auto-check passed

  • Shell Integration

    marcus/sidecar

    Interactive shell/TTY integration with tmux session management, shell command execution, control-mode output capture with polling fallback, native cursor rendering, lazy scrollback, selection, paste…

    1.1k GitHub stars~3.6k tokensUpdated 2 days ago
    Auto-check passed

  • Sidecar Website

    marcus/sidecar

    Writing and maintaining the Sidecar Docusaurus documentation site, including page structure, doc authoring, blog posts, styling, images, and deployment workflow.

    1.1k GitHub stars~1.7k tokensUpdated 2 days ago
    Auto-check passed

  • UI Features

    marcus/sidecar

    Implementing UI/UX features in sidecar including modals (internal/modal library), keyboard shortcuts, mouse support, scrolling, pill/tab rendering, and pane resizing.

    1.1k GitHub stars~4.6k tokensUpdated 2 days ago
    Auto-check passed

Categories

Questions about Project Switching

What does Project Switching do?

Project switching implementation in sidecar: project discovery, state management, UI flow, modal rendering, filtering, theme preview, and plugin reinitialization. Project Switching is an agent skill from marcus/sidecar. Project switching implementation in sidecar: project discovery, state management, UI flow, modal rendering, filtering, theme preview, and plugin reinitialization.

When should I use Project Switching?

Project Switching fits situations like: working on the project switcher feature; project management; worktree switching; the project configuration system.

How do I install Project Switching in Claude Code?

Run `npx skills add marcus/sidecar --skill project-switching -a claude-code`. Or copy the skill folder (.claude/skills/project-switching in marcus/sidecar) into .claude/skills/project-switching in your project. Claude Code loads it when a task matches its description.

How do I install Project Switching in Codex?

Run `npx skills add marcus/sidecar --skill project-switching -a codex`. Or copy the skill folder (.claude/skills/project-switching in marcus/sidecar) into .agents/skills/project-switching in your project. Codex loads it when a task matches its description.

Can I use Project Switching in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add marcus/sidecar --skill project-switching -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/project-switching, .gemini/skills/project-switching, .github/skills/project-switching and .opencode/skills/project-switching in your project.

What does Project Switching need to run?

SKILL.md names no scripts, command-line tools or credentials: Project Switching is instructions for the agent only.

Does Project Switching access the network?

SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.

Is Project Switching safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Project Switching use?

Project Switching is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Project Switching use?

About 1.8k tokens (SKILL.md is roughly 7k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full. Its references folder adds about 2.4k tokens, read only when the agent opens those files.

What are the alternatives to Project Switching?

Skills that share tags, products or a category with Project Switching: Shep Workstreams (shep-ai/shep, 264 stars), Vc Review Situation (withkynam/vibecode-pro-max-kit, 1.1k stars), Dify Component Writing Guide (langgenius/dify, 158k stars) and Worklog Design (regisx001/Worklog, 258 stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Project Switching?

marcus (a GitHub user) maintains it in marcus/sidecar, which has 1,085 GitHub stars. The repository holds 19 skills in this directory. The repository was last updated on October 5, 2026.

Source: marcus/sidecar on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.