@n-seiji/nuthatch 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/LICENSE +674 -0
  2. package/README.md +86 -0
  3. package/dist/cli.js +44872 -0
  4. package/package.json +51 -0
  5. package/shell/init.zsh +46 -0
package/README.md ADDED
@@ -0,0 +1,86 @@
1
+ <p align="center">
2
+ <img src="docs/assets/logo.png" alt="nuthatch — hop between git worktrees" width="560">
3
+ </p>
4
+
5
+ <p align="center"><em>Hop between git worktrees like a nuthatch hops between trees.</em></p>
6
+
7
+ `nuthatch` is a zero-setup git worktree manager. Its single command, **`hop`**,
8
+ jumps you to the worktree of any branch — creating it on the fly when it
9
+ doesn't exist yet. Built for humans (interactive picker) and AI coding agents
10
+ (non-interactive, `--json`) alike.
11
+
12
+ ## Why
13
+
14
+ - **Zero setup** — no state files, no init. `git worktree list --porcelain` is
15
+ the single source of truth. Works in any repository immediately.
16
+ - **Convention over config** — worktrees always live at
17
+ `<parent-of-root>/_worktree/<repo>/<branch>`, so listing and path inference
18
+ are fast and predictable.
19
+ - **AI native** — every command completes non-interactively, `--json`
20
+ everywhere, paths on stdout / logs on stderr, and errors that tell you the
21
+ next step.
22
+
23
+ ## Usage
24
+
25
+ ```sh
26
+ hop # pick a worktree/branch interactively and cd into it
27
+ hop feat/foo # cd into feat/foo's worktree — created on demand
28
+ hop root # cd into the root clone
29
+ hop - # cd back to the previous worktree
30
+
31
+ hop ls [--json] # list worktrees (dirty, ahead/behind, kind)
32
+ hop rm <branch> # remove a worktree (branch is kept)
33
+ hop clean # auto-detect and remove garbage worktrees
34
+ hop root <branch> # temporarily switch the root clone (for verification)
35
+ hop root - # switch the root clone back
36
+ ```
37
+
38
+ Shell integration (auto-`cd`):
39
+
40
+ ```sh
41
+ # ~/.zshrc
42
+ eval "$(hop init zsh)"
43
+ ```
44
+
45
+ ## Install
46
+
47
+ > Not released yet — no version has been published or tagged. Once the first
48
+ > `v*` tag ships, the options below will work as described.
49
+
50
+ ```sh
51
+ npm i -g @n-seiji/nuthatch # or: bunx @n-seiji/nuthatch
52
+ mise use -g npm:@n-seiji/nuthatch # mise
53
+
54
+ # Prebuilt binary (macOS arm64/x64, Linux x64) — no Node.js required:
55
+ curl -fsSL https://raw.githubusercontent.com/n-seiji/nuthatch/main/install.sh | sh
56
+ ```
57
+
58
+ The install script places `hop` in `~/.local/bin` (override with
59
+ `HOP_INSTALL_DIR`) and always fetches the latest GitHub Release; pin a
60
+ specific version with `HOP_VERSION=vX.Y.Z`. Linux arm64 has no prebuilt
61
+ binary yet — use the npm install instead.
62
+
63
+ ## Agent skill (Claude Code / Codex plugin)
64
+
65
+ This repo doubles as a plugin marketplace that ships the
66
+ [`using-hop`](skills/using-hop/SKILL.md) skill — it teaches coding agents how
67
+ to drive `hop` non-interactively and safely.
68
+
69
+ ```sh
70
+ # Claude Code
71
+ /plugin marketplace add n-seiji/nuthatch
72
+ /plugin install hop@nuthatch
73
+
74
+ # Codex
75
+ codex plugin marketplace add n-seiji/nuthatch
76
+ codex plugin install hop
77
+ ```
78
+
79
+ ## Docs
80
+
81
+ - [docs/design.md](docs/design.md) — full design document (Japanese)
82
+ - [AGENTS.md](AGENTS.md) — guide for coding agents working on this repo
83
+
84
+ ## License
85
+
86
+ GPL-3.0 — see [LICENSE](LICENSE).