pisces

Documentation | 中文文档

A terminal TUI launcher for AI coding agents — quickly open projects and agents from one place.

Features

• Keystroke-first search — type locationKey + agentKey prefixes to filter launch targets
• Agent combos — open a project directory and start an AI agent there in one keystroke
• Editor launch — open any location (or the current directory) in VS Code or another configured editor/IDE
• Subdirectory browsing — type locationKey + / to drill into a location
• Default launch — Ctrl+D opens your configured default path and command instantly
• Recent opens — Ctrl+R lists your last 10 launches (with open time) and re-opens any of them
• Self-update — pis self-update upgrades to the latest npm version

Installation

npm install -g @lysun001/pisces

Requires Node.js 22 or later. Then run:

pis

Quick Start

On first run, pisces automatically detects your installed agents and initializes the config for you. Configure your project directories and agents in ~/.pisces/settings.json:

{
  "locations": [
    {
      "name": "code",
      "path": "C:\\Users\\You\\Desktop\\code",
      "key": ["b", "beta"]
    }
  ],
  "agents": [
    {
      "name": "opencode",
      "command": "opencode",
      "key": ["oc", "open"]
    }
  ],
  "editors": [
    {
      "name": "VS Code",
      "command": "code",
      "key": "vscode"
    }
  ],
  "default": {
    "path": "C:\\Users\\You\\Desktop\\code",
    "command": "opencode"
  }
}

Type b to see the directory, boc to launch it with opencode, b/ to browse its subdirectories.

Documentation

The full documentation lives at neptune-constellation.github.io/pisces (中文):

• Installation
• Quick Start
• Configuration reference
• Search & keyboard shortcuts
• Subdirectory browsing
• Self-update
• FAQ

Development

This is a pnpm-workspace monorepo: apps/cli is the TUI launcher, apps/docs is the VitePress documentation site.

git clone https://github.com/neptune-constellation/pisces.git
cd pisces

pnpm install        # install dependencies for all packages
pnpm dev            # run the TUI in development mode
pnpm test           # run the CLI test suite
pnpm lint           # lint all packages
pnpm typecheck      # typecheck all packages
pnpm build          # build all packages
pnpm docs:dev       # preview the documentation site locally

License

MIT © lysun001