Introducing hawk: A Project Command Center for Your Terminal

If you're a developer who juggles more than a handful of projects, you've probably made peace with a set of small, daily annoyances. You cd into the wrong folder, you try to remember which GitHub account a repo belongs to, you open three browser tabs to check whether a deployment is live. Each friction is minor on its own. Together they add up to a lot of interrupted flow.

hawk is a Node.js CLI that fixes all of this. It keeps a registry of every project on your machine (local directories, GitHub repos, Vercel deployments) across as many accounts as you use. One command to jump to any project by name. One command to check its status. No browser required.

The problem with many projects

Most developers have their work spread across several folders. A typical setup might look something like this:

~/work/
  api-service/
  internal-dashboard/
  design-system/
~/clients/
  acme-corp/
    frontend/
    cms/
~/personal/
  portfolio/
  side-project/

None of this is wrong. It makes sense to organise by context. But the moment you need to jump between these contexts, things get tedious. You either keep a mental map of where everything lives, or you find around, or you open Finder. And when you get to a project, you still need to open a browser to see whether its CI is passing or its Vercel deployment is live.

The core problem isn't your folder structure. It's that your terminal has no shared memory of what your projects are. Every new session starts from zero.

Multiple accounts make it worse

If you work across a personal GitHub account, a work organisation, and one or two client accounts, the credential problem is compounded. GitHub CLI ties itself to a single account. The Vercel CLI does the same. Switching between them involves logging out and back in, or maintaining separate config files, or writing shell aliases that nobody can remember six months later.

hawk solves this with named profiles. You set up each account once (personal, work, client-acme) and hawk stores the tokens separately. Every project knows which profile it belongs to. hawk sync --profile work pulls only your work repos. No credential juggling.

Enter hawk

At its core, hawk does three things:

Registers projects by name. A .hawk JSON file in a project's root directory tells hawk the project's name, which account it belongs to, and optionally its GitHub repo, Vercel project, and dev server command.
Lets you navigate by name. Once the shell integration is active, hawk cd project-name takes you there from anywhere on your filesystem, with tab completion.
Surfaces status without leaving the terminal. hawk status shows open PRs, CI results, and last commit. hawk hosting shows your live Vercel deployment URL and last deploy time.

How it works under the hood

hawk stores a registry at ~/.hawk/registry.json, a flat index of every registered project, its path, profile, and linked services. When you run hawk scan ~/projects, hawk walks the directory tree looking for .hawk files and adds each one it finds.

The hawk cd command is a shell function rather than a binary command. This is because a subprocess can't change the working directory of its parent shell; it's a fundamental limitation of how Unix processes work. The shell integration snippet (loaded via eval "$(hawk shell-init)", or installed permanently with hawk shell-init --install) wraps the hawk binary in a function that intercepts the cd subcommand, calls hawk _resolve-path <name> internally to get the path, and then does the cd itself within the shell context.

Getting started in under a minute

Install hawk globally from npm:

$ npm install -g hawk-cli

Install the shell integration permanently so hawk cd and tab completion work in every new terminal:

$ hawk shell-init --install
✓ Installed hawk shell integration into ~/.zshrc
$ source ~/.zshrc

Scan your projects directory to register everything at once:

$ hawk scan ~/projects

  ✓  acme-frontend    ~/projects/acme-frontend
  ✓  api-service      ~/work/api-service
  ✓  design-system    ~/work/design-system
  ✓  my-portfolio     ~/personal/my-portfolio
  ───────────────────────────────────
  4 projects registered

Now jump to any of them by name:

~ $ hawk cd acme-frontend
acme-frontend $

The commands you'll actually use

hawk dashboard

A live table of every registered project, showing name, GitHub CI status, and Vercel deployment at a glance. You can select any project to drill into it.

~ $ hawk dashboard

  NAME              CI              DEPLOY
  ─────────────────────────────────────────────
  acme-frontend    ● passing      ▲ live
  api-service      ⚠ 2 open PRs  ▲ live
  design-system    ● passing      ·
  my-portfolio     ·               ▲ live

hawk status

Fetches the full GitHub status for a project (open PRs, CI result, and last commit message) without leaving the terminal.

~ $ hawk status acme-frontend

  acme-frontend  ·  github: acme/frontend
  CI:           passing
  Open PRs:     0
  Last commit:  feat: add dark mode toggle

hawk sync

Pulls all repos from GitHub and all deployments from Vercel for a given profile, and updates the registry. Useful when you've created new repos or projects that hawk doesn't know about yet.

hawk open

Opens a project in your editor, its GitHub page, its Vercel dashboard, or starts the dev server, all without remembering which command does what for which project.

What's next

hawk is at v0.1. It covers the core workflow well but there's more planned. Upcoming ideas include richer hawk dashboard filtering (by profile, by status), better hawk open browser integration, and a hawk log command that shows recent commits across all projects at once.

If you run into anything odd or have a feature you'd find useful, the repo is at github.com/3okash/hawk-cli. Issues and PRs are very welcome.

Try it now

One command to install. Under a minute to set up.

$npm install -g hawk-cli