ghq-sector

You want to work across many repositories with AI agents. But how do you organize them?

• Manage directories by hand? Hard to reproduce on another machine.
• Git submodules? Even more painful.
• Just use ghq? Great for cloning — but as repos pile up, the flat layout becomes hard to navigate.

ghq-sector solves this by layering categorized workspace views on top of ghq. Your clones stay where ghq put them. On top of that, ghq-sector builds a structured working area with category directories, symlinks, and a generated VS Code .code-workspace — reproducible across machines with a single config file.

Language: English | 日本語

What it does

ghq-sector helps you:

• keep clones managed by ghq (no duplication, no submodules)
• organize repos into human-readable categories (projects, tools, docs, …)
• generate a .code-workspace file so editors and AI agents see a clean, structured workspace
• manage everything visually or as raw JSON — and reproduce it anywhere

Why this matters

A symlink-only workspace is easy to understand, but the symlinks themselves are machine-local state. They embed real filesystem paths, so copying the workspace directory to another machine is not enough when ghqRoot, usernames, or home directory layouts differ.

ghq-sector makes the config file the source of truth instead of the symlinks:

• keep one portable JSON/YAML config in version control
• regenerate the local workspace from that config on each machine
• adapt to different ghqRoot and workspaceRoot values without hand-editing every link
• detect drift with gsec doctor and repair it with gsec sync

In other words, the value is not just “create symlinks once,” but “rebuild the same categorized workspace reliably on any machine.”

Requirements

• Node.js 20+
• ghq
• gh for GitHub account-aware repo suggestions in the editor and shorthand owner flows

Windows note

ghq-sector creates symlinks in the workspace. On Windows, creating symlinks may require either:

• an elevated shell (Run as Administrator), or
• Windows Developer Mode enabled

If gsec sync or gsec apply fails with EPERM: operation not permitted, symlink ..., rerun the command from an elevated shell or enable Developer Mode first.

Install

Run without installing:

npx ghq-sector init
bunx ghq-sector init

Install globally:

npm install -g ghq-sector
gsec --help

[!NOTE] gsec is the installed shorthand command. When you run ghq-sector through npx or bunx, use ghq-sector ... instead. gsec becomes available after a local or global installation that exposes the package binaries.

Package pages:

• npm: https://www.npmjs.com/package/ghq-sector
• npmx: https://npmx.dev/package/ghq-sector

Quick start

Get started without installing:

npx ghq-sector init
# or
bunx ghq-sector init

Then open the visual config editor to manage your workspace:

gsec edit

The editor is built with visual-json — edit your config visually or as raw JSON, preview changes, and apply them in one place. See Commands for the full CLI reference.

What it creates

• ghq-sector.config.json
• category directories under workspaceRoot
• symlinks pointing to repositories managed by ghq
• optional agent skill symlinks under workspaceRoot/.agents/skills/... and workspaceRoot/.claude/skills/...
• copied resources declared in resources
• a generated VS Code .code-workspace file when enabled
• .ghq-sector/agent-skills-report.json and .md reports when agent skill sync is enabled

Portable config behavior

ghq-sector treats the config file as portable and the generated workspace as machine-local:

• ghqRoot and workspaceRoot are saved in portable form when possible, such as ~/ghq
• runtime commands resolve those paths on the current machine before cloning, syncing, previewing, or applying
• ghqRoot may be adapted to the current machine's detected ghq root
• symlinks and generated workspace files should be regenerated per machine with gsec sync or gsec apply

If you copy a workspace/config directory between macOS, Linux, or Windows environments, keep the config under version control and regenerate the local workspace instead of copying existing symlinks.

Default categories:

• projects
• tools
• docs

Included skills

This repository also includes reusable skills under skills/ for AI agents and automation workflows.

| Skill | Purpose | When to use | |---|---|---| | ghq-sector-cli | Guides an agent through the normal gsec / ghq-sector command flow. | Use when you want to set up, edit, clone, sync, doctor, or apply a ghq-sector workspace through the CLI. | | ghq-sector-manual-workspace | Explains how to build an equivalent categorized workspace manually without installing the CLI. | Use when an agent or user cannot install ghq-sector and needs mkdir/symlink/manual JSON instructions instead. |

Install these skills

Add the skills from this repository with:

npx skills add https://github.com/ts-76/ghq-sector.git

Installed skills:

• ghq-sector-cli
• ghq-sector-manual-workspace

Use ghq-sector-cli when the agent can run the CLI. Use ghq-sector-manual-workspace when the agent cannot install or execute ghq-sector and must reproduce the workspace with plain shell operations.

Commands

gsec init

Create a config file, prepare the workspace root, create category directories, and optionally open the editor immediately.

gsec init
gsec init --ghq-root ~/ghq --workspace-root ~/workspace/sector --yes

Options:

• --ghq-root <path>: set the ghq root directory
• --workspace-root <path>: set the workspace root
• --yes: skip prompts and use defaults

gsec sync

Regenerate symlinks, copy configured resources, and regenerate the .code-workspace file from the current config.

gsec sync

Sync checks the entire repository/skill link plan before changing links. It refuses destinations outside workspaceRoot, parent symlinks within the workspace, duplicate or overlapping link destinations, and existing real files/directories (including empty directories). Errors identify the protected path and reason. Use an actual directory for workspaceRoot; resolve a root symlink to its canonical directory first.

A link already pointing to the configured source is safe to reuse, including a broken link whose source is currently missing. Other links can be replaced only when their current target matches the source recorded in .ghq-sector/repo-links-manifest.json or agent-skills-manifest.json. Unexpected links remain untouched. Stale skill links are removed only when both their recorded destination and actual target match; targets and real directories/files are never recursively deleted. Old path-only skill manifests cannot prove ownership, so their stale entries are left for manual review. Move a conflicting entry or update the config, then rerun Sync/Apply. This protection applies to managed links and their metadata; configured resources and hooks retain their explicit copy/command behavior.

When a configured repo source is missing, the ownership manifest keeps the observed managed target of any existing link; it does not grant ownership to the missing desired source. Case behavior is probed inside the workspace's volume using a temporary directory that is immediately removed.

Sync acquires an exclusive .ghq-sector-sync.lock directory so managed repository/skill-link synchronization from CLI/editor operations cannot overlap. Resource copies, generated .code-workspace and AGENTS.md updates run outside this lease. A crashed operation may leave this lease; inspect it and ensure no sync is running before manually removing it. Managed link replacement and stale cleanup atomically move the old entry into a private .ghq-sector-retired-*/entry directory beside its original location, inspect the moved entry, and retain it as recovery data. These recovery directories are not automatically deleted. Review and remove them manually when no longer needed; do not recursively follow their symlinks or delete their targets. A retained relative symlink keeps its original text: restore it to its original parent directory before using it, since it may resolve differently inside the recovery directory.

If another application swaps in a real file/directory at the instant of a link update, Sync preserves the moved entry, stops, and reports its recovery path. It restores file access with an exclusive hardlink or directory access with a recovery symlink when the destination is still free; an entry newly created at the destination is left untouched. The lease coordinates ghq-sector managed-link synchronization, not arbitrary filesystem writers. Keep external writers from renaming workspace parent directories during Sync; this is not a cross-process transaction or a guarantee against a process replacing ancestor directories concurrently.

gsec apply

Apply the full config state: ensure missing repositories exist in ghq, sync the workspace, and copy the config file into the workspace root.

gsec apply

Use this when you want the CLI equivalent of the editor's Apply action.

gsec clone

Clone a repository with ghq, append it to the config, and sync the workspace.

gsec clone owner/repo
gsec clone repo --owner owner --category projects
gsec clone github.com/owner/repo --provider github.com

Accepted repository formats:

• provider/owner/name
• owner/name
• name with --owner or defaults.owner

Options:

• --category <name>: assign the repo to a category
• --owner <name>: override the owner for shorthand repo names
• --provider <name>: override the provider for shorthand repo names
• --yes: skip owner selection and use the active/default account when possible

gsec doctor

Validate environment setup, config consistency, resource paths, and workspace health.

gsec doctor

Checks include:

• ghq and gh availability
• config validity and category consistency
• resource source and target paths
• code-workspace generation status
• symlink and source-path health for existing repos

gsec edit

Start the local config editor UI. The editor is built with visual-json.

gsec edit
gsec edit --config ./ghq-sector.config.json --no-open
gsec edit --host localhost --port 4173

Options:

• --config <path>: config file path or a directory containing the config
• --host <host>: host to bind the editor server to
• --port <port>: port to bind the editor server to
• --no-open: do not open a browser automatically

The editor binds only to 127.0.0.1, ::1, or localhost; other hosts (including 0.0.0.0) are rejected. Open the exact address printed by the command. All API requests require that Host and the same Origin. A browser's same-origin fetch without Origin is accepted; explicit local clients without Origin must send X-Ghq-Sector-Request: 1. Cross-site requests are rejected, including reads. Responses also reject framing with CSP frame-ancestors 'none' and X-Frame-Options: DENY. This is a local editor, not an authenticated shared service.

Save, Preview, Apply, and draft repo proposals accept UTF-8 application/json with a 1 MiB body limit. Invalid JSON/config returns 400, oversized bodies 413, and other content types 415. Repo proposals accept {config: currentDraft, repo: optionalRepo} and return a draft without writing the config. During Save/Apply, competing API requests for that config return 409 busy; retry only after completion. An exclusive <config-file>.editor-lock lease protects editor instances across processes, including different ports; external CLI tools or manual file edits do not participate. After an abnormal exit, first confirm the recorded PID is no longer running, then remove only that stale lease file before retrying. The editor never removes an existing lease automatically.

An Apply failure returns fixed completed stage names and a failed stage, without underlying exception details. configSaved indicates whether Save completed; the failed stage may have made partial changes. Completed changes are not rolled back. Inspect the workspace and run Doctor before retrying hooks or Apply.

Config file

gsec init creates ghq-sector.config.json.

Typical fields:

• ghqRoot
• workspaceRoot
• categories
• defaults
• repos
• resources
• hooks
• editor
• agentSkills

agentSkills

Enable repository-distributed agent skill syncing when you want ghq-sector to discover skills from fixed vendor paths inside each configured repo.

{
  "agentSkills": {
    "enabled": true,
    "providers": ["agents", "claude"]
  }
}

Behavior:

• scans only <repo>/.agents/skills/*/SKILL.md and <repo>/.claude/skills/*/SKILL.md
• links selected skills into workspaceRoot/.agents/skills/<skill> and the .claude equivalent
• resolves duplicate frontmatter.name values deterministically by repos order in the config
• records skipped duplicates and parse/name warnings in workspaceRoot/.ghq-sector/agent-skills-report.json and .md
• preview in gsec edit stays read-only; actual links and reports are created only during apply/sync/clone

AI workflow angle

ghq-sector is not an autonomous agent — it is the workspace layer around your AI workflow.

AI tools work best when your repositories are easy to discover and grouped by purpose. ghq-sector gives agents a stable, categorized filesystem to operate in, while keeping humans in control of what goes where.

Support

If you run into a problem or want to request a feature, open an issue on GitHub.

License

MIT