Pier

In-browser terminal for your *.localhost apps with Portless, mapped to the right repo automatically.

- "dev": "pnpm dev"
+ "dev": "pier myapp pnpm dev"  # http://myapp.localhost:1355

Website • Docs

Quick Start

# Install
npm install -g @malviyahimanshu/pier

# One-time setup (starts bridge + proxy, prints token + ws URL)
pier setup

# Run an app through a stable localhost hostname
pier myapp pnpm dev
# -> http://myapp.localhost:1355

Install the extension from Chrome Web Store:

• https://chromewebstore.google.com/detail/pier/gfhbagnaafeefbkjcocmpnepfggbbdpj

Open the app URL and press `Ctrl+`` to toggle the Pier panel.

Manual unpacked extension flow (optional):

pier extension install
pier extension path

Why Pier

When you build multiple apps or agents in parallel, context switching becomes expensive:

• Terminal sprawl: too many terminal windows tied to different repos
• Tab ambiguity: many localhost tabs with unclear workspace context
• Wrong-shell errors: commands run in the wrong directory
• Storage collisions: cookies/localStorage overlap across localhost apps

Pier keeps each project self-contained in one tab:

• app UI at a stable *.localhost hostname (via portless)
• in-page terminal panel (xterm.js + local bridge)
• hostname -> repo routing with session reuse

Usage

# Basic
pier myapp pnpm dev
# -> http://myapp.localhost:1355

# Subdomain-style apps
pier api.myapp pnpm dev
# -> http://api.myapp.localhost:1355

# Inspect routing
pier map list
pier map where myapp.localhost

package.json Script

{
  "scripts": {
    "dev": "pier myapp pnpm dev"
  }
}

How It Works

flowchart LR
    A["Browser tab\nmyapp.localhost:1355"] --> B["Pier extension\ncontent script + panel"]
    B --> C["Pier bridge\nlocalhost WebSocket server"]
    C --> D["Workspace registry\nhostname -> cwd"]
    D --> E["Shell session\npty/pipes in mapped repo"]

Loading

1. pier <name> <cmd...> wraps portless and records <name>.localhost -> cwd
2. Pier ensures the local bridge is running
3. Extension connects to the bridge (legacy token-compat by default, strict mode optional)
4. Bridge resolves the page hostname to a workspace path
5. Terminal session is created or reused in that workspace

Commands

pier <name> <cmd...>         # run app with mapping + bridge bootstrap

# Mapping
pier map list
pier map add <host.localhost> [cwd]
pier map remove <host.localhost>
pier map where <host.localhost>

# Bridge
pier bridge start [--foreground]
pier bridge stop
pier bridge status
pier bridge logs

# Extension & diagnostics
pier extension path
pier extension url
pier extension install [--force] [--version <x.y.z>] [--from <url-or-file>]
pier doctor
pier setup [--https] [--manual-extension]

Security

• Bridge binds to localhost by default (127.0.0.1)
• WebSocket token auth can be enforced with PIER_STRICT_TOKEN=1
• Extension only activates on localhost-style pages
• Bridge upgrade checks allow only localhost + extension origins

Development

pnpm install
pnpm run build
pnpm run check

Local loop:

pnpm run build:extension --watch
pnpm run typecheck
pnpm run test:unit
pnpm run test:smoke

Repo Layout

• packages/shared - shared validation, protocol, terminal settings
• packages/cli-core - CLI implementation and workspace routing registry
• packages/bridge-core - local WebSocket + terminal bridge server
• packages/extension-src - extension source (TS/TSX + static assets)
• extension/ - generated unpacked extension assets
• cli/, server/, bin/ - compatibility shims
• docs/ - source docs for users and contributors

Docs

Live docs: https://pier.himan.me/docs

Source docs in repo:

• Setup
• Usage
• Configuration
• Architecture
• Troubleshooting
• Contributing
• Release

Requirements

• Node.js 20+
• Chrome or Chromium (Manifest V3)

License

ISC