hakonook

a cozy CLI for your local projects ✿

---

about

I built this for myself. It helps me keep track of scattered projects across my dev folder — what's active, what's on pause, what I forgot about months ago. Probably not for everyone, but if you tend to accumulate projects like I do, it might be useful.

The idea is simple: one root folder, projects organized by status, and a quick way to navigate between them.

---

concepts

root — your development folder (default: ~/development)

statuses — projects live in status folders:

• active — currently working on
• paused — taking a break
• archived — done or abandoned
• stable — shipped and maintained

index — cached metadata about your projects, auto-refreshes hourly

---

install

# clone and build
git clone https://github.com/chrisdevelops/hakonook.git
cd hakonook
bun install
bun run build

# add to path
cp ./dist/hako ~/.local/bin/

---

quick start

hako scan              # index your projects
hako                   # open interactive picker
hako new my-app        # create a project
hako code my-app       # open in IDE

---

interactive mode

Run hako with no arguments to open the TUI.

key	action
↑ ↓ j k	navigate
enter o	open in Finder
i	open in IDE
c	open in Claude Code
t	open terminal
a	archive project
p	pause project
n	new project wizard
/	search
?	help
q	quit

---

commands

navigation

hako — interactive project picker

hako list — list projects

hako list                    # all projects
hako list -s active          # filter by status
hako list --json             # machine-readable output

option	description
-s, --status <status>	filter by status
--json	output as JSON

hako open <name> — open project in Finder

hako code <name> — open project in IDE

hako claude <name> — open project in Claude Code

hako claude my-app           # default
hako claude my-app --yolo    # skip permissions
hako claude my-app -p custom # use custom profile

option	description
-p, --profile <name>	use named profile from config
--yolo	shortcut for --profile yolo

hako cd <name> — print project path (for shell integration)

---

creation

hako new [name] — create a new project

hako new                     # launch wizard
hako new my-app              # create blank project
hako new my-app -t sveltekit # from template
hako new my-app -g user/repo # clone from GitHub
hako new my-app -s paused    # start as paused
hako new my-app --no-open    # don't open after

option	description
-t, --template <name>	use registered template
-g, --github <repo>	clone from GitHub (user/repo)
--blank	create empty project with git init
-s, --status <status>	initial status (default: active)
--no-open	skip opening in IDE after creation

---

status

hako status <name> <status> — change project status

hako status my-app paused    # change to paused
hako status my-app active    # reactivate

hako activate <name> — shortcut for status <name> active

hako pause <name> — shortcut for status <name> paused

hako archive <name> — shortcut for status <name> archived

---

templates

hako template list — show registered templates

hako template add <name> — register a template

hako template add starter --github user/repo
hako template add local-kit --local templates/kit

option	description
--github <repo>	GitHub repository (user/repo)
--local <path>	local template path

hako template remove <name> — unregister a template

---

processes

hako process run <project> [script] — run a script

hako process run my-app          # run default (dev)
hako process run my-app start    # run specific script
hako process run my-app -b       # run in background
hako process run my-app -l       # list available scripts

option	description
-b, --background	run detached, track process
-l, --list	list available scripts

hako process list — show tracked processes (TUI)

hako process list            # interactive
hako process list --json     # machine-readable
hako process list -a         # include dead processes

option	description
--json	output as JSON
-a, --all	show all including stopped

hako process kill <target> — stop a process

hako process kill my-app     # by project name
hako process kill 12345      # by PID
hako process kill my-app -f  # force kill

option	description
-s, --signal <signal>	signal to send (default: SIGTERM)
-f, --force	use SIGKILL

hako ps — alias for process list

---

maintenance

hako scan — rebuild project index

hako stale — find inactive projects

hako stale                   # 30+ days inactive
hako stale -d 60             # 60+ days inactive
hako stale --json            # machine-readable

option	description
-d, --days <n>	days threshold (default: 30)
--json	output as JSON

hako doctor — health check

hako doctor                  # run all checks
hako doctor --json           # machine-readable

Checks config validity, root directory, status folders, index freshness, git initialization, and active project count.

---

configuration

hako config show — display current config

hako config edit — open config in editor

hako config set <key> <value> — set a config value

hako config set root ~/projects
hako config set default_ide code
hako config set active_limit 10

hako config path — print config file path

---

configuration

Config file: ~/.config/hako/config.toml

# where your projects live
root = "~/development"

# IDE command
default_ide = "cursor"

# warn when active projects exceed this
active_limit = 5

[editor]
command = "cursor"

[github]
username = ""

[claude_code]
command = "claude"
default_args = []

[claude_code.profiles]
yolo = ["--dangerously-skip-permissions"]

[statuses]
active = "active"
paused = "paused"
archived = "archived"
stable = "stable"

[processes]
log_dir = "~/.config/hako/logs"
capture_output = false
default_script = "dev"

[templates]
# add your own templates here
# starter = { type = "github", repo = "user/repo" }

---

shell integration

Add to your .zshrc or .bashrc:

# cd to a project by name
hcd() { cd "$(hako cd "$1")"; }

---

made with ♡