CLI-first launcher and local dashboard for starting, stopping, and watching a set of development apps. It is built with Bun, Svelte, and Vite, and is intended for a single-user localhost workflow.

bunrun binds to localhost and has no authentication. It runs shell commands from data/projects.yaml as your user with no sandboxing, so only point it at projects and commands you already trust.

• Launches a project by a short, unambiguous query (bunrun aud resolves audigest). Exact id/name/alias, unique prefix, token-prefix, then conservative fuzzy matching are tried in that order.
• Starts its localhost service in the background on first use. That service owns project process trees, logs, and the dashboard after the invoking CLI exits.
• Attaches interactive terminals to buffered and live output by default; scripts, Spotlight, and redirected shells detach by default.
• Keeps your dev projects in one sidebar with favicons, paths, and status dots.
• Starts, stops, and restarts each configured process.
• Streams stdout and stderr into the main pane with ANSI colors.
• Watches data/projects.yaml, so agent-generated config updates show up while the app is running.
• Can open detected app URLs after startup when a process exposes one.
• Includes UI for manually adding and editing projects, processes, and .env files.

Install dependencies:

bun install

Create project config with the bundled agent skill:

Use SKILL.md to discover/register my projects for bunrun.
Scan ~/koodi with max depth 1.

The skill writes data/projects.yaml, preserving user-owned UI state on rescans. It can scan one project directory or a parent directory containing many projects.

Build the dashboard once and expose the launcher on your PATH:

bun run build
bun link

bun link installs the package's bunrun executable into Bun's global bin directory. Ensure that directory is on PATH (bun pm bin -g prints it). A plain symlink is also sufficient:

mkdir -p ~/.local/bin
ln -sf "$PWD/bin/bunrun" ~/.local/bin/bunrun

Now launch by project id, name, alias, or a unique abbreviation:

bunrun aud
bunrun tal-web --detach
bunrun logs audigest

The first command starts the service silently with dashboard auto-open disabled. The API listens on 127.0.0.1:3939; subsequent commands reuse it.

bunrun <query> [--attach|--detach] [--quiet] [--no-open]
bunrun logs <query> [--history N]
bunrun stop <query>
bunrun restart <query> [--attach|--detach] [--no-open]
bunrun status
bunrun list
bunrun ui [query]
bunrun shutdown

When stdin and stdout are terminals, launch/restart attaches after starting. Otherwise it detaches and exits while the service keeps the project running. --attach and --detach override that choice; --quiet suppresses launcher messages, and --no-open suppresses browser opening for that invocation. This is suitable for noninteractive callers:

bunrun aud --detach --quiet

An attached terminal first receives roughly 100 buffered lines, then live output without stripping ANSI color. Multi-process projects get process-name prefixes. Press Escape to detach and leave the project running, Ctrl-C to stop all of its processes, or o to surface its app/dashboard. A closed terminal or lost connection only detaches.

Launching an already-running project surfaces its known primary URL. If no URL is known, it opens the dashboard focused on that project. bunrun ui [query] always opens the dashboard, while bunrun logs never launches or opens anything.

The service records its PID and background output in ignored local files under data/ (bunrun.pid and bunrun.log). CLI bootstrap uses an atomic lock in the same directory to prevent concurrent callers from starting duplicate services. bunrun shutdown stops all project process trees before stopping the service.

Run the Bun API and Vite UI together:

bunrun shutdown
bun run dev

In development the API remains on 127.0.0.1:3939 and Vite serves the UI on http://localhost:3940.

data/projects.yaml is the source of truth. A minimal entry looks like this:

- id: my-app
  name: My App
  aliases: [app]
  path: /Users/you/koodi/my-app
  category: null
  favicon: public/favicon.ico
  envFile: .env
  processes:
    - name: dev
      command: bun run dev
      cwd: null
      port: 5173
      url: null
      urlPattern: null
      openOnStart: true
  ui:
    pinned: false
    logEnabled: false

The process command is run as a shell string from the project directory, so commands such as bun run dev, npm run dev, environment prefixes, pipes, and && chains work as written.

• bun run dev starts the Bun server and Vite UI for development.
• bun run build builds the Svelte frontend.
• bun run bunrun -- <args> runs the CLI without installing it.
• bun run service starts the foreground service directly (mostly for debugging).
• bun test runs server and CLI unit tests.
• bun run typecheck runs TypeScript and Svelte checks.
• bun run lint checks formatting with Prettier.

MIT — see LICENSE.