termcode

termcode is a small macOS CLI for finding local repos, opening them, and running package scripts without remembering where every repo lives.

Why termcode?

AI has changed how I work on code. I spend less time manually navigating an editor and more time running local projects from a multi-tabbed terminal.

termcode exists so I do not have to remember where every repo lives. Configure your project folders once, then list repos, open them, or run package scripts by name.

Usage

termcode
termcode runner set pnpm
termcode set ~/Documents/code ~/Desktop/projects
termcode ls
termcode update
termcode my-app
termcode my-app dev
termcode my-app dev-2
termcode my-app run dev
termcode my-app bun run dev
termcode my-app bun install
termcode open my-app
termcode . my-app
termcode rename my-long-repo-name my-app

termcode set saves the roots to ${TERMCODE_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/termcode}/roots. Aliases created by termcode rename are saved to aliases in the same directory, and your preferred runner is saved to runner.

First Run

Run termcode with no arguments to start onboarding:

Welcome to termcode.

Step 1: Choose your preferred runner
  1. bun run
  2. pnpm run
  3. npm run
  4. yarn run
  5. none

Step 2: Add project directories
  Example: ~/Documents/code ~/Desktop/projects

After each directory step, termcode lists the projects it found and lets you add another directory or proceed.

Preferred Runner

The preferred runner is the package runner termcode uses when you run a script by name:

termcode runner set pnpm
termcode my-app dev
termcode my-app run dev

Both script forms run:

pnpm run dev

To clear it:

termcode runner clear

If no preferred runner is set, provide one in the command:

termcode my-app bun run dev
termcode my-app pnpm run dev
termcode my-app npm run dev
termcode my-app yarn run dev

You can also run package-manager commands inside a project:

termcode my-app bun install
termcode my-app pnpm add react

If you type a script name that is not in the project package.json, termcode prints the available script names for that project before exiting. When you run only termcode my-app in an interactive terminal, it still prints the project path and also shows the scripts you can run next.

Jump Workflow

Without shell integration, termcode <project> prints the project path:

termcode my-app
termcode path my-app

To make termcode my-app change your current shell directory in zsh, add this to your shell config:

eval "$(termcode init zsh)"

A standalone CLI cannot change its parent shell directory, so the shell integration wraps the binary and runs cd "$(command termcode path my-app)" for one-argument project jumps. The same zsh integration also enables tab completion for project names, aliases, and package scripts.

Install

curl -fsSL https://raw.githubusercontent.com/ishaqyusuf/termcode/main/install.sh | bash

By default, the installer puts termcode at:

~/.local/bin/termcode

To choose another install location:

curl -fsSL https://raw.githubusercontent.com/ishaqyusuf/termcode/main/install.sh | sudo env TERMCODE_INSTALL_DIR=/usr/local/bin bash

Use sudo only for system-owned directories like /usr/local/bin.

Update

Check whether a newer version is available:

termcode update

Rerun the installer to update termcode. It overwrites the existing binary with the latest version from main.

curl -fsSL https://raw.githubusercontent.com/ishaqyusuf/termcode/main/install.sh | bash

If you installed to /usr/local/bin, update with the same install directory:

curl -fsSL https://raw.githubusercontent.com/ishaqyusuf/termcode/main/install.sh | sudo env TERMCODE_INSTALL_DIR=/usr/local/bin bash

Install From Source

git clone https://github.com/ishaqyusuf/termcode.git
cd termcode
./install.sh

To install from a local clone into another directory:

TERMCODE_INSTALL_DIR=/usr/local/bin ./install.sh

To install from another branch or tag with curl:

curl -fsSL https://raw.githubusercontent.com/ishaqyusuf/termcode/main/install.sh | TERMCODE_REF=v0.2.1 bash

For forks, pass TERMCODE_REPO_OWNER and TERMCODE_REPO_NAME to the bash command.

Homebrew Preparation

A formula template lives at packaging/homebrew/termcode.rb.template. After tagging a release, replace the placeholder repository URL and checksum, then publish it through a tap.

Project Discovery Rule

Discovery is intentionally simple:

• search only the roots configured with termcode set
• include only direct child folders
• include only folders containing package.json
• list callable names alphabetically
• report duplicate callable names instead of guessing

Commands

termcode set <paths...>
termcode ls
termcode runner get
termcode runner set <bun|pnpm|npm|yarn|none>
termcode runner clear
termcode update
termcode rename <current-name-or-path> <new-alias>
termcode path <project>
termcode init zsh
termcode open <project>
termcode . <project>
termcode <project> <script> [args...]
termcode <project> run <script> [args...]
termcode <project> <runner> run <script> [args...]
termcode <project> <runner> <command> [args...]

Script execution uses your preferred runner, run as the second word uses your preferred runner explicitly, and a named runner can execute package-manager commands inside the project. Invalid script names fail before invoking the runner and show the scripts from that project's package.json.

Development

./bin/termcode --help
./bin/termcode --version
./tests/run.sh

See brain/PROJECT_INDEX.md and brain/tasks/backlog.md for future work.