🛠️ nanokit - minimal development environment


                                                   88         88
                                                   88         ""    ,d
                                                   88               88
8b,dPPYba,   ,adPPYYba,  8b,dPPYba,    ,adPPYba,   88   ,d8   88  MM88MMM
88P'   `"8a  ""     `Y8  88P'   `"8a  a8"     "8a  88 ,a8"    88    88
88       88  ,adPPPPP88  88       88  8b       d8  8888[      88    88
88       88  88,    ,88  88       88  "8a,   ,a8"  88`"Yba,   88    88,
88       88  `"8bbdP"Y8  88       88   `"YbbdP"'   88   `Y8a  88    "Y888

🛠️ nanokit - minimal development environment

Platform Powered by Pixi License: MIT

⚡ A lightweight, fast, and efficient cross-platform development setup for Linux (x86/arm), OSX
✨ No sudo required - Everything installs to $HOME/.pixi, completely user-local
🪄 Pixi as a shell tool manager - Keep your tools up-to-date by declarative management
🦀 dotter as a simple dotfile manager that links / unlinks dotfiles in nanokit
🐚 zsh 🎩 sheldon 🚀 starship - Modern shell experience with plugin management

⚙️ Setup - All you need is pixi

Step 1: Install pixi

Install pixi following the official installation guide:

curl -fsSL https://pixi.sh/install.sh | sh

If your system doesn't have curl, you can use wget:

wget -qO- https://pixi.sh/install.sh | sh

Warning

Now restart your terminal or shell to make the installation effective.

Step 2: Clone this repository

Install GitHub CLI (recommended) or git:

export PATH="${HOME}/.pixi/bin/:$PATH"
pixi global install gh
# or
pixi global install git

Using 🔀 git:

git clone https://github.com/DenDen047/nanokit.git
cd nanokit

Using gh (recommended - includes SSH key setup):

gh auth login

# Where do you use GitHub? → GitHub.com
# What is your preferred protocol? → SSH
# Generate a new SSH key? → Yes
# How would you like to authenticate? → Login with a web browser

gh repo clone DenDen047/nanokit
cd nanokit

Using 🔀 git:

git clone https://github.com/DenDen047/nanokit.git
cd nanokit

Step 3-a: nanokit install (recommended for new environment)

./nanokit install

That's all you need to get started!

Caution

nanokit configures zsh as the default shell for the terminal emulator (e.g. tmux) and use it only for interactive sessions. We recommend using a system-managed shell such as /usr/bin/zsh (or /bin/bash) as the login shell.

Pixi installs zsh in a user-space environment and locks it together with its runtime dependencies (e.g. ncurses, libgcc; see pixi global tree --environment zsh).

If this environment fails, using it as a login shell can prevent system login (e.g. via SSH or WSL). https://tim.siosm.fr/blog/2023/12/22/dont-change-defaut-login-shell/

Step 3-b: Manual Installation (recommended for existing environment)

If you prefer more control over the installation process or are setting up on an existing machine with custom configurations

Install dotter

pixi global install dotter-rs

Symlink configuration files

Check what will be symlinked (dry run):

dotter -d       # dry run: confirm what happens

Deploy the symlinks:

dotter deploy

Install utility tools

Install all necessary tools defined in the global configuration:

pixi global sync

Start your 🐚 zsh

Launch zsh shell or tmux:

zsh

tmux

Everything is setup automatically via 🎩 sheldon.

🔄 Reset All Environment

dotter undeploy -d
dotter undeploy
touch ~/.pixi/manifests/pixi-global.toml
pixi global sync

Step 4: Install fonts required for 🚀 starship (optional)

For local terminals, installing fonts is recommended. Fonts will be installed to $HOME/.local/fonts.

🐧 Linux	🍎 Mac OS	🪟 Windows Terminal
`./setup_fonts.sh`	`brew install --cask font-hack-nerd-font`	`choco install nerd-fonts-hack` Note: Requires administrator privileges

See Starship Presets for more customization options.

🎨 Customization

🛠️ Global Tools

The following tools are available through pixi-global.toml:

	Tool	Description	Exposed Command	GitHub
🔀	git	Version control system	`git`, `git-cvsserver`, `git-receive-pack`, `git-shell`, `git-upload-archive`, `git-upload-pack`, `gitk`, `scalar`	git/git
	gh	GitHub CLI	`gh`	cli/cli
🔀	git-lfs	Version control system	`git-lfs`	git/git
🔀	tig	TUI client for Git	`tig`	jonas/tig
🐚	zsh	Z shell	`zsh`, `zsh-5.9`	zsh-users/zsh
🎩	sheldon	Fast and configurable shell plugin manager	`sheldon`	rossmacarthur/sheldon
🚀	starship	Minimal, beautifl prompt for any shell	`starship`	starship/starship
🦀	dotter-rs	Dotfile manager	`dotter`	SuperCuber/dotter
🔐	sshs	TUI client for ssh	`sshs`	quantumsheep/sshs
📊	htop	Interactive process viewer	`htop`	htop-dev/htop
📊	bottom	System monitor	`btm`	ClementTsang/bottom
🔎	fzf	Fuzzy finder	`fzf`	junegunn/fzf
📁	tree	Directory tree display	`tree`	Old-Man-Programmer/tree
📁	go-ghq	Git repository manager	`ghq`	x-motemen/ghq
🌲	gwq	Git worktree manager	`gwq`	d-kuro/gwq
🌀	zoxide	Smart directory jumper	`zoxide`	ajeetdsouza/zoxide
🛠️	make	Build automation tool	`make`	mirror/make
📋	xsel	X11 clipboard manipulation	`xsel`	kfish/xsel
🗄️	pueue	Local job queue manager	`pueue`, `pueued`	Nukesor/pueue
🪟	tmux	Terminal multiplexer	`tmux`	tmux/tmux
💽	dua-cli	Disk usage analyzer	`dua`	Byron/dua-cli
💽	diskonaut	Disk space navigator	`diskonaut`	imsnif/diskonaut
🦇	bat	Better cat with syntax highlighting	`bat`	sharkdp/bat
📂	lsdeluxe	Modern ls replacement	`lsd`	lsd-rs/lsd
⬢	fnm	Fast Node Manager (Node/npm/npx via `fnm env`)	`fnm`	Schniz/fnm
⚙️	jq	Command-line JSON processor	`jq`	jqlang/jq
🌍	xh	Friendly and fast tool for sending HTTP requests	`xh`	ducaale/xh
☁️	rclone	rsync for cloud storage	`rclone`	rclone/rclone
☁️	aws	CLI for AWS	`aws` `aws_completer`	aws/aws-cli
📝	neovim	Neovim with Node.js, Lua, Python support	`nvim`	neovim/neovim
📝	helix	A post-modern modal text editor	`hx`	helix-editor/helix
🌱	direnv	Per-directory environment variables	`direnv`	direnv/direnv
🍞	bun	Fast JavaScript runtime, bundler, test runner	`bun`	oven-sh/bun
🎬	ffmpeg	Audio/video processing	`ffmpeg`, `ffprobe`	FFmpeg/FFmpeg
🗜️	p7zip	7-Zip archive utility	`7z`, `7za`, `7zr`	p7zip-project/p7zip
👀	watch	Execute a program periodically	`watch`	procps-ng/procps
📹	t-rec	Terminal recorder (animated GIFs)	`t-rec`	sassman/t-rec-rs
🖼️	imagemagick	Image manipulation toolkit	`magick`, `convert`, `mogrify`, `identify`, `composite`, …	ImageMagick/ImageMagick

Add your favorite tools with:

pixi search <package-name>
pixi global install <package-name>  # e.g. pixi global install python=3.13

This will automatically update the pixi-global.toml configuration.

pixi global update

automatically upgrade all tools except for version-pinned packages.

see Pixi Global: Declarative Tool Installation for details.

🚀 Starship Settings

Customize your prompt by editing starship.toml. See Starship Themes.

For detailed configuration options, see the Starship documentation.

🎩 Zsh Plugins

Manage plugins by editing zshrc and sheldon.toml.

For more plugin management options, see the Sheldon documentation.

🦀 Dotfiles Management

Manage symlinks for dotfiles by editing .dotter/global.toml.

For detailed configuration options, see the dotter documentation.

🚀 ghq + 🌲 gwq + 🌀 zoxide = ❤️

The combination of ghq and zoxide creates a magical workflow for repository management:

📦 Repository Management with ghq

ghq provides a clean way to organize remote repository clones. When you run:

ghq get {repo-url}

It automatically clones the repository to a well-structured directory hierarchy under ~/ghq, regardless of your current location. For example:

ghq get https://github.com/user/project
# Creates: ~/ghq/github.com/user/project

🌀 Smart Navigation with zoxide

Once you cd into any directory, zoxide remembers that location. You can then use:

zi  # Interactive fuzzy finder for visited directories
z <partial-name>  # Jump to directory matching the pattern

No more cd ../../../project - just zi and you're there! 🎯

🌲 Worktree Management with gwq

gwq is to branches what ghq is to repositories — a structured, ghq-style manager for git worktree. Instead of juggling git worktree add ../some-path by hand, gwq lays worktrees out under $GHQ_ROOT using the naming template configured in gwq.toml:

$GHQ_ROOT/github.com/{owner}/{repo}.{branch}

Common commands:

gwq add <branch>     # create a worktree for <branch> (auto-cd into it)
gwq list             # list avaialable worktrees
gwq remove           # prune a worktree

With auto_cd_on_add = true (already set in gwq.toml) and the shell integration sourced in zshrc (source <(gwq completion zsh)), gwq add drops you straight inside the new worktree, 🌀 zoxide quietly memorizes the path along the way. So next time, just zi and you're back in the worktree you wanted. 🎯

🖥️ Tmux Key Bindings

The tmux configuration uses Ctrl+a as the prefix key (instead of the default Ctrl+b). Here are the essential key bindings:

Basic Commands

Key Binding	Description
`Ctrl+a` then `?`	Show help and all key bindings
`Ctrl+a` then `r`	Reload tmux configuration

Window Management

Key Binding	Description
`Ctrl+a` then `c`	Create new window (in current directory)
`Ctrl+a` then `w`	Choose window from list
`Ctrl+a` then `n`	Next window
`Ctrl+a` then `p`	Previous window

Pane Management

Key Binding	Description
`Ctrl+a` then `-`	Split window horizontally
`Ctrl+a` then `	`
`Ctrl+a` then `h`	Move to left pane
`Ctrl+a` then `j`	Move to bottom pane
`Ctrl+a` then `k`	Move to top pane
`Ctrl+a` then `l`	Move to right pane

Copy Mode (Vi-style)

Key Binding	Description
`Ctrl+a` then `[`	Enter copy mode
`v`	Start selection (in copy mode)
`y`	Copy selection (in copy mode)
`q`	Exit copy mode

💡 Tip: All panes and windows are created in the current working directory for better workflow.

📝 Neovim Settings (Optional)

Basic commands to get started:

vi - Launch Neovim
:q - Quit Neovim
:checkhealth - Check Neovim configuration
:Lazy - Plugin manager interface
Ctrl+P - Fuzzy file finder

🤖 Claude Code / Codex shared configuration

nanokit manages Claude Code's tool-specific settings and the global instructions/skills shared with Codex. Common content has one source; client-specific adapters remain in claude-settings.

Note

Claude Code and Codex themselves are installed separately. nanokit manages their portable configuration and shared files.

Setup

# Install Claude Code first
curl -fsSL https://claude.ai/install.sh | bash

# Setup configuration and plugins
./nanokit claude-setup

# Re-apply every configuration change (dotter symlinks + shared agent config)
./nanokit deploy --diff
./nanokit deploy

# Or re-apply only the shared agent configuration
./nanokit agent-config-sync --diff
./nanokit agent-config-sync

This will:

Symlink Claude-specific settings from nanokit/claude/ to ~/.claude/ with dotter.
Link claude/CLAUDE.md to ~/.codex/AGENTS.md.
Link every claude/skills/*/SKILL.md directory to both ~/.claude/skills/ and ~/.agents/skills/.
Upsert portable keys from codex/config.toml into the stateful ~/.codex/config.toml without touching host-specific sections.
Link nanokit-managed Codex command rules from codex/rules/*.rules into ~/.codex/rules/.
Register client-safe HTTP MCPs (scrapling, zotero, deepwiki) in both CLIs.
Register Claude Code plugin marketplaces and plugins.

Client-scoped MCPs such as workspace-hdt / workspace-personal are intentionally not added to Codex user scope; claude-settings selects them per project so organization credentials do not leak across clients.

Plugins

./nanokit claude-setup で自動インストールされます。別の環境で手動インストールする場合は以下を実行してください。

Step 1: マーケットプレイスの登録

claude plugin marketplace add affaan-m/everything-claude-code

Step 2: プラグインのインストール

claude plugin install everything-claude-code@everything-claude-code

Plugin	Marketplace (GitHub)	Description
everything-claude-code	affaan-m/everything-claude-code	Agent, skill, rule の包括的コレクション

What is managed

File	Description
`claude/settings.json`	Global settings (hooks, env vars, plugins, statusLine)
`claude/CLAUDE.md`	Global instructions for Claude Code and Codex
`claude/skills/*`	Shared skill sources for `~/.claude/skills` and `~/.agents/skills`
`codex/config.toml`	Portable Codex top-level settings
`codex/rules/*.rules`	Global Codex command rules linked into `~/.codex/rules/`
`codex/sync-config.py`	Safe, idempotent config/instruction/skill/rule synchronizer
`claude/scripts/zotero-mcp-server.sh`	Zotero MCP server lifecycle script

Plugin-managed files and runtime data remain outside this synchronization. A non-symlink path or a foreign symlink with the same skill name is treated as a collision and is never overwritten.

Post-setup

Configure machine-specific settings manually:

MCP servers: ~/.claude/mcp-configs/mcp-servers.json
Local overrides: ~/.claude/settings.local.json

📚 Zotero MCP (Optional)

zotero-mcp をマルチホスト対応で運用するためのサブコマンドです。Mac（Zotero.app 起動中）ではローカル API、Linux サーバー等（Zotero.app なし）では Web API に自動で切り替えます。

Note

Zotero MCP は ./nanokit install では導入されません。利用したい環境でのみ zotero-mcp-install を実行してください。

Install

新規マシンセットアップ後、API キーを対話的に登録:

./nanokit zotero-mcp-install

これにより以下が行われます:

claude/mcp-servers/zotero-mcp/pixi.toml から pixi env をインストール (zotero-mcp-server[semantic])
Zotero API key と userID を OS の secret store に登録（macOS Keychain / Linux secret-tool / fallback: ~/.config/nanokit/secrets.env）
Claude Code に MCP サーバー (HTTP transport, localhost:8321) を登録（冪等）
~/.claude/scripts/zotero-mcp-server.sh を再起動してヘルスチェック

API キーは https://www.zotero.org/settings/keys/new で発行してください（推奨パーミッション: library/notes access、write は OFF 推奨、file access は将来のために ON 推奨）。

動作モードの自動切替

実行環境	モード	取得可能なデータ
Zotero.app 起動中	`ZOTERO_LOCAL=true`	メタデータ + PDF 本体 + 注釈作成可
Zotero.app 停止中 / Linux 他	`ZOTERO_LOCAL=false`	メタデータ + フルテキスト（インデックス）+ ノート + タグ + semantic search

判定は curl http://localhost:23119/connector/ping の成否で自動。詳細は specs/zotero-mcp-multi-host-setup.md。

Update / Uninstall

./nanokit zotero-mcp-update      # pixi update + サーバー再起動
./nanokit zotero-mcp-uninstall   # pixi env 削除 + MCP client 解除 + credentials 削除（対話）

手動操作

bash ~/.claude/scripts/zotero-mcp-server.sh status
bash ~/.claude/scripts/zotero-mcp-server.sh stop
bash ~/.claude/scripts/zotero-mcp-server.sh start
tail -f ~/.claude/debug/zotero-mcp.log

🔐 Supply Chain Security (Cooldown)

To reduce the risk of installing recently-published (and potentially compromised) packages, nanokit ships release-age cooldown configs for npm and uv, managed by dotter.

A 7-day cooldown blocks the majority of real-world supply chain incidents, since compromised packages are typically caught and pulled within hours or days. See Package Managers Need to Cool Down and Dependency Cooldowns.

Tool	Config file	Setting	Min version
npm	`npmrc` → `$HOME/.npmrc`	`min-release-age=7` (days)	`npm v11.10.0+`
uv	`uv.toml` → `$HOME/.config/uv/uv.toml`	`exclude-newer = "7 days"`	`uv 0.11.2+`

⚠️ Pixi

Pixi's exclude-newer is currently workspace-only — it is not available in user-level ~/.pixi/config.toml (config reference). Add it manually to each project's pixi.toml | pyproject.toml:

[workspace]
exclude-newer = "7d"  # requires pixi v0.67.0+

This applies to both conda and PyPI packages within that workspace. For pixi global (i.e. pixi-global.toml), cooldown is not yet supported upstream.

🧪 Try nanokit in your OS

Want to test nanokit without affecting your current setup? Create a temporary user:

sudo adduser nanokit
su - nanokit
# Try nanokit setup here

Cleanup test user:

sudo userdel -r nanokit    # Remove user and home directory

References

Shell Tools を Rust 製に固めてｼﾝﾌﾟﾙに管理する

Name		Name	Last commit message	Last commit date
Latest commit History 207 Commits
.dotter		.dotter
.vscode		.vscode
claude		claude
codex		codex
docs		docs
lib		lib
nvim		nvim
specs		specs
tools/jarvislabs		tools/jarvislabs
wezterm		wezterm
zsh		zsh
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
README.md		README.md
bootstrap-lambda.sh		bootstrap-lambda.sh
gwq.toml		gwq.toml
nanokit		nanokit
npmrc		npmrc
pixi-global.toml		pixi-global.toml
pueue.yml		pueue.yml
setup_fonts.sh		setup_fonts.sh
sheldon.toml		sheldon.toml
starship.toml		starship.toml
tigrc		tigrc
tmux.conf		tmux.conf
uv.toml		uv.toml
zshenv		zshenv
zshrc		zshrc

Folders and files

Latest commit

History

Repository files navigation

🛠️ nanokit - minimal development environment

⚙️ Setup - All you need is pixi

Step 1: Install pixi

Step 2: Clone this repository

Step 3-a: nanokit install (recommended for new environment)

Step 3-b: Manual Installation (recommended for existing environment)

Install dotter

Symlink configuration files

Install utility tools

Start your 🐚 zsh

🔄 Reset All Environment

Step 4: Install fonts required for 🚀 starship (optional)

🎨 Customization

🛠️ Global Tools

🚀 Starship Settings

🎩 Zsh Plugins

🦀 Dotfiles Management

🚀 ghq + 🌲 gwq + 🌀 zoxide = ❤️

📦 Repository Management with ghq

🌀 Smart Navigation with zoxide

🌲 Worktree Management with gwq

🖥️ Tmux Key Bindings

Basic Commands

Window Management

Pane Management

Copy Mode (Vi-style)

📝 Neovim Settings (Optional)

🤖 Claude Code / Codex shared configuration

Setup

Plugins

What is managed

Post-setup

📚 Zotero MCP (Optional)

Install

動作モードの自動切替

Update / Uninstall

手動操作

🔐 Supply Chain Security (Cooldown)

⚠️ Pixi

🧪 Try nanokit in your OS

References

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages