Developing Tarsk

This guide covers running the Tarsk monorepo locally. End users should use Installation instead.

Prerequisites

Bun (pinned in the repo)
git on your PATH

Clone and Install

git clone https://github.com/WebNativeLLC/tarsk.git
cd tarsk
bun install

Development Modes

Command	What it does
`bun run dev:web`	CLI server on 641 + app Vite on its default port. This command does not configure the frontend/API port pairing.
`cd cli && bun run dev`	Build app, start Electrobun desktop dev
`cd cli && bun run dev:web`	Debug API on port 462 + app Vite on 8100 (recommended for web development)
`bun run dev:app`	Frontend only (Vite default port; API calls go to the same origin). The 8100 frontend / 462 API pairing applies when the app is served on port 8100, for example via `cd cli && bun run dev:web`.
`bun run dev:docs`	Documentation site (Astro)
`bun run dev:cli`	CLI server with built assets

When you run the app on Vite port 8100, the frontend sends API requests to port 462 on the same hostname.

Dev Label

The sidebar shows a Dev label next to the Tarsk logo when the server is a development instance. The label follows the signals the development commands set — MODE=development (bun run web, bun run api-serve-462), TARSK_ELECTROBUN_DEV=1 (bun run dev, bun run dev:watch), or --debug. It is not triggered by a port fallback, so a released app that walks from 641 to 642 stays unlabelled.

Build

bun run build

Build order: shared → app → cli → postbuild (copies app/dist into the CLI public assets).

For npm publish without Electrobun native targets:

bun run build:npm

Quality Checks

bun run check:all

Runs lint, build, tests, and Vite Plus checks. bun run check:all now performs the signed desktop build path; use bun run check:all:unsigned when you need the full pipeline without codesigning or notarization, and bun run check:all:quiet for a one-line pass/fail summary.

Repository Layout

Directory	Purpose
`app/`	React frontend (Vite Plus)
`cli/`	Bun/Hono server, agent orchestration, Electrobun desktop shell
`shared/`	`@tarsk/shared` types, constants, utilities
`docs/`	This documentation site (Astro + Starlight)
`website/`	Marketing site
`mobile/`	Capacitor iOS/Android wrapper
`extensions/vscode/`	VS Code extension
`ai-data/`	Provider and model catalog data
`specs/`	Product specifications

Sync Model Data

bun run sync-models

Refreshes the model catalog in ai-data/. Full sync needs ARTIFICIAL_ANALYSIS_TOKEN.

VS Code Extension Development

cd extensions/vscode
bun install
bun run compile

In VS Code/Cursor, select Run Tarsk VS Code Extension and press F5.

AGENTS.md — contributor rules for agents
cli/README.md — published CLI reference