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

npm i -g hakonook

Or build from source (requires Bun):

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

macOS:

cp ./dist/hako ~/.local/bin/
codesign --sign - --force ~/.local/bin/hako

Linux:

cp ./dist/hako ~/.local/bin/

Windows (PowerShell):

New-Item -ItemType Directory -Force -Path "$env:LOCALAPPDATA\hako"
Copy-Item ./dist/hako.exe "$env:LOCALAPPDATA\hako\hako.exe"

Then add %LOCALAPPDATA%\hako to your PATH.

quick start

hako scan              # index your projects
hako                   # open interactive picker
hako create 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 file manager

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 info <project> — show detailed project information

hako info my-project         # show project details
hako info my-project --json  # machine-readable output

| option | description | |--------|-------------| | --json | output as JSON |

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

creation

hako create [name] — create a new project

hako create                        # launch wizard
hako create my-app                 # create blank project
hako create my-app -t sveltekit    # from template
hako create my-app -g user/repo    # clone from GitHub
hako create my-app --remote <url>  # clone from any git remote
hako create my-app -f other-proj   # fork from existing project
hako create my-app -s paused       # start as paused
hako create my-app --no-open       # don't open after

| option | description | |--------|-------------| | -t, --template <name> | use registered template | | -g, --github <repo> | clone from GitHub (user/repo or user/repo/subdir) | | --remote <url> | clone from any git remote URL | | -f, --fork <project> | create from an existing project | | --blank | create empty project with git init | | -s, --status <status> | initial status (default: active) | | --no-open | skip opening in IDE after creation |

status

hako update <name> — update project properties

hako update my-app -s paused       # pause the project
hako update my-app -s archived     # archive the project
hako update my-app -s active       # reactivate

| option | description | |--------|-------------| | -s, --status <status> | change status (active, paused, archived, stable) |

hako delete <name> — permanently delete a project

hako delete my-old-project         # delete with confirmation
hako delete my-old-project -f      # delete without confirmation

| option | description | |--------|-------------| | -f, --force | skip confirmation prompt |

Warns about uncommitted changes, unpushed commits, and missing remotes before deleting.

templates

hako template list — show registered templates

hako template add <name> — register a template

hako template add starter -g user/repo
hako template add gitlab --remote <url>
hako template add local-kit --local templates/kit

| option | description | |--------|-------------| | -g, --github <repo> | GitHub repository (user/repo or user/repo/subdir) | | --remote <url> | any git remote URL | | --local <path> | local template path |

hako template remove <name> — unregister a template

ai resources

hako ai — manage AI resources (skills, agents, prompts, MCP configs, snippets)

Run hako ai with no arguments to open an interactive browser.

hako ai list — list all resources

hako ai list                 # all resources
hako ai list --type skill    # filter by type
hako ai list --json          # machine-readable

| option | description | |--------|-------------| | --type <type> | filter by type (skill, agent, prompt, mcp, snippet) | | --json | output as JSON |

hako ai use <resource> — install a resource into the current project

hako ai use skill/my-skill
hako ai use my-agent

hako ai publish <path> — add a local resource to the library

hako ai publish .claude/skills/my-skill
hako ai publish .claude/agents/helper.md --description "Helper agent"

| option | description | |--------|-------------| | --description <text> | resource description | | --tags <tags> | comma-separated tags | | --type <type> | resource type (auto-detected if not specified) | | --name <name> | resource name (auto-detected if not specified) |

hako ai remove <resource> — remove a resource from the library

hako ai sync — sync the library with its git remote

hako ai init — initialize the AI resources library

hako ai init
hako ai init -g user/ai-resources
hako ai init --remote [email protected]:user/ai-resources.git

| option | description | |--------|-------------| | -g, --github <repo> | GitHub repository (user/repo) | | --remote <url> | git remote URL for syncing |

hako ai info — show library status

| option | description | |--------|-------------| | --json | output as JSON |

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 [project] — rebuild project index

hako scan                    # rescan all project directories
hako scan my-project         # scan single project for AI resources
hako scan --ai               # also detect AI resources
hako scan --ai --publish     # auto-publish all new AI resources

| option | description | |--------|-------------| | --ai | also detect AI resources across projects | | --publish | auto-publish all detected AI resources (use with --ai) |

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 path "$1")"; }

made with ♡