Wraps the local GitHub CLI (gh) in agent tools for pull requests, issues, Actions runs, repository search and raw API calls, plus /gh status and /gh help slash commands and two web panels (a global repository cockpit and a per-session workspace panel).
Install
# from npm (prebuilt)
dsh plugin --profile web add dsh-github-flow
# from GitHub (first run asks for allowBuilds approval — follow the hint, retry)
dsh plugin --profile web add github:ItQianChen/dsh-github-flow
Any plugin you install runs third-party code with your own permissions — it can read your files, use your credentials, and reach the network, and tool approvals don’t sandbox it. GitHub-sourced plugins also run build scripts at install time — pnpm blocks those until you allow them, so an install can stop with ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED or ERR_PNPM_IGNORED_BUILDS; dsh prints the exact key to add under allowBuilds in your profile’s pnpm-workspace.yaml, and the install works on the next run. Allowing a build is a trust decision: only install sources you trust, and pin a commit (github:owner/repo#sha).
README
🎯 Why dsh-github-flow?
When using AI Agents for collaborative coding, developers frequently hit these fragmentation friction points:
| Collaborative Scenario | Traditional Approach (Friction-Heavy) | dsh-github-flow (Native Experience) |
|---|---|---|
| Agent PRs & Code Review | Manually push branch in browser, click through GitHub web pages to open PRs, breaking autonomous loops. | Autonomous PRs & Reviews: Just tell the Agent "Create a PR for this branch"; Agent calls github_pr to publish and review diffs automatically. |
| CI / Actions Failure Debugging | Sifting through pages of Actions logs in a browser, copying stack traces to chat for debugging. | Pinpoint Error Extraction: Tell the Agent "Why did CI fail?"; Agent calls github_run(log_failed) to grab failed step logs and patch code instantly. |
| Security & Token Management | Pasting plain-text Personal Access Tokens (PATs) in plugin configs, risking token leaks and permission sprawl. | Zero Token Exposure: Directly reuses local gh auth login credentials via native OS Keychains/Keyrings securely. |
| Context Switching Overhead | Jumping back and forth between VS Code, browser GitHub tabs, and DSH chat windows. | Immersive Dual Cockpit: Live PR status, Actions pipelines, and 3D issue matrices right inside DSH. |
| Branch Switching & Real-Time Sync | Switching branches requires hopping into a terminal, while the sidebar remains stale regarding local stage/commit changes. | Safe In-UI Branch Switching + Live Git Watch: Instant keyword filter with uncommitted dirty change guard; 800ms debounced .git watcher aligns right sidebar in milliseconds. |
| First-Screen Latency & Loading | Staring at full-screen spinners for 8~15s while waiting for heavy background gh processes. |
SWR 0ms Instant Render + Scheduled Sync: Instantly displays local persistent snapshots; features a 3-way mutually exclusive sync model (SWR, Cloud Auto-Sync with visibility pause, Manual) and standalone local Git watch. |
| Plugin Upgrades & Maintenance | Manually checking npm registry versions, complicated commands, fear of breaking configs. | Idle Silent Detection + One-Click Upgrade: Dual-registry acceleration, auto macOS/Windows adaptation, upgrade with one click. |
🚀 Installation Guide
Step 1: Prerequisites
Ensure GitHub CLI (gh) is installed and authenticated:
# Windows
winget install --id GitHub.cli
# macOS
brew install gh
# Login (one-time setup)
gh auth login
Step 2: Install into DSH
Run in your DSH environment:
# Scenario A: DSH Desktop Edition (Desktop Profile)
dsh plugin --profile desktop add dsh-github-flow
# Scenario B: DSH Web / CLI Environment (--profile is required by the official CLI; fill in your actual profile name)
dsh plugin --profile web add dsh-github-flow
💡 Notice (24-Hour Supply-Chain Security Lock Window):
DSH's bundled package manager enforces a supply-chain safety policy (minimum-release-age = 24h) by default to mitigate malicious package takeovers. Within 24 hours of a new version release, running bare-name install commands without a version suffix will automatically fall back to the preceding stable version that has matured past 24 hours. To install a newly released version immediately, append the explicit version tag:dsh plugin --profile desktop add dsh-github-flow@<latest-version>Once 24 hours have passed since release, the standard bare-name command will resolve to the latest version automatically.
🤖 Core Agent Tools: Equipping Agents with Native GitHub Powers
Consolidates scattered GitHub endpoints into 19 core domain tools (106 actions), featuring Token Budget Protection (default 24KB intelligent truncation), High-density Native Markdown Rendering (70%+ list output token reduction), OAuth Scope self-healing guidance, and Zero-argument CWD auto-binding.
0. github_task: Task-level Primitives (🆕 new in v0.7.0)
Example Agent Prompts:
- "Review PR #12, focus on security"
- "Why did CI fail?"
- "What should the next version be? Draft the notes"
The 19 domain tools above are a verb table (list / view / diff / checks / review…), while users speak in tasks. github_task wraps the three most repeated journeys into one call and returns an already-trimmed, directly actionable envelope:
summary (≤1.5KB) + facts (structured) + nextActions (concrete next steps) + cost (chars / gh calls / elapsed)
review_pr: PR metadata + head SHA + changed-file diffs (trimmed bybudget_chars) + CI tri-state + repositoryAGENTS.mdreview rules + existing line-comment count — in one shot.focus: 'security' | 'correctness' | 'perf' | 'style'only changes the wording of the conclusion, not what is fetched.- Read-only by default; writing a review back requires
write: true, confirm: true(the gate returns a confirmation payload first).
diagnose_ci: takesrun_idorpr_number→ locates failing jobs/steps → extracts failure-log anchors by framework → lists suspected files. When the log is truncated,truncated.totalUnknown = true— do not conclude "that's all the failures".prepare_release: commits since the last tag → Conventional Commits grouping → SemVer suggestion (breaking→major / feat→minor / else→patch) → release-notes draft + health check (clean tree / synced / CI green).- This primitive never tags, pushes, or creates a Release: releasing is a human decision; it only prepares "which version, what notes" and puts ready-to-run commands in
nextActions.
- This primitive never tags, pushes, or creates a Release: releasing is a human decision; it only prepares "which version, what notes" and puts ready-to-run commands in
Tier tip:
toolsets: ['core']is exactly "3 tasks instead of 15 domain tools" (github_task+github_repo+github_help, ~4,400 chars of schema — 84% smaller than full). Addgithub_pr/github_runexplicitly when you need fine-grained control — primitives are shortcuts, not the only entrance.
1. github_pr: Pull Request Lifecycle & Automated Code Review
Example Agent Prompts:
- "Check if there are any open PRs awaiting my review in this repository."
- "Create a PR for the current branch titled 'feat: add dark mode' with a brief summary of changes."
- "Review code diffs in PR #12 and provide security and refactoring suggestions."
- "Did CI checks pass for PR #8? If so, squash merge it and delete the source branch."
- Supported Actions:
list: List open PRs with author, review decisions, and CI status (state/author/limitfilters);view: Inspect PR description, metadata, and mergeability;diff: Retrieve complete code diffs (stat_onlyfor file-change overview, safely truncated against token limits);checks: Audit CI gate status (pass/fail/skip category badges, owning workflow, and detail links);create: Auto-create PRs (supports draft mode &--dry-run, supportsattach_imageslocal uploads);edit: 🆕 Edit PR title, body description, and metadata with image attachment support;comment: 🆕 Post comments and reviews to pull requests with image attachment support;checkout: 🆕 Check out PR code to a local branch so the Agent can run tests in the local workspace (requires a clean working tree; an existing branch is not reset unlessforce: true+confirm: trueare passed);status: 🆕 Inspect merge conflict status (CLEAN/CONFLICT) for the current branch's PR;review: Submit code reviews (APPROVE,REQUEST_CHANGES,COMMENT);🆕
review+comments(line-level review comments, new in v0.7.0):gh pr reviewhas no line-level flags, so this version adds acommentsarray backed byPOST /pulls/{n}/reviews, posting multiple comments anchored to specific code lines in one request. Withoutcommentsthe behaviour is byte-for-byte identical to previous versions (stillgh pr review) — no write-back by default.// github_pr(action:'review', pr_number:12, review_decision:'COMMENT', // body:'summary', comments:[{ path:'src/a.ts', line:42, body:'needs a lock here' }]) // optional: side('LEFT'|'RIGHT', default RIGHT), start_line (multi-line), commit_id (pin to a SHA)Three boundaries: ① max 50 comments per review; ②
path/bodyrequired andlinemust be a positive integer — validation reports all problems at once; ③ if a line is not on the commentable side of the diff (pure deletions, etc.) and GitHub returns 422, the comments are folded into the review body (prefixed withpath:line), retried once, and explicitly markeddegraded— no content is lost.🆕 Severity prefixes
[P0]/[P1]/[P2](new in v0.7.0): review bodies and every line comment pass through severity normalization before submission — existing prefixes are preserved, a missing one gets[P2], and[P0]/[P1]are never downgraded. The goal is to keep a pile of P2s from drowning out the P0; the plugin only adds labels, it never rewrites your judgement.🆕 Repository review rules from
AGENTS.md(new in v0.7.0):viewreadsAGENTS.mdfrom the workspace (repo root plus the nearest file in each changed file's directory, ≤8KB per file / ≤16KB total), extracts the## Code Review Rulessection (falls back to the whole file when that heading is absent), returns it asreviewRules, and renders a "Repository review rules" section at the end of the Markdown output. When noAGENTS.mdexists the key is absent entirely — "no rules" and "empty rules" stay distinguishable. Rules enter context only through tool output; nothing is injected into the system prompt.🆕 Review anchors & visible truncation (new in v0.7.0):
viewnow returnsheadRefOid/baseRefOid/changedFiles, and the Markdown branch line renders asfeat/x@a1b2c3d(branch names move, SHAs don't); when thefileslist hits gh's 100-item cap it says so explicitly ("only the first N / M listed").merge: Merge pull requests (squash/merge/rebase, optionaldelete_branch; requiresconfirm: true);ready: 🆕 Toggle Draft ↔ Ready (undo: trueconverts back to Draft — fully reversible);revert: 🆕 Create a revert commit (generates a new revert PR on the remote; requiresconfirm: true);update_branch: 🆕 Sync the latest base-branch commits into the PR branch — the self-healing action for "branch is out-of-date" CI gate failures;view_images: 🆕 Download PR discussion screenshots (body + comments;image_urlstargeting with budget-overflow resume list);attach_images(param): 🆕 Upload local images/attachments to PRs (up to 50 files/batch, symmetric with view_images, requires gh ≥ 2.99).body_file(param): 🆕 PR and comment bodies can come straight from a local markdown file (create/edit/comment/review), mutually exclusive withbody; relative paths resolve against the current workspace, the file must be valid UTF-8 (GBK/ANSI fails loudly), and bodies are capped at 65,536 characters — long bodies never enter the model context.
2. github_issue: Issue Tracking & Branch Creation
Example Agent Prompts:
- "List all open issues assigned to me."
- "Branch off a local fix branch 'fix-login-error' from Issue #42 and start working."
- "Add a comment to Issue #15 summarizing the edge cases we just discovered with screenshots."
- Supported Actions:
list: List issues with flexible filtering (state/labels/assignees);view: Inspect full issue threads, body descriptions, and assignees;create: Create new issue tickets (supportsattach_imageslocal uploads);comment: Add comments to issue threads (supportsattach_imageserror screenshot uploads);edit: Update titles,add_labels, orremove_labels;close/reopen: Manage lifecycle status (closerequiresconfirm: true);develop: 🆕 Automatically branch off a local Git branch linked to the issue;delete: 🆕 Irreversible physical deletion (requiresconfirm: true);transfer: 🆕 Move issue to another repository with 301 redirects (requiresconfirm: true);pin/unpin: 🆕 Manage pinned issues on the repository;lock/unlock: 🆕 Lock discussions with standard reasons (off_topic,resolved,spam,too_heated);status: 🆕 Retrieve a comprehensive dashboard of issues assigned to the active user;view_images: 🆕 Download screenshot attachments from issue descriptions and comments into local image blocks;attach_images(param): 🆕 Upload local file screenshots alongside issues (up to 50 local files/batch, requires gh ≥ 2.99).body_file(param): 🆕 Issue and comment bodies can come straight from a local markdown file, mutually exclusive withbody; relative paths resolve against the current workspace, the file must be valid UTF-8, and bodies are capped at 65,536 characters.
3. github_run: Actions Monitoring & Intelligent Troubleshooting
Example Agent Prompts:
- "Did the latest CI run on main fail?"
- "Extract the failed step logs from the recent failed run and debug the root cause."
- "Re-run the latest failed CI pipeline."
- Supported Actions:
list: Query workflow runs by branch or status;view: Inspect step breakdown and conclusion states;log_failed: 🔥 Troubleshooting Swiss Army Knife! Pinpoints exact failing jobs and steps, extracting only the critical failure lines;- 🆕 Framework-aware anchor extraction (new in v0.7.0): the whole log is no longer dumped at the model. Failure markers from common frameworks (pytest
FAILED, nodeAssertionError, Gopanic:, tscerror TSxxxx,npm ERR!, …) are used to slice the log into failure blocks (each with a start line and following context; adjacent markers are merged), then trimmed to a character budget; when blocks exceed the cap it states "N blocks omitted (M total)". If no known anchor matches it falls back to the last 200 lines and says why (failures are concluded at the end of a log; the head is mostly environment setup). - For this,
log_failed's output budget is raised to 2MB chars / 8MB bytes — otherwise the default 24K truncation happens before extraction and later failures never reach the context. rerun: Re-trigger failed workflows with one click;cancel: Cancel in-progress or queued runs;trigger: Manually dispatchworkflow_dispatchworkflows with custom parameters;workflow_list: 🆕 List all workflows in the repository (all: trueincludes disabled ones);workflow_view: 🆕 Inspect workflow YAML definitions and total run metrics;workflow_enable/workflow_disable: 🆕 Toggle workflow status dynamically;download: 🆕 Download build artifacts (strictly adhering to GHSA path-traversal safeguards).
4. github_repo: Metadata, Fork Sync, Clone-Free File Reads & Global Search
Example Agent Prompts:
- "Sync my fork with the upstream repository."
- "Search where 'useAuthToken' is used across this repository."
- "Read 'src/utils.ts' on the remote repository without cloning."
- "Fetch the README, and download the architecture diagrams inside it."
- Supported Actions:
view: Inspect repository metadata, default branch, Star/Fork counts, licenses, and topics;readme: 🆕 Read README text and extract all referenced image URLs, with optionalimage_urlsbatch downloads;sync: Sync fork branch with upstream (--forcehard reset supported);read_file: 🆕 Clone-free remote file reading (gh ≥ 2.95direct, older CLI versions auto-fallback to REST API);read_dir: 🆕 Clone-free remote directory enumeration with file types and sizes;search_code: Search code across GitHub repositories;search_repos: Search repositories by keywords and topics;search_issues/search_prs: Global issue and pull request queries;search_commits: Global commit message search.
5. github_release: Release Governance & Build Artifact Delivery
Example Agent Prompts:
- "Check the latest release notes and assets for this repository."
- "Draft a new v0.4.0 release using commits since the last tag."
- "Upload the local build artifact 'dsh-github-flow-0.4.0.tgz' to the latest release."
- Supported Actions:
list: Query release history;view: Inspect notes and asset manifests for a given tag;create: Publish releases (supportsgenerate_notes, drafts, prereleases, and asset attachments);notes_file(param): 🆕 Release notes can come straight from a local markdown file (replacesnotes, maps to--notes-file -), mutually exclusive withnotes; relative paths resolve against the current workspace, the file must be valid UTF-8 (release notes do not use the 65,536-character body cap — only the 4MB file-size guard applies);upload: Attach build assets to an existing release (clobber: truerequiresconfirm: true);download: Download release artifacts with glob pattern filters;delete: Delete releases (cleanup_tag: truedeletes associated Git tag; requiresconfirm: true).
6. github_secret: CI/CD Secrets & Variables Governance
Example Agent Prompts:
- "List the names of all configured Actions secrets."
- "Set a repository secret named 'DEPLOY_KEY'."
- "Read the value of plaintext variable 'NODE_ENV'."
- Supported Actions:
list: Enumerate secret or variable names (secret values are never echoed);set: Configure secrets (Security Invariant: ciphertext safely passed via stdin, never in command arguments or process tables) or variables;get: 🆕 Read variable values (available only forkind: 'variable'; secrets are cryptographically shielded by GitHub);delete: Remove secrets or variables (secret deletion requiresconfirm: true).
7. github_skill: Agent Skills Ecosystem Discovery & Local Installation 🧪 Preview
🧪 Preview dependency: built on
gh skill, which is currently in public preview (subject to change without notice); the command surface may change with gh releases. Example Agent Prompts:
- "Search GitHub for open-source Agent skills related to 'markdown'."
- "Preview and install the code review skill from 'github/awesome-copilot' into this project."
- Supported Actions:
search: Discover compliant Agent skills across open-source GitHub repositories;preview: PreviewSKILL.mdrule instructions without installing;install: Install skills locally (scope: 'project'or'user'; requiresconfirm: true);list: Inspect installed skills in the current environment;publish: 🆕 Skill Compliance Validation & Publishing Loop: Safe--dry-runinspection against agentskills.io specifications,--fixmetadata stripping, and release publishing with requiredtagandconfirm: true;update: 🆕 Batch Inspection & Sync Updates: Safe--dry-runcheck comparing local and remote tree SHAs, with--allbatch synchronization.
8. github_help: Comprehensive Mapping, Official Syntax & Self-Healing
Example Agent Prompts:
- "I am not sure which tool manages Discussions; check the mapping table for me."
- "What is the syntax for filtering GitHub search results by date?"
- "How do I debug 'authentication failed' errors from gh?"
- Supported Actions:
overview: Complete toolbox navigation and summary table (19 core tools);mapping: Official gh Command ↔ Tool Action Mapping Table, detailing exact tool calls and REST/GraphQL fallback routes;search_syntax: Date ranges, qualifiers, and boolean query syntax;troubleshooting: Self-healing recipes for authentication loss, timeouts, SOCKS5 proxy configs, and permissions;- Domain guides: In-depth usage guides for
pr,issue,run,repo,release,secret,skill,label,ruleset,cache,gist,status,agent_task,discussion,project, andcodespace; gh_command: Direct pass-through lookup of official gh manual entries (e.g.gh_command: 'ruleset').
9. github_api: Raw GitHub REST & GraphQL Escape Hatch
Example Agent Prompts:
- "Call GitHub API to fetch the current user's profile JSON."
- "Run a GraphQL query to inspect repository Discussions."
- Supported Features: Direct invocation of arbitrary GitHub REST or GraphQL endpoints using host credentials, supporting
--jqfiltering, auto-pagination (paginate: true), andraw: truemode.
10. github_label: Label System Management & Cross-Repo Cloning
Example Agent Prompts:
- "List all labels in this repository sorted by name."
- "Create a label 'priority/p0' with color #d73a4a for critical bugs."
- "Clone the label system from 'cli/cli' repository into our new repository."
- "Delete the deprecated 'invalid' label."
- Supported Actions:
list: List repository labels (supportssearchregex/keyword,sort: 'created' | 'name', andorder: 'asc' | 'desc');create: Create a new label (hex color normalization, optionalforce: trueto update existing);edit: Update label color, description, or rename vianew_name;delete: Safe deletion (affects associated issues/PRs; requiresconfirm: trueconfirmation, injects--yes);clone: 🆕 One-click cross-repo label cloning: Copy all labels from a source repository (source_repo) into the target repository (supportsforce: trueto overwrite conflicts).
11. github_ruleset: Branch Protection Rules & Policy Diagnosis
Example Agent Prompts:
- "Why can't I merge this PR? Check all applicable rules for this branch."
- "Verify whether branch master requires CI status checks or 2 approvals."
- "List all repository rulesets."
- Supported Actions:
check: 🔥 Core PR Merge Blocker Diagnosis! View all protective rules governing a branch (e.g. required approvals, required status checks, linear history, force-push denial), complementinggithub_pr(action: 'checks')with authoritative policy perspective;list: List rulesets for repository or organization (--organd--no-parentssupport);view: Inspect ruleset configuration and target branches (requiresruleset_id).
12. github_cache: Actions Build Cache Auditing & Safe Cleanup
Example Agent Prompts:
- "How much cache space is consumed by GitHub Actions in this repository?"
- "List build caches sorted by size in descending order."
- "Purge all build caches in this repository."
- Supported Actions:
list: Audit Actions caches with human-readable size formatting (KB/MB/GB), key prefix and ref filtering, and size/access sorting;delete: Precise 3-way cleanup (bycache_id, bykey, or purge everything viaall: true; all three paths requireconfirm: true; purge additionally injects--succeed-on-no-cachesfor idempotency).
13. github_gist: Code Snippets & Diagnostics Archiving
Example Agent Prompts:
- "Publish this diagnostic error log as a Secret Gist and share the link."
- "List all gists on my user account."
- "Inspect the contents of Gist '5b0e0062eb8e9654adad7bb1d81cc75f'."
- Supported Actions:
list: List user gists (structured TSV parser, supportspublic/secret/filteroptions);view: View raw code contents of a gist (optionalfilenametargeting, requiresgist_id);create: Create gists fromcontentstring (streamed via safe stdin pipeline) or localfiles, defaults to Secret mode with explicit unlisted security warnings;edit: Update descriptions or files in a gist;delete: Permanently delete a gist (requiresconfirm: trueand--yes).
14. github_status: Cross-Repository Todo & Runtime Health Dashboard
Example Agent Prompts:
- "What tasks and pull requests need my attention on GitHub today?"
- "Check recent @mentions and activity across all repositories I follow."
- "Audit the runtime health score and degradation rate report of our GitHub tools."
- Supported Actions:
view: Account-level global status cockpit (default), aggregating Assigned Issues, Assigned PRs, Review Requests, Mentions, and Repository Activity across all subscribed repositories without needing repository context; supports-oorg filtering and-enoise repository exclusion;health: 🆕 Toolchain Runtime Health & Degradation Audit Report: Powered by Cordistools/resultevent telemetry, audits total calls, success rates, comprehensive health score (0-100), API degradation rates, and actionable self-healing upgrade suggestions across all 19 tools.
15. github_agent_task: Cloud Coding Agent Session Governance 🧪 Preview
🧪 Preview dependency: built on
gh agent-task, which is currently in public preview (subject to change without notice); the command surface may change with gh releases. Example Agent Prompts:
- "List all GitHub Copilot Coding Agent task sessions assigned under my account."
- "View task 'e2fa49d2' details and fetch its execution logs."
- "Dispatch a task to the cloud Agent: 'Refactor network layer with retry support', based on branch develop."
- Supported Actions:
list: List agent tasks (supports-L/--limit;gh agent-task listdoes not accept-R/--repo, which has no effect on this action);view: View task session details and logs (supports--log, strictly requirestask_idto prevent TTY hangs);create: Create and dispatch a cloud agent coding task (supports-b/--baseand-a/--custom-agent).
16. github_discussion: Team Discussions & Open-Source RFC Loop 🧪 Preview
🧪 Preview dependency: built on
gh discussion, which is currently in public preview (subject to change without notice); the command surface may change with gh releases. Example Agent Prompts:
- "List open discussions in category 'Ideas' for this repository."
- "View discussion #101 body and comment thread."
- "Start a discussion under 'RFC': 'Proposal on telemetry observability'."
- "Post a reply comment to discussion #101."
- Supported Actions:
list: Query discussions (supports-c/--category,-s/--state,--labels, and-S/--search);view: Read discussion body and replies (supports--comments, requiresdiscussion_number);create: Start a discussion (requirescategory,title, andbody);edit: Update discussion title or body;comment: Post a comment reply to an existing discussion.
17. github_project: Projects v2 Board & Item Planning
Example Agent Prompts:
- "List all Projects v2 boards under my account."
- "View items in project board #1 with filter query 'is:open'."
- "Add Issue 'https://github.com/owner/repo/issues/10' to project board #1."
- "Create a draft issue item in project #1 titled 'Review unit test coverage'."
- Supported Actions:
list: List user or organization projects (defaultowner: '@me', natively handles--format json);view: Inspect project metadata, visibility, description, and README;item-list: Inspect board items (supports Projects query filter syntax--query, e.g.,is:open assignee:@me);item-add: Associate existing Issue/PR URLs to a project board;item-create: Create draft issue items;item-delete: Remove items from board (guarded by requiredconfirm: true);- 🔑 Scope Self-Healing: Automatically renders a single-line self-healing command card (
gh auth refresh -s read:project) when permissions are missing.
18. github_codespace: Cloud Remote Development Environment (MVP)
Example Agent Prompts:
- "Check which cloud Codespace environments are currently running."
- "Inspect instance specs and idle timeout for 'fuzzy-spoon-69vj'."
- "Stop 'fuzzy-spoon-69vj' to avoid billable core-hour consumption."
- "Permanently delete an unused temporary Codespace."
- Supported Actions:
list: List Codespaces under current user or organization;view: Inspect environment specs, DevContainer path, and status (requirescodespacename);stop: Stop running instances to halt billing immediately;delete: Safely delete instances (requiresconfirm: true, passes-ffor non-interactive execution);- 🔑 Scope Self-Healing: Automatically renders a single-line self-healing command card (
gh auth refresh -h github.com -s codespace) when missing required scopes.
🖥️ Web UI Cockpit & Right Sidebar Workspace Panel
dsh-github-flow delivers native visual controls alongside its Agent toolset:
1. Global Cockpit (Main Dashboard)
Click the Octocat icon in DSH's left navigation bar to open the full-screen cockpit:
- ⚡ 0ms Instant Render (SWR Persistent Cache): Powered by local snapshot persistence; enjoy instant dashboard loading;
- 📦 Live Freshness Status Pill: Transparently communicates data freshness right next to the title (
[📦 Local Snapshot (21m ago)]➔[⏳ Syncing in background...]➔[✅ Up to date (15:30)]➔[⚠️ Network failed, offline snapshot displayed]); - Account-Wide Overview: Live view of all cloud repositories, default branches, and star counts;
- Local Workspace Matrix: Automatically detects open projects and bridges local directories with remote repos;
- 3D Issue Governance Matrix: Categorizes issues into "📥 User Reported", "🎯 Assigned to Me", and "✍️ Created by Me" with responsive pill filters;
- Update Notification Banner: Smoothly glides down when an update is available with one-click automated upgrade;
- 🔀 PR Review Workbench: Click any PR to review author, branch flow, CI/review status, Markdown description, comment timeline, and the changed-file list with high-fidelity unified diffs — all without leaving DSH (diffs are sliced per file in memory, so switching files is instant);
- 📝 Issue Online Viewer: Click any Issue to read the full discussion — body and comments rendered as Markdown, long content collapsed, GitHub-hidden (SPAM) comments explicitly flagged, with label chips, assignees, milestone, sub-issue progress, and linked PRs.
- ⚡ Actions Run Online Detail: Click any run card in the sidebar to inspect workflow / branch / commit / trigger event / duration plus the full job & step tree (per-step conclusion and timing, failed steps highlighted, first failed job expanded by default). On failure, pull an anchored log excerpt on demand (up to 3 failed jobs per click, 90s server-side batch budget, 100s client-side abort), while
GitHub ↗still opens the complete log on GitHub.
2. Session Right Sidebar Panel (Workspace Drawer)
Located in the right drawer of every chat workspace, seamlessly bridging your local Git workspace with remote GitHub repositories:
- Context Auto-Binding: Automatically locks onto the active Git repository of the current session;
- Branch Viewing & Safe In-UI Switching (Branch Selector):
- Visual branch dropdown directly inside the repository card;
- Built with official Git diamond vector icons (
#1296dbSVG); - Pre-fetched with the overview payload for an instant 0ms dropdown opening, featuring live keyword search across local and remote branches;
- Dirty File Guard: Strict pre-flight checks block switching if there are uncommitted changes, protecting work from destructive overwrites;
- Freshness Pill Alignment: Compact indicator
[📦 Local Snapshot (2m ago)]with live[🔄 Refresh]button; - Quick Action Grid: Open repo in browser, jump to Issues/PRs, create PRs with one click;
- Five Mutually Exclusive Tabs: Compact tabbed navigation directly below the quick action grid:
- Git Records (
Git) (Default tab):- Branch & Remote Sync: Real-time branch indicator (e.g.
master) with tracking sync status (✓ Up to dateor↑N to push/↓N to pull); - Three-Section Commit View: Unpushed commits (ahead of remote), unpulled commits (behind remote), and recent commit history;
- 15 commits displayed by default, with infinite scroll loading when scrolling to the bottom (with live
15 / 74progress counter and click trigger); - Latest Release badge (
🏷️ v0.4.0) anchored in the top right with hover details and direct release link; - Commit Detail Modal: Click any commit row to open a clean modal dialog centered within the right sidebar, featuring smooth vertical scrolling, full 40-char SHA, author email, date, multi-line commit message body, and file diff stat table (
--stat), pure local 0ms instant display; - File Diff Preview Modal: Click a file stat row inside the commit detail, or any file in the uncommitted list, to open that file's Unified Diff in a modal (the whole patch is split per file on
diff --gitboundaries, renamed paths normalized, body lines starting with---/+++are not mistaken for file headers, oversized patches truncated on file boundaries); the modal stacks above the commit detail (Esc closes one layer at a time) and offers copy-source plus "Open in DSH";
- Branch & Remote Sync: Real-time branch indicator (e.g.
- Uncommitted Changes (
📁 Uncommitted (N)): Full-width list of uncommitted files with color-coded status codes (??untracked,Mmodified,Ddeleted,Rrenamed) and change counts; - Pull Requests (
🔀 PR (N)): Shows all PRs (merged/closed included, default "All"), with status pillsAll / 🟢 Open / 🟣 Merged / ⚪ Closedshowing per-state counts; 3-state CI rollup (✅ CI Passed/❌ CI Failed/⏳ CI Pending), merge conflict detection, review decisions (✔ Approved/✋ Changes Requested/👀 Review Required), Draft pills, and humanized timestamps; click a card to open the in-app PR review workbench, whileGitHub ↗still jumps to the browser; - Workspace Issues (
📋 Issues (N)): Shows all issues (closed included, default "All"), with status pillsAll / 🟢 Open / ⚪ Closed; click a card to open the in-app Issue viewer (Markdown body / comment timeline / labels & milestone, Esc to close), whileGitHub ↗still jumps to the browser; - Actions Pipeline (
⚡ Actions (N)): Real-time CI workflow status tracking with trigger event badges (push/schedule/manual/PR) and relative time; click a card to open the in-app run detail — job / step tree with failed steps highlighted (first failed job expanded), plus an on-demand anchored log excerpt (up to 3 failed jobs, 90s batch budget), whileGitHub ↗still opens the full log on GitHub;
- Git Records (
- ⚙️ Full Settings Access: Dedicated settings button reusing the same settings modal as the cockpit (all four sections: Sync / Proxy / Update Source / About) — no need to switch back to the main page.
3. Help & Playbook Modal
Click [📖 Help] in the top right of the Cockpit (or the ❓ button in the right sidebar) to open the 920px immersive manual; press Esc or click the backdrop to close. Five sections:
- 🚀 3-Minute Quickstart: login check → workspace binding → first Agent instruction, plus a capability overview (19 tools / 106 business actions / 2 workbenches);
- 🤖 Agent Prompt Playbook: 7 high-frequency scenarios (open a PR, CI triage, daily standup, diff review, screenshot triage, bulk label governance, RFC discussion), each with one-click prompt copy;
- 🖥️ UI Walkthrough: per-tab documentation for the 4-tab Cockpit and the 5-tab right sidebar, plus shared modal interaction habits;
- 🧰 19-Tool Reference: all tools and actions grouped into daily development / delivery & config / ecosystem & collaboration / escape hatches, with a
/ghcommand cheat sheet; - 🔑 Troubleshooting: login, missing scopes, the 24h supply-chain protection window, proxy flapping, empty lists, and why a DSH restart is needed.
The same knowledge is exposed to Agents via the
github_helptool — both sides are asserted against the source tree by phase33, so docs drifting from code fails the test suite.
4. Settings Center (Settings Modal)
Click [⚙️ Settings] in the top right of the Cockpit (or the ⚙️ button in the right sidebar) to open the sectioned settings modal:
🔄 Data Sync Section — tune data fetching rhythm and perception sensitivity:
- Three Mutually Exclusive Data Refresh Strategies:
- ⚡ Instant Render (SWR, Default): Instantly displays local cache (0ms), then silently syncs the latest state in the background on initial load;
- ☁️ Cloud Scheduled Auto-Sync (SWR + Polling): Instantly renders local cache and syncs once on mount, then counts down cyclically (5/10/30/60 minutes selectable; features automatic window visibility pause to prevent API quota drain in background tabs);
- 📋 Manual Only (Energy Saver): Browse local cache only; zero background
ghprocesses triggered; click[🔄 Refresh]whenever you want updates.
- Advanced Automation & Status Perception:
- 📁 Local Git Real-Time Watch (Right Sidebar Only, Enabled by Default): Monitors
.git/HEADand.git/indexmetadata directly; staging, commit, and branch changes synchronize to the sidebar within milliseconds with an 800ms debounce, consuming zero external network quota; omitted from the main cockpit to preserve lightweight performance.
- 📁 Local Git Real-Time Watch (Right Sidebar Only, Enabled by Default): Monitors
- Visual Cache Management: Real-time snapshot size and timestamp visibility with one-click
[🗑️ Clear Cache].
🌐 Network Proxy Section — route all plugin traffic through your proxy:
- Global Scope: Once configured, the cockpit, right-sidebar panel, all 19 Agent tool invocations, and one-click upgrades route through the proxy;
- Protocol Support:
http:///https:///socks5:///socks5h://(socks5hdelegates DNS resolution to the proxy for stronger pollution resistance); [🧪 Test Connectivity]: One-click latency probe against the GitHub API through the current proxy;- Instant Effect: Persisted to
~/.dsh/data/dsh-github-flow/proxy.json(auto-restored on DSH restart) — no restart, no plugin reload; - NO_PROXY Exclusions:
localhostand127.0.0.1are forcibly included.
⬆️ Update Source Section — choose which npm registry checks for new versions:
- Three options: 🌍 npm official registry (default — new releases visible immediately) / 🇨🇳 npmmirror (fast in China; minutes-level sync delay) / ⛔ No update checks (only silences the upgrade banner;
/gh upgradeand one-click upgrade remain available); - Strict single-source: the selected source is never silently swapped — probe failures are reported honestly;
- Verify on save: switching sources immediately probes the new registry and shows the latest version.
ℹ️ About Section — plugin identity & project info:
- Current running version, project description, GitHub repository, npm package page, and MIT license;
- Star card — if the plugin helps your workflow, a Star on the repo powers continued iteration.
🏷️ Plugin Identity Badge: Panel titles (cockpit & right sidebar) carry a small "Plugin" badge, clearly marking the UI as provided by the third-party plugin
dsh-github-flow(not a DSH / GitHub official feature). Click the badge to open the About page.
| 🔄 Data Sync Section | 🌐 Network Proxy Section |
|---|---|
![]() |
![]() |
⚡ Smart Upgrades & Cross-Platform Engine
Never miss an update! Built-in industrial-grade update management:
- Parallel Detection, Zero gh-Dependency:
- Update checks fire in parallel with the gh environment chain on mount — never serialized behind gh overviews; gh failures never block upgrade banners;
- Server-side
inFlightPromisemerging + 24h cache keeps multi-panel mounting storm-free.
- Selectable Update Source (see the "⬆️ Update Source" settings section):
- Defaults to the npm official registry (new releases visible immediately), or switch to npmmirror (minutes-level sync delay);
- Auto checks can be disabled entirely.
- Cross-Platform One-Click Upgrade:
- Click to Upgrade: Click
[⚡ Upgrade]in the UI to update in the background; - Auto OS Adaptation: Differentiates macOS and Windows; auto-injects Homebrew PATH variables on macOS GUI launches;
- Source Protection: Automatically aborts npm overwrites when running in local Git linked development mode (
link:); - Restart Guidance: Clearly notifies users to restart DSH service to reload backend tools, with instant web refresh options.
- Click to Upgrade: Click
⏱️ SWR Instant Render & Sync Rhythm Control
Why did the Global Cockpit take several seconds to load in earlier releases? Because it concurrently executes a dozen gh processes scanning multiple repositories and workspaces. This plugin integrates the Stale-While-Revalidate (SWR) caching pattern, putting total control back in your hands:
Initial Mount (0ms) ──────────> Instantly render local persistent snapshot
│
├── SWR Mode: Idle 300ms delay, silently revalidate in background once
├── Cloud Scheduled Sync: Starts countdown after initial sync (5/10/30/60m pause on hide)
└── Manual Mode: Browse offline snapshot, only fetch on click [🔄 Refresh]
Strategy Comparison & Recommendations:
| Sync Strategy | Mechanism | Recommended Use Case |
|---|---|---|
| ⚡ Instant Render (SWR, Default) | 0ms instantaneous mount from local cache, silently revalidating in background once on mount — however stale the snapshot, opening the panel self-heals to fresh data. | Recommended for all developers. Eliminates spinner freezes, delivering seamless UX. |
| ☁️ Cloud Scheduled Auto-Sync (SWR + Polling) | Instantly renders local cache and revalidates on mount, then starts a recurring timer (5/10/30/60m); features visibility-change pause to prevent background API quota drain. | Active developers managing multiple repositories, PR workflows, and team issues. |
| 📋 Manual Only (Energy Saver) | Browse local cache only; zero automated background gh processes. |
Battery-powered laptops, low-spec hardware, or metered networks. Zero background waste. |
- Offline Resilience (Fail-Safe): Even when disconnected or hitting network timeouts, your dashboard preserves the complete snapshot for searching, navigation, and review, paired with prominent offline warning banners and toasts—zero blank screens or crash popups!
💬 Human Slash Commands
Enter in any DSH chat window:
/gh status: Diagnostics for GitHub CLI auth status, scopes, active workspace repository, plugin version, and runtime toolchain telemetry (health score & degradation rates);/gh upgrade: Check the latest npm release and output platform-tailored upgrade instructions (macOS / Windows / Linux);/gh help: View help documentation and example Agent dialogue recipes.
⚙️ Plugin Configuration (cordis.yml)
Fine-tune options via DSH config:
- id: github-flow
name: dsh-github-flow
config:
ghPath: 'gh' # GitHub CLI executable path (default 'gh')
defaultTimeoutMs: 30000 # Command execution timeout in ms (default 30s)
maxOutputChars: 24000 # Max character output threshold (Token overflow protection)
maxOutputBytes: 96000 # Hard UTF-8 byte output cap, defaults to maxOutputChars * 4
defaultListLimit: 20 # Default query limit for list operations across PR/Issue/Run/Release/Skill
cacheTtlMs: 15000 # Repository overview cache TTL in ms (default 15s)
checkUpdate: true # Enable automated version checks (default true)
agentEnvInjection: true # Inject AI_AGENT=dsh for gh CLI recognition (default true)
updateCheckIntervalMs: 86400000 # Update check interval in ms (default 24h)
registryUrl: '' # Custom npm registry (defaults to Update Source setting)
proxyUrl: '' # Default proxy URL (overridden by UI settings)
toolsets: ['core'] # Tool tier: unset/full = all 19; core=3 / ci=7 / maintain=8; bare tool names allowed
read_only: true # Read-only tier: write actions pruned from the schema at registration; github_api not registered
toolsetscontrols which tools get registered to the model, not a runtime permission check: unset = all 19 resident (~27,000 chars of schema),core= 3 (~4,400 chars, 84% smaller). A misspelled tier name logs aconsole.warnlisting the available tiers instead of silently dropping every tool.read_onlyis a hard semantic enforced in two layers: (1) write actions are removed from the argumentenumat registration time (invisible at the schema layer); (2) the execution entry rejects them again — this plugin ships hand-rolled descriptors, so the host does not validate arguments on our behalf; a pruned action is refused before it ever reachesgh, even withconfirm: true.github_apiaccepts any endpoint and method, so it cannot be degraded — it is simply not registered. Boundary note:github_helpoutput is documentation, so it still lists every capability (including write usage) in read-only mode. It is not an executable contract — what actually blocks writes is the two layers above.
Config is validated by a Schemastery schema: a wrong type (e.g.
maxOutputChars: '24000'as a string) now fails loudly instead of silently falling back to the default.maxOutputChars/defaultTimeoutMs/defaultListLimitare volatile fields — editing only these hot-commits the new values into the running instance without reloading the plugin; editing any other field (includingcheckUpdate) still triggers a plugin reload.
🔌 Cordis Ecosystem Service (ctx.github)
Exports a standard Cordis service ctx.github for other DSH plugins:
import type { Context } from '@deepseek-ai/cordis';
// Optional but recommended: load the declaration merge shipped with this package
// so `ctx.github` gets full types and autocompletion.
import type {} from 'dsh-github-flow/host';
export const inject = ['github'];
export async function apply(ctx: Context) {
const auth = await ctx.github.checkAuth();
const repo = await ctx.github.getRepoMetadata();
const prs = await ctx.github.run(['pr', 'list', '--json', 'number,title']);
}
🛠️ Local Development & Debugging
When contributing or customizing the plugin locally, follow this workflow:
1. Link Plugin to DSH (Directory Junction)
By default, DSH profiles copy local file: dependencies as static snapshots and may ignore build lifecycle scripts. To achieve instant reflection of your builds, use a native Directory Junction (Windows):
# Windows PowerShell
New-Item -I
…
Links
More in this category
zhu1090093659/dsh-web#packages/dsh-git-graph★ 10494
Git branch selector and Git graph for the dsh web GUI: switch branches and explore branch-lane and commit history from the conversation header. Retired by the author in favour of the official workspace-changes plugin: the published npm package stays installable but is no longer developed.
Akimiya-z/codex-guard#dsh★ 132
Pre-submit pull-request hygiene checks inside DeepSeek Harness: scans the current diff for TODO leftovers, hardcoded secrets, and non-conventional commit subjects.
xbzbing/dsh-git-panel★ 57
IDE-style Git panel in the DSH Web GUI: a resident tab with a three-column overview (branch/tag list, searchable commit-history graph, commit detail with changed-file tree and message) and a changes page (stats bar, uncommitted list with per-file stage/unstage/discard, commit box with amend); side-by-side diffs carry lazy highlight.js syntax highlighting, on-demand between-hunk context expansion and word-level intra-line emphasis, with image files shown as before/after panes; plus a zsh-style branch marker in the input bar. Every git command runs as an argv array through the host subprocess service, cwd locked to the repo root.
Cerbur/clutch-dsh#clutch-dsh-worktree★ 46
Adds a Worktree view to DSH Web UI that groups Sessions by Git worktree while keeping DSH as the source of truth.
DamonKoy/dsh-web-ui#dsh-git-graph★ 33
Git branch selector and Git graph in the conversation header of the dsh web GUI.
Lenonss/DSH_VsCodeMode★ 33
VSCode-style editing experience for DeepSeek Harness: a Monaco-based central file editor (tabs, Ctrl+P quick open, status bar) and interactive diff review of agent edit/write results with per-change Keep/Undo, rollback and archiving, persisted across restarts.


Community comments
Comments are public GitHub Discussions. Loading them connects to GitHub and Giscus; a GitHub account is required to post.