Worktree-centered development task dashboard with Obsidian integration.
npm install -g @jmchilton/ghwt
# or link locally for development
npm link
ghwt init --vaults-path ~/my-obsidian-vaults --vault-name ghwt
Options:
--vaults-path <path> - Directory containing Obsidian vaults (default: ~/Library/Mobile Documents/iCloud~md~obsidian/Documents)--vault-name <name> - Name of the Obsidian vault to create (default: ghwt)Creates:
~/projects/repositories/ - Base git repos~/projects/worktrees/ - Active development directories# Clone only
ghwt clone https://github.com/galaxyproject/galaxy.git
ghwt clone git@github.com:galaxyproject/galaxy.git
# Clone - auto-detects your fork if it exists!
ghwt clone https://github.com/galaxyproject/galaxy.git
# → If you have a fork, automatically uses your fork as origin + original as upstream
# Clone with explicit upstream (skips auto-detection)
ghwt clone git@github.com:jmchilton/galaxy.git \
--upstream git@github.com:galaxyproject/galaxy.git
# Clone with upstream and disable origin push (for safe fork workflow)
ghwt clone git@github.com:jmchilton/galaxy.git \
--upstream git@github.com:galaxyproject/galaxy.git \
--no-push
# Clone and create worktree
ghwt clone https://github.com/galaxyproject/gxformat2 test
ghwt clone https://github.com/galaxyproject/galaxy 1234
# Skip fork detection (useful if gh auth is not configured)
ghwt clone https://github.com/galaxyproject/galaxy.git --no-fork-check
Clones repository in ~/projects/repositories/<name>/
Options:
[branch] - Optional: creates worktree immediately (format: branch name or PR number)--upstream <url> - Optional: adds upstream remote (useful for forks); skips fork detection--no-push - Optional: disables push to origin (git remote set-url --push origin no-push), forcing pushes to go to upstream instead--no-fork-check - Optional: skips automatic fork detection (useful if gh CLI is not authenticated)ghwt create galaxy cool-feature
ghwt create galaxy fix-login
ghwt create galaxy 1234
Automatically:
ghwt sync # Sync all projects
ghwt sync galaxy # Sync specific project
ghwt sync --verbose # See detailed output
Updates:
Recreates missing items:
Example output:
📊 Sync complete: 3 updated, 1 note recreated, 2 sessions recreated, 0 errors
ghwt rm galaxy cool-feature
ghwt rm galaxy 1234
Automatically:
~/projects/old/Persistent, reconnectable development environments with tmux or zellij multiplexer:
ghwt create galaxy new-feature
# → Automatically launches session (if config exists)
ghwt attach galaxy new-feature
# → Reconnect to existing session (survives terminal crashes)
Features:
.venv/bin/activate)~/.ghwtrc.json)Per-worktree Claude Code sessions - automatically scoped to each worktree directory:
ghwt claude galaxy new-feature
# → Opens Claude in the worktree directory
ghwt claude galaxy new-feature --continue
# → Resumes last conversation in that worktree
ghwt claude galaxy new-feature "help me fix this bug"
# → Opens Claude with a prompt in that worktree
Features:
--continue flagQuick shortcuts to open worktree in different contexts, with interactive picker when args are optional:
# Open in VS Code
ghwt code # → Pick from all worktrees
ghwt code galaxy # → Pick from galaxy worktrees only
ghwt code galaxy 21199 # → Open directly (no picker)
ghwt code --this # → Open current worktree
# Open Obsidian note
ghwt note # → Pick from all worktrees
ghwt note training-material # → Pick from training-material only
ghwt note gxformat2 test # → Open directly
ghwt note --this # → Open current worktree's note
# Open on GitHub (branch or PR)
ghwt gh # → Pick from all worktrees
ghwt gh artifact-detective # → Pick from artifact-detective only
ghwt gh galaxy 21199 # → Open directly (reads PR URL from note or constructs branch URL)
ghwt gh --this # → Open current worktree on GitHub
# Attach to terminal session
ghwt attach # → Pick from all worktrees
ghwt attach galaxy # → Pick from galaxy sessions only
ghwt attach galaxy 21199 # → Attach directly
ghwt attach --this # → Attach to current worktree's session
# Open Claude in worktree
ghwt claude # → Pick from all worktrees
ghwt claude galaxy # → Pick from galaxy worktrees only
ghwt claude galaxy 21199 # → Open directly
ghwt claude galaxy fix --continue # → Resume last session
ghwt claude galaxy fix "help me understand this code" # → Open with prompt
ghwt claude --this # → Open Claude in current worktree
# Get paths for scripting
ghwt path-note --this # → Output path to current worktree's note
ghwt path-ci-artifacts --this # → Output path to current worktree's CI artifacts
# Open dashboard
ghwt dashboard # → Opens Obsidian dashboard
Worktree Picker:
Each worktree note includes clickable links for instant access to common actions (when configured).
Setup (optional):
Install the Shell commands Obsidian community plugin
Create a shell command in the plugin with three variables:
_subcommand_project_worktreeShell command: ghwt {{_subcommand}} {{_project}} {{_worktree}}
Copy the command ID from the plugin (shown in the list of commands)
Configure ghwt with your Obsidian vault name and command ID:
{
"obsidianVaultName": "ghwt",
"shellCommandExecuteId": "YOUR_COMMAND_ID_HERE"
}
The links automatically use the project and branch from the note's YAML frontmatter and pass them as variables to the shell command.
Edit ~/.ghwtrc.json:
{
"projectsRoot": "~/projects",
"repositoriesDir": "repositories",
"worktreesDir": "worktrees",
"vaultPath": "~/my-obsidian-vault",
"obsidianVaultName": "projects",
"shellCommandExecuteId": "abc123def456",
"syncInterval": null,
"defaultBaseBranch": "dev",
"terminalMultiplexer": "tmux",
"terminalUI": "wezterm"
}
Terminal Configuration Options:
terminalMultiplexer: "tmux" (default) or "zellij" - Which multiplexer to use for sessionsterminalUI: "wezterm" (default) or "none" - How to launch sessions
"wezterm": Launch WezTerm with multiplexer inside (modern UI)"none": Launch multiplexer directly (native zellij UI or raw tmux)Note:
ci-artifacts-config/andterminal-session-config/directories are automatically resolved relative toprojectsRootand do not need to be configured.
Place .gh-ci-artifacts.yaml, .gh-ci-artifacts.yml, or .gh-ci-artifacts.json config files in:
~/projects/ci-artifacts-config/<repo-name>/
Example for Galaxy:
~/projects/ci-artifacts-config/galaxy/.gh-ci-artifacts.yaml
When ghwt syncs or creates worktrees with failing PRs, it will automatically detect and use the config file for that repository. See gh-ci-artifacts docs for config options.
Place .ghwt-session.yaml, .ghwt-session.yml, or .ghwt-session.json config files in:
~/projects/terminal-session-config/
Per-repository config:
# ~/projects/terminal-session-config/galaxy.ghwt-session.yaml
name: galaxy
root: '{{worktree_path}}'
pre:
- '[ -f .venv/bin/activate ] && source .venv/bin/activate'
windows:
- name: client
root: client
panes:
- npm run dev
- name: server
panes:
- make run
- name: test
# Empty pane for interactive testing
Default fallback config (optional):
If a repository doesn't have a specific config, ghwt will look for _default.ghwt-session.yaml:
# ~/projects/terminal-session-config/_default.ghwt-session.yaml
# Used for any repository without its own config file
Template variables (substituted automatically):
{{worktree_path}} - Full path to worktree{{project}} - Project name (e.g., "galaxy"){{branch}} - Branch name (without slashes)Sections:
name - Session name (prefixed with project-branch)root - Session root directory (default: worktree_path)pre - Commands to run before each pane (useful for venv activation)windows - List of windows/tabs with panes and startup commandsFormat & Multiplexer Support:
ghwt create runs, it automatically detects the config and launches a session using the configured multiplexer and UIEach worktree note tracks:
Git Info
repo_url - GitHub repository URLcommits_ahead / commits_behind - Relative to base branchhas_uncommitted_changes - Boolean flaglast_commit_date - Most recent commit timestampGitHub Info (when linked to PR)
pr_state - open/closed/merged/draftpr_checks - passing/failing/pendingpr_reviews - Number of reviewspr_labels - GitHub labelsCI Artifacts (auto-fetched for failing PRs)
ci_status - complete/partial/incomplete (workflow status)ci_failed_tests - Count of test failuresci_linter_errors - Count of linter errorsci_artifacts_path - Local directory pathci_viewer_url - File URL to interactive HTML viewerci_head_sha - Commit SHA (for smart incremental fetching)ci_last_synced - Last CI artifacts sync timestampActivity Tracking
days_since_activity - Auto-calculated stalenesslast_synced - Last metadata sync timestampRequired Plugins: The interactive dashboard requires the following Obsidian community plugins to be installed:
Install these from Settings → Community plugins → Browse.
The init command creates dashboard.md with Dataview queries:
Active Work
TABLE project, branch, status, commits_ahead, pr_checks
FROM "projects"
WHERE status != "merged"
SORT created DESC
Needs Attention
TABLE project, branch, pr_checks, commits_ahead, days_since_activity
FROM "projects"
WHERE (pr_checks = "failing" OR days_since_activity > 7 OR has_uncommitted_changes = true)
SORT days_since_activity DESC
CI Failures
TABLE project, branch, ci_status, ci_failed_tests, ci_linter_errors
FROM "projects"
WHERE ci_status != null AND ci_status != "complete"
SORT ci_failed_tests DESC
Customize queries for your workflow - all metadata is available.
src/
├── cli.ts # Command router
├── commands/
│ ├── init.ts # Workspace initialization
│ ├── clone.ts # Repository cloning
│ ├── create.ts # Worktree creation
│ ├── sync.ts # Metadata sync
│ ├── rm.ts # Worktree removal
│ ├── attach.ts # Terminal session attachment
│ ├── code.ts # Open worktree in VS Code
│ ├── note.ts # Open Obsidian note
│ ├── gh.ts # Open GitHub branch/PR
│ ├── claude.ts # Open Claude in worktree
│ ├── cursor.ts # Open worktree in Cursor IDE
│ ├── ci-artifacts-download.ts # Download CI artifacts
│ ├── ci-artifacts-clean.ts # Clean CI artifacts
│ ├── path-ci-artifacts.ts # Output CI artifacts path
│ ├── path-note.ts # Output note path
│ ├── clean-sessions.ts # Kill all sessions
│ ├── lint.ts # Validate configs
│ └── dashboard.ts # Open Obsidian dashboard
└── lib/
├── git.ts # Git operations
├── github.ts # GitHub API (via gh CLI)
├── ci-artifacts.ts # gh-ci-artifacts integration
├── terminal-session.ts # Session manager dispatcher
├── terminal-session-base.ts # Base interfaces
├── terminal-session-tmux.ts # Tmux backend implementation
├── terminal-session-zellij.ts # Zellij backend implementation
├── worktree-picker.ts # Interactive worktree selector
├── worktree-list.ts # Worktree enumeration
├── obsidian.ts # Note management
├── paths.ts # Path construction utilities
└── config.ts # Configuration handling
--resume when no new commits detected~/projects/ci-artifacts/<project>/<branch|pr>/<name>/ghwt path-ci-artifacts --this outputs artifact path for scriptingterminal-session-config/<repo>.ghwt-session.yamlterminal-session-config/_default.ghwt-session.yaml. .venv/bin/activate run before pane startup{{worktree_path}}, {{project}}, {{branch}} in configsghwt rm kills session before removing worktree--this flag: Skip picker and use current worktree (requires running from within a worktree)code, note, gh, attach, claude, path-note, and path-ci-artifacts commands--continue flag reopens last conversation in that worktreeNPM packages:
commander - CLI frameworkjs-yaml - YAML/JSON config parsingexeca - Shell command executionenquirer - Interactive CLI prompts (worktree picker)External tools (must be installed):
git and gh CLI - Git and GitHub operationsclaude - Claude Code CLI (for opening Claude sessions)gh-ci-artifacts - CI artifact downloads (installed on demand via npx)wezterm - Terminal emulator (optional, for sessions with terminalUI: "wezterm")tmux - Terminal multiplexer (default, for session persistence)zellij - Terminal multiplexer (alternative, set terminalMultiplexer: "zellij" in config)npm install
npm run build
npm run dev # Watch mode
npm link # Local development
MIT
FAQs
Worktree-centered development task dashboard with Obsidian integration
We found that ghwt demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Multiple high-impact npm maintainers confirm they have been targeted in the same social engineering campaign that compromised Axios.
Security News
Axios compromise traced to social engineering, showing how attacks on maintainers can bypass controls and expose the broader software supply chain.
Security News
Node.js has paused its bug bounty program after funding ended, removing payouts for vulnerability reports but keeping its security process unchanged.